libnl
3.2.11
Main Page
Related Pages
Modules
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
*/
130
struct
nl_msgtype
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
*/
145
struct
nl_af_group
146
{
147
/** Address family */
148
int
ag_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
*/
162
struct
nl_parser_param
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
*/
178
struct
nl_cache_ops
179
{
180
/** Name of cache type (must be unique) */
181
char
*
co_name
;
182
183
/** Size of family specific netlink header */
184
int
co_hdrsize
;
185
186
/** Netlink protocol */
187
int
co_protocol
;
188
189
/** Group definition */
190
struct
nl_af_group
*
co_groups
;
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 */
247
struct
nl_object_ops
*
co_obj_ops
;
248
249
/** Internal, do not touch! */
250
struct
nl_cache_ops
*
co_next
;
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
include
netlink
cache-api.h
Generated on Wed Jun 13 2012 19:05:25 for libnl by
1.8.1.1