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