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