1 /* 2 * netlink/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-2006 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 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /** 22 * @ingroup cache 23 * @defgroup cache_api Cache Implementation 24 * @brief 25 * 26 * @par 1) Cache Definition 27 * @code 28 * struct nl_cache_ops my_cache_ops = { 29 * .co_name = "route/link", 30 * .co_protocol = NETLINK_ROUTE, 31 * .co_hdrsize = sizeof(struct ifinfomsg), 32 * .co_obj_ops = &my_obj_ops, 33 * }; 34 * @endcode 35 * 36 * @par 2) 37 * @code 38 * // The simplest way to fill a cache is by providing a request-update 39 * // function which must trigger a complete dump on the kernel-side of 40 * // whatever the cache covers. 41 * static int my_request_update(struct nl_cache *cache, 42 * struct nl_sock *socket) 43 * { 44 * // In this example, we request a full dump of the interface table 45 * return nl_rtgen_request(socket, RTM_GETLINK, AF_UNSPEC, NLM_F_DUMP); 46 * } 47 * 48 * // The resulting netlink messages sent back will be fed into a message 49 * // parser one at a time. The message parser has to extract all relevant 50 * // information from the message and create an object reflecting the 51 * // contents of the message and pass it on to the parser callback function 52 * // provide which will add the object to the cache. 53 * static int my_msg_parser(struct nl_cache_ops *ops, struct sockaddr_nl *who, 54 * struct nlmsghdr *nlh, struct nl_parser_param *pp) 55 * { 56 * struct my_obj *obj; 57 * 58 * obj = my_obj_alloc(); 59 * obj->ce_msgtype = nlh->nlmsg_type; 60 * 61 * // Parse the netlink message and continue creating the object. 62 * 63 * err = pp->pp_cb((struct nl_object *) obj, pp); 64 * if (err < 0) 65 * goto errout; 66 * } 67 * 68 * struct nl_cache_ops my_cache_ops = { 69 * ... 70 * .co_request_update = my_request_update, 71 * .co_msg_parser = my_msg_parser, 72 * }; 73 * @endcode 74 * 75 * @par 3) Notification based Updates 76 * @code 77 * // Caches can be kept up-to-date based on notifications if the kernel 78 * // sends out notifications whenever an object is added/removed/changed. 79 * // 80 * // It is trivial to support this, first a list of groups needs to be 81 * // defined which are required to join in order to receive all necessary 82 * // notifications. The groups are separated by address family to support 83 * // the common situation where a separate group is used for each address 84 * // family. If there is only one group, simply specify AF_UNSPEC. 85 * static struct nl_af_group addr_groups[] = { 86 * { AF_INET, RTNLGRP_IPV4_IFADDR }, 87 * { AF_INET6, RTNLGRP_IPV6_IFADDR }, 88 * { END_OF_GROUP_LIST }, 89 * }; 90 * 91 * // In order for the caching system to know the meaning of each message 92 * // type it requires a table which maps each supported message type to 93 * // a cache action, e.g. RTM_NEWADDR means address has been added or 94 * // updated, RTM_DELADDR means address has been removed. 95 * static struct nl_cache_ops rtnl_addr_ops = { 96 * ... 97 * .co_msgtypes = { 98 * { RTM_NEWADDR, NL_ACT_NEW, "new" }, 99 * { RTM_DELADDR, NL_ACT_DEL, "del" }, 100 * { RTM_GETADDR, NL_ACT_GET, "get" }, 101 * END_OF_MSGTYPES_LIST, 102 * }, 103 * .co_groups = addr_groups, 104 * }; 105 * 106 * // It is now possible to keep the cache up-to-date using the cache manager. 107 * @endcode 108 * @{ 109 */ 110 111 enum { 112 NL_ACT_UNSPEC, 113 NL_ACT_NEW, 114 NL_ACT_DEL, 115 NL_ACT_GET, 116 NL_ACT_SET, 117 NL_ACT_CHANGE, 118 __NL_ACT_MAX, 119 }; 120 121 #define NL_ACT_MAX (__NL_ACT_MAX - 1) 122 123 #define END_OF_MSGTYPES_LIST { -1, -1, NULL } 124 125 /** 126 * Message type to cache action association 127 */ 128 struct nl_msgtype 129 { 130 /** Netlink message type */ 131 int mt_id; 132 133 /** Cache action to take */ 134 int mt_act; 135 136 /** Name of operation for human-readable printing */ 137 char * mt_name; 138 }; 139 140 /** 141 * Address family to netlink group association 142 */ 143 struct nl_af_group 144 { 145 /** Address family */ 146 int ag_family; 147 148 /** Netlink group identifier */ 149 int ag_group; 150 }; 151 152 #define END_OF_GROUP_LIST AF_UNSPEC, 0 153 154 struct nl_parser_param 155 { 156 int (*pp_cb)(struct nl_object *, struct nl_parser_param *); 157 void * pp_arg; 158 }; 159 160 /** 161 * Cache Operations 162 */ 163 struct nl_cache_ops 164 { 165 char * co_name; 166 167 int co_hdrsize; 168 int co_protocol; 169 struct nl_af_group * co_groups; 170 171 /** 172 * Called whenever an update of the cache is required. Must send 173 * a request message to the kernel requesting a complete dump. 174 */ 175 int (*co_request_update)(struct nl_cache *, struct nl_sock *); 176 177 /** 178 * Called whenever a message was received that needs to be parsed. 179 * Must parse the message and call the paser callback function 180 * (nl_parser_param) provided via the argument. 181 */ 182 int (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *, 183 struct nlmsghdr *, struct nl_parser_param *); 184 185 struct nl_object_ops * co_obj_ops; 186 187 struct nl_cache_ops *co_next; 188 struct nl_cache *co_major_cache; 189 struct genl_ops * co_genl; 190 struct nl_msgtype co_msgtypes[]; 191 }; 192 193 /** @} */ 194 195 #ifdef __cplusplus 196 } 197 #endif 198 199 #endif 200