libnl  1.1.4
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_handle *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  */
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  */
144 {
145  /** Address family */
147 
148  /** Netlink group identifier */
149  int ag_group;
150 };
151 
152 #define END_OF_GROUP_LIST AF_UNSPEC, 0
153 
155 {
156  int (*pp_cb)(struct nl_object *, struct nl_parser_param *);
157  void * pp_arg;
158 };
159 
160 /**
161  * Cache Operations
162  */
164 {
165  char * co_name;
166 
167  int co_hdrsize;
168  int co_protocol;
169 
170  struct nl_af_group * co_groups;
171 
172  /**
173  * Called whenever an update of the cache is required. Must send
174  * a request message to the kernel requesting a complete dump.
175  */
176  int (*co_request_update)(struct nl_cache *, struct nl_handle *);
177 
178  /**
179  * Called whenever a message was received that needs to be parsed.
180  * Must parse the message and call the paser callback function
181  * (nl_parser_param) provided via the argument.
182  */
183  int (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *,
184  struct nlmsghdr *, struct nl_parser_param *);
185 
186  struct nl_object_ops * co_obj_ops;
187 
188  struct nl_cache_ops *co_next;
189  struct nl_cache *co_major_cache;
190  struct genl_ops * co_genl;
191 
192  /** Reference counter */
193  unsigned int co_refcnt;
194 
195  void (*unused1)(void);
196  void (*unused2)(void);
197  void (*unused3)(void);
198  void (*unused4)(void);
199  void (*unused5)(void);
200  void (*unused6)(void);
201  void (*unused7)(void);
202  void (*unused8)(void);
203 
204  struct nl_msgtype co_msgtypes[];
205 };
206 
207 extern void nl_cache_ops_get(struct nl_cache_ops *);
208 extern void nl_cache_ops_put(struct nl_cache_ops *);
209 
210 /** @} */
211 
212 #ifdef __cplusplus
213 }
214 #endif
215 
216 #endif
Message type to cache action association.
Definition: cache-api.h:128
char * mt_name
Name of operation for human-readable printing.
Definition: cache-api.h:137
int(* co_request_update)(struct nl_cache *, struct nl_handle *)
Called whenever an update of the cache is required.
Definition: cache-api.h:176
int mt_act
Cache action to take.
Definition: cache-api.h:134
void nl_cache_ops_get(struct nl_cache_ops *)
Increment reference counter.
Definition: cache_mngt.c:45
Netlink message header.
int(* co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *, struct nlmsghdr *, struct nl_parser_param *)
Called whenever a message was received that needs to be parsed.
Definition: cache-api.h:183
int ag_family
Address family.
Definition: cache-api.h:146
void nl_cache_ops_put(struct nl_cache_ops *)
Decrement reference counter.
Definition: cache_mngt.c:54
unsigned int co_refcnt
Reference counter.
Definition: cache-api.h:193
Cache Operations.
Definition: cache-api.h:163
Generic Netlink Operations.
Definition: mngt.h:57
Object Operations.
Definition: object-api.h:254
int ag_group
Netlink group identifier.
Definition: cache-api.h:149
Netlink socket address.
Definition: netlink-kernel.h:8
int mt_id
Netlink message type.
Definition: cache-api.h:131
Address family to netlink group association.
Definition: cache-api.h:143