cache-api.h

/*
 * 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;
 
        /** Reference counter */
        unsigned int            co_refcnt;
 
        void                  (*unused1)(void);
        void                  (*unused2)(void);
        void                  (*unused3)(void);
        void                  (*unused4)(void);
        void                  (*unused5)(void);
        void                  (*unused6)(void);
        void                  (*unused7)(void);
        void                  (*unused8)(void);
 
        struct nl_msgtype       co_msgtypes[];
};
 
extern void     nl_cache_ops_get(struct nl_cache_ops *);
extern void     nl_cache_ops_put(struct nl_cache_ops *);
 
/** @} */
 
#ifdef __cplusplus
}
#endif
 
#endif