1 /* 2 * netlink-private/cache-api.h Caching API 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation version 2.1 7 * of the License. 8 * 9 * Copyright (c) 2003-2013 Thomas Graf <tgraf@suug.ch> 10 */ 11 12 #ifndef NETLINK_CACHE_API_H_ 13 #define NETLINK_CACHE_API_H_ 14 15 #include <netlink/netlink.h> 16 #include <netlink/cache.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** 23 * @ingroup cache 24 * @defgroup cache_api Cache Implementation 25 * @brief 26 * 27 * @par 1) Cache Definition 28 * @code 29 * struct nl_cache_ops my_cache_ops = { 30 * .co_name = "route/link", 31 * .co_protocol = NETLINK_ROUTE, 32 * .co_hdrsize = sizeof(struct ifinfomsg), 33 * .co_obj_ops = &my_obj_ops, 34 * }; 35 * @endcode 36 * 37 * @par 2) 38 * @code 39 * // The simplest way to fill a cache is by providing a request-update 40 * // function which must trigger a complete dump on the kernel-side of 41 * // whatever the cache covers. 42 * static int my_request_update(struct nl_cache *cache, 43 * struct nl_sock *socket) 44 * { 45 * // In this example, we request a full dump of the interface table 46 * return nl_rtgen_request(socket, RTM_GETLINK, AF_UNSPEC, NLM_F_DUMP); 47 * } 48 * 49 * // The resulting netlink messages sent back will be fed into a message 50 * // parser one at a time. The message parser has to extract all relevant 51 * // information from the message and create an object reflecting the 52 * // contents of the message and pass it on to the parser callback function 53 * // provide which will add the object to the cache. 54 * static int my_msg_parser(struct nl_cache_ops *ops, struct sockaddr_nl *who, 55 * struct nlmsghdr *nlh, struct nl_parser_param *pp) 56 * { 57 * struct my_obj *obj; 58 * 59 * obj = my_obj_alloc(); 60 * obj->ce_msgtype = nlh->nlmsg_type; 61 * 62 * // Parse the netlink message and continue creating the object. 63 * 64 * err = pp->pp_cb((struct nl_object *) obj, pp); 65 * if (err < 0) 66 * goto errout; 67 * } 68 * 69 * struct nl_cache_ops my_cache_ops = { 70 * ... 71 * .co_request_update = my_request_update, 72 * .co_msg_parser = my_msg_parser, 73 * }; 74 * @endcode 75 * 76 * @par 3) Notification based Updates 77 * @code 78 * // Caches can be kept up-to-date based on notifications if the kernel 79 * // sends out notifications whenever an object is added/removed/changed. 80 * // 81 * // It is trivial to support this, first a list of groups needs to be 82 * // defined which are required to join in order to receive all necessary 83 * // notifications. The groups are separated by address family to support 84 * // the common situation where a separate group is used for each address 85 * // family. If there is only one group, simply specify AF_UNSPEC. 86 * static struct nl_af_group addr_groups[] = { 87 * { AF_INET, RTNLGRP_IPV4_IFADDR }, 88 * { AF_INET6, RTNLGRP_IPV6_IFADDR }, 89 * { END_OF_GROUP_LIST }, 90 * }; 91 * 92 * // In order for the caching system to know the meaning of each message 93 * // type it requires a table which maps each supported message type to 94 * // a cache action, e.g. RTM_NEWADDR means address has been added or 95 * // updated, RTM_DELADDR means address has been removed. 96 * static struct nl_cache_ops rtnl_addr_ops = { 97 * ... 98 * .co_msgtypes = { 99 * { RTM_NEWADDR, NL_ACT_NEW, "new" }, 100 * { RTM_DELADDR, NL_ACT_DEL, "del" }, 101 * { RTM_GETADDR, NL_ACT_GET, "get" }, 102 * END_OF_MSGTYPES_LIST, 103 * }, 104 * .co_groups = addr_groups, 105 * }; 106 * 107 * // It is now possible to keep the cache up-to-date using the cache manager. 108 * @endcode 109 * @{ 110 */ 111 112 #define END_OF_MSGTYPES_LIST { -1, -1, NULL } 113 114 /** 115 * Message type to cache action association 116 */ 117 struct nl_msgtype 118 { 119 /** Netlink message type */ 120 int mt_id; 121 122 /** Cache action to take */ 123 int mt_act; 124 125 /** Name of operation for human-readable printing */ 126 char * mt_name; 127 }; 128 129 /** 130 * Address family to netlink group association 131 */ 132 struct nl_af_group 133 { 134 /** Address family */ 135 int ag_family; 136 137 /** Netlink group identifier */ 138 int ag_group; 139 }; 140 141 #define END_OF_GROUP_LIST AF_UNSPEC, 0 142 143 /** 144 * Parser parameters 145 * 146 * This structure is used to configure what kind of parser to use 147 * when parsing netlink messages to create objects. 148 */ 149 struct nl_parser_param 150 { 151 /** Function to parse netlink messages into objects */ 152 int (*pp_cb)(struct nl_object *, struct nl_parser_param *); 153 154 /** Arbitary argument to be passed to the parser */ 155 void * pp_arg; 156 }; 157 158 /** 159 * Cache Operations 160 * 161 * This structure defines the characterstics of a cache type. It contains 162 * pointers to functions which implement the specifics of the object type 163 * the cache can hold. 164 */ 165 struct nl_cache_ops 166 { 167 /** Name of cache type (must be unique) */ 168 char * co_name; 169 170 /** Size of family specific netlink header */ 171 int co_hdrsize; 172 173 /** Netlink protocol */ 174 int co_protocol; 175 176 /** cache object hash size **/ 177 int co_hash_size; 178 179 /** cache flags */ 180 unsigned int co_flags; 181 182 /** Reference counter */ 183 unsigned int co_refcnt; 184 185 /** Group definition */ 186 struct nl_af_group * co_groups; 187 188 /** 189 * Called whenever an update of the cache is required. Must send 190 * a request message to the kernel requesting a complete dump. 191 */ 192 int (*co_request_update)(struct nl_cache *, struct nl_sock *); 193 194 /** 195 * Called whenever a message was received that needs to be parsed. 196 * Must parse the message and call the paser callback function 197 * (nl_parser_param) provided via the argument. 198 */ 199 int (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *, 200 struct nlmsghdr *, struct nl_parser_param *); 201 202 /** 203 * The function registered under this callback is called after a 204 * netlink notification associated with this cache type has been 205 * parsed into an object and is being considered for inclusio into 206 * the specified cache. 207 * 208 * The purpose of this function is to filter out notifications 209 * which should be ignored when updating caches. 210 * 211 * The function must return NL_SKIP to prevent the object from 212 * being included, or NL_OK to include it. 213 * 214 * @code 215 * int my_filter(struct nl_cache *cache, struct nl_object *obj) 216 * { 217 * if (reason_to_not_include_obj(obj)) 218 * return NL_SKIP; 219 * 220 * return NL_OK; 221 * } 222 * @endcode 223 */ 224 int (*co_event_filter)(struct nl_cache *, struct nl_object *obj); 225 226 /** 227 * The function registered under this callback is called when an 228 * object formed from a notification event needs to be included in 229 * a cache. 230 * 231 * For each modified object, the change callback \c change_cb must 232 * be called with the \c data argument provided. 233 * 234 * If no function is registered, the function nl_cache_include() 235 * will be used for this purpose. 236 * 237 * @see nl_cache_include() 238 */ 239 int (*co_include_event)(struct nl_cache *cache, struct nl_object *obj, 240 change_func_t change_cb, change_func_v2_t change_cb_v2, 241 void *data); 242 243 void (*reserved_1)(void); 244 void (*reserved_2)(void); 245 void (*reserved_3)(void); 246 void (*reserved_4)(void); 247 void (*reserved_5)(void); 248 void (*reserved_6)(void); 249 void (*reserved_7)(void); 250 void (*reserved_8)(void); 251 252 /** Object operations */ 253 struct nl_object_ops * co_obj_ops; 254 255 /** Internal, do not touch! */ 256 struct nl_cache_ops *co_next; 257 258 struct nl_cache *co_major_cache; 259 struct genl_ops * co_genl; 260 261 /* Message type definition */ 262 struct nl_msgtype co_msgtypes[]; 263 }; 264 265 /** @} */ 266 267 #ifdef __cplusplus 268 } 269 #endif 270 271 #endif 272