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
18extern "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
111enum {
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 */
128struct 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 */
143struct 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
154struct nl_parser_param
155{
156	int             (*pp_cb)(struct nl_object *, struct nl_parser_param *);
157	void *            pp_arg;
158};
159
160/**
161 * Cache Operations
162 */
163struct nl_cache_ops
164{
165	char  *			co_name;
166
167	int			co_hdrsize;
168	int			co_protocol;
169	struct nl_af_group *	co_groups;
170
171	/**
172	 * Called whenever an update of the cache is required. Must send
173	 * a request message to the kernel requesting a complete dump.
174	 */
175	int   (*co_request_update)(struct nl_cache *, struct nl_sock *);
176
177	/**
178	 * Called whenever a message was received that needs to be parsed.
179	 * Must parse the message and call the paser callback function
180	 * (nl_parser_param) provided via the argument.
181	 */
182	int   (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *,
183			       struct nlmsghdr *, struct nl_parser_param *);
184
185	struct nl_object_ops *	co_obj_ops;
186
187	struct nl_cache_ops *co_next;
188	struct nl_cache *co_major_cache;
189	struct genl_ops *	co_genl;
190	struct nl_msgtype	co_msgtypes[];
191};
192
193/** @} */
194
195#ifdef __cplusplus
196}
197#endif
198
199#endif
200