Export interface to define caches

This interface was internal so far which required all code defining
caches to be compiled with the sources available.

In order to simplify the interface, the co_msg_parser prototype was
changed to take the struct nl_parser_param directly instead of a
void *. It used to be void * because the co_msg_parser was directly
passed as the NL_CB_VALID callback function.

3 files changed, 200 insertions, 64 deletions

diff --git a/include/netlink-local.h b/include/netlink-local.h
index f03b795..a4cc6ce 100644
--- a/include/netlink-local.h
+++ b/include/netlink-local.h
@@ -54,6 +54,7 @@ typedef uint64_t	__u64;
 #include <netlink/cache.h>
 #include <netlink/route/tc.h>
 #include <netlink/object-api.h>
+#include <netlink/cache-api.h>
 #include <netlink-types.h>
 
 struct trans_tbl {
diff --git a/include/netlink-types.h b/include/netlink-types.h
index 8fea34c..e1145e1 100644
--- a/include/netlink-types.h
+++ b/include/netlink-types.h
@@ -95,27 +95,6 @@ struct nl_cache_mngr
 
 struct nl_parser_param;
 
-enum {
-	NL_ACT_UNSPEC,
-	NL_ACT_NEW,
-	NL_ACT_DEL,
-	NL_ACT_GET,
-	NL_ACT_SET,
-	NL_ACT_CHANGE,
-	__NL_ACT_MAX,
-};
-
-#define NL_ACT_MAX (__NL_ACT_MAX - 1)
-
-#define END_OF_MSGTYPES_LIST	{ -1, -1, NULL }
-
-struct nl_msgtype
-{
-	int			mt_id;
-	int			mt_act;
-	char *			mt_name;
-};
-
 struct genl_info
 {
 	struct sockaddr_nl *	who;
@@ -127,43 +106,6 @@ struct genl_info
 
 #define LOOSE_FLAG_COMPARISON	1
 
-struct nl_af_group
-{
-	int			ag_family;
-	int			ag_group;
-};
-
-#define END_OF_GROUP_LIST AF_UNSPEC, 0
-
-struct nl_cache_ops
-{
-	char  *			co_name;
-	int			co_hdrsize;
-	int			co_protocol;
-	struct nl_af_group *	co_groups;
-	
-	/**
-	 * Called whenever an update of the cache is required. Must send
-	 * a request message to the kernel requesting a complete dump.
-	 */
-	int   (*co_request_update)(struct nl_cache *, struct nl_handle *);
-
-	/**
-	 * Called whenever a message was received that needs to be parsed.
-	 * Must parse the message and call the paser callback function
-	 * (nl_parser_param) provided via the argument.
-	 */
-	int   (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *,
-			       struct nlmsghdr *, void *);
-
-	struct nl_object_ops *	co_obj_ops;
-
-	struct nl_cache_ops *co_next;
-	struct nl_cache *co_major_cache;
-	struct genl_ops *	co_genl;
-	struct nl_msgtype	co_msgtypes[];
-};
-
 #define NL_OBJ_MARK		1
 
 struct nl_object
@@ -171,12 +113,6 @@ struct nl_object
 	NLHDR_COMMON
 };
 
-struct nl_parser_param
-{
-	int             (*pp_cb)(struct nl_object *, struct nl_parser_param *);
-	void *            pp_arg;
-};
-
 struct nl_data
 {
 	size_t			d_size;
diff --git a/include/netlink/cache-api.h b/include/netlink/cache-api.h
new file mode 100644
index 0000000..96699ed
--- /dev/null
+++ b/include/netlink/cache-api.h
@@ -0,0 +1,199 @@
+/*
+ * netlink/cache-api.h		Caching API
+ *
+ *	This library is free software; you can redistribute it and/or
+ *	modify it under the terms of the GNU Lesser General Public
+ *	License as published by the Free Software Foundation version 2.1
+ *	of the License.
+ *
+ * Copyright (c) 2003-2006 Thomas Graf <tgraf@suug.ch>
+ */
+
+#ifndef NETLINK_CACHE_API_H_
+#define NETLINK_CACHE_API_H_
+
+#include <netlink/netlink.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @ingroup cache
+ * @defgroup cache_api Cache Implementation
+ * @brief
+ *
+ * @par 1) Cache Definition
+ * @code
+ * struct nl_cache_ops my_cache_ops = {
+ * 	.co_name		= "route/link",
+ * 	.co_protocol		= NETLINK_ROUTE,
+ * 	.co_hdrsize		= sizeof(struct ifinfomsg),
+ * 	.co_obj_ops		= &my_obj_ops,
+ * };
+ * @endcode
+ *
+ * @par 2) 
+ * @code
+ * // The simplest way to fill a cache is by providing a request-update
+ * // function which must trigger a complete dump on the kernel-side of
+ * // whatever the cache covers.
+ * static int my_request_update(struct nl_cache *cache,
+ * 				struct nl_handle *socket)
+ * {
+ * 	// In this example, we request a full dump of the interface table
+ * 	return nl_rtgen_request(socket, RTM_GETLINK, AF_UNSPEC, NLM_F_DUMP);
+ * }
+ *
+ * // The resulting netlink messages sent back will be fed into a message
+ * // parser one at a time. The message parser has to extract all relevant
+ * // information from the message and create an object reflecting the
+ * // contents of the message and pass it on to the parser callback function
+ * // provide which will add the object to the cache.
+ * static int my_msg_parser(struct nl_cache_ops *ops, struct sockaddr_nl *who,
+ * 			    struct nlmsghdr *nlh, struct nl_parser_param *pp)
+ * {
+ * 	struct my_obj *obj;
+ *
+ * 	obj = my_obj_alloc();
+ * 	obj->ce_msgtype = nlh->nlmsg_type;
+ *
+ * 	// Parse the netlink message and continue creating the object.
+ *
+ * 	err = pp->pp_cb((struct nl_object *) obj, pp);
+ * 	if (err < 0)
+ * 		goto errout;
+ * }
+ *
+ * struct nl_cache_ops my_cache_ops = {
+ * 	...
+ * 	.co_request_update	= my_request_update,
+ * 	.co_msg_parser		= my_msg_parser,
+ * };
+ * @endcode
+ *
+ * @par 3) Notification based Updates
+ * @code
+ * // Caches can be kept up-to-date based on notifications if the kernel
+ * // sends out notifications whenever an object is added/removed/changed.
+ * //
+ * // It is trivial to support this, first a list of groups needs to be
+ * // defined which are required to join in order to receive all necessary
+ * // notifications. The groups are separated by address family to support
+ * // the common situation where a separate group is used for each address
+ * // family. If there is only one group, simply specify AF_UNSPEC.
+ * static struct nl_af_group addr_groups[] = {
+ * 	{ AF_INET,	RTNLGRP_IPV4_IFADDR },
+ * 	{ AF_INET6,	RTNLGRP_IPV6_IFADDR },
+ * 	{ END_OF_GROUP_LIST },
+ * };
+ *
+ * // In order for the caching system to know the meaning of each message
+ * // type it requires a table which maps each supported message type to
+ * // a cache action, e.g. RTM_NEWADDR means address has been added or
+ * // updated, RTM_DELADDR means address has been removed.
+ * static struct nl_cache_ops rtnl_addr_ops = {
+ * 	...
+ * 	.co_msgtypes		= {
+ * 					{ RTM_NEWADDR, NL_ACT_NEW, "new" },
+ * 					{ RTM_DELADDR, NL_ACT_DEL, "del" },
+ * 					{ RTM_GETADDR, NL_ACT_GET, "get" },
+ * 					END_OF_MSGTYPES_LIST,
+ * 				},
+ * 	.co_groups		= addr_groups,
+ * };
+ *
+ * // It is now possible to keep the cache up-to-date using the cache manager.
+ * @endcode
+ * @{
+ */
+
+enum {
+	NL_ACT_UNSPEC,
+	NL_ACT_NEW,
+	NL_ACT_DEL,
+	NL_ACT_GET,
+	NL_ACT_SET,
+	NL_ACT_CHANGE,
+	__NL_ACT_MAX,
+};
+
+#define NL_ACT_MAX (__NL_ACT_MAX - 1)
+
+#define END_OF_MSGTYPES_LIST	{ -1, -1, NULL }
+
+/**
+ * Message type to cache action association
+ */
+struct nl_msgtype
+{
+	/** Netlink message type */
+	int			mt_id;
+
+	/** Cache action to take */
+	int			mt_act;
+
+	/** Name of operation for human-readable printing */
+	char *			mt_name;
+};
+
+/**
+ * Address family to netlink group association
+ */
+struct nl_af_group
+{
+	/** Address family */
+	int			ag_family;
+
+	/** Netlink group identifier */
+	int			ag_group;
+};
+
+#define END_OF_GROUP_LIST AF_UNSPEC, 0
+
+struct nl_parser_param
+{
+	int             (*pp_cb)(struct nl_object *, struct nl_parser_param *);
+	void *            pp_arg;
+};
+
+/**
+ * Cache Operations
+ */
+struct nl_cache_ops
+{
+	char  *			co_name;
+
+	int			co_hdrsize;
+	int			co_protocol;
+	struct nl_af_group *	co_groups;
+	
+	/**
+	 * Called whenever an update of the cache is required. Must send
+	 * a request message to the kernel requesting a complete dump.
+	 */
+	int   (*co_request_update)(struct nl_cache *, struct nl_handle *);
+
+	/**
+	 * Called whenever a message was received that needs to be parsed.
+	 * Must parse the message and call the paser callback function
+	 * (nl_parser_param) provided via the argument.
+	 */
+	int   (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *,
+			       struct nlmsghdr *, struct nl_parser_param *);
+
+	struct nl_object_ops *	co_obj_ops;
+
+	struct nl_cache_ops *co_next;
+	struct nl_cache *co_major_cache;
+	struct genl_ops *	co_genl;
+	struct nl_msgtype	co_msgtypes[];
+};
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif