libnl
3.2.7
Main Page
Related Pages
Modules
Data Structures
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-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
/**
155
* Parser parameters
156
*
157
* This structure is used to configure what kind of parser to use
158
* when parsing netlink messages to create objects.
159
*/
160
struct
nl_parser_param
161
{
162
/** Function to parse netlink messages into objects */
163
int (*
pp_cb
)(
struct
nl_object
*,
struct
nl_parser_param
*);
164
165
/** Arbitary argument to be passed to the parser */
166
void
*
pp_arg
;
167
};
168
169
/**
170
* Cache Operations
171
*
172
* This structure defines the characterstics of a cache type. It contains
173
* pointers to functions which implement the specifics of the object type
174
* the cache can hold.
175
*/
176
struct
nl_cache_ops
177
{
178
/** Name of cache type (must be unique) */
179
char
*
co_name
;
180
181
/** Size of family specific netlink header */
182
int
co_hdrsize
;
183
184
/** Netlink protocol */
185
int
co_protocol
;
186
187
/** Group definition */
188
struct
nl_af_group
*
co_groups
;
189
190
/**
191
* Called whenever an update of the cache is required. Must send
192
* a request message to the kernel requesting a complete dump.
193
*/
194
int (*
co_request_update
)(
struct
nl_cache *,
struct
nl_sock *);
195
196
/**
197
* Called whenever a message was received that needs to be parsed.
198
* Must parse the message and call the paser callback function
199
* (nl_parser_param) provided via the argument.
200
*/
201
int (*
co_msg_parser
)(
struct
nl_cache_ops
*,
struct
sockaddr_nl *,
202
struct
nlmsghdr *,
struct
nl_parser_param
*);
203
204
/**
205
* Called whenever a notification has been parsed into an object and
206
* is considered for inclusion into a cache. Must return NL_SKIP if
207
* the object should not be included in the cache.
208
*/
209
int (*
co_event_filter
)(
struct
nl_cache *,
struct
nl_object
*obj);
210
211
/** Object operations */
212
struct
nl_object_ops
*
co_obj_ops
;
213
214
/** Internal, do not touch! */
215
struct
nl_cache_ops
*
co_next
;
216
217
struct
nl_cache *co_major_cache;
218
struct
genl_ops
* co_genl;
219
220
/* Message type definition */
221
struct
nl_msgtype
co_msgtypes[];
222
};
223
224
/** @} */
225
226
#ifdef __cplusplus
227
}
228
#endif
229
230
#endif
include
netlink
cache-api.h
Generated on Sat Jun 30 2012 15:19:09 for libnl by
1.8.1.1