include/netlink-private/cache-api.h

   1 /*
   2  * netlink-private/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-2013 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 #include <netlink/cache.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /**
  23  * @ingroup cache
  24  * @defgroup cache_api Cache Implementation
  25  * @brief
  26  *
  27  * @par 1) Cache Definition
  28  * @code
  29  * struct nl_cache_ops my_cache_ops = {
  30  *      .co_name                = "route/link",
  31  *      .co_protocol            = NETLINK_ROUTE,
  32  *      .co_hdrsize             = sizeof(struct ifinfomsg),
  33  *      .co_obj_ops             = &my_obj_ops,
  34  * };
  35  * @endcode
  36  *
  37  * @par 2)
  38  * @code
  39  * // The simplest way to fill a cache is by providing a request-update
  40  * // function which must trigger a complete dump on the kernel-side of
  41  * // whatever the cache covers.
  42  * static int my_request_update(struct nl_cache *cache,
  43  *                              struct nl_sock *socket)
  44  * {
  45  *      // In this example, we request a full dump of the interface table
  46  *      return nl_rtgen_request(socket, RTM_GETLINK, AF_UNSPEC, NLM_F_DUMP);
  47  * }
  48  *
  49  * // The resulting netlink messages sent back will be fed into a message
  50  * // parser one at a time. The message parser has to extract all relevant
  51  * // information from the message and create an object reflecting the
  52  * // contents of the message and pass it on to the parser callback function
  53  * // provide which will add the object to the cache.
  54  * static int my_msg_parser(struct nl_cache_ops *ops, struct sockaddr_nl *who,
  55  *                          struct nlmsghdr *nlh, struct nl_parser_param *pp)
  56  * {
  57  *      struct my_obj *obj;
  58  *
  59  *      obj = my_obj_alloc();
  60  *      obj->ce_msgtype = nlh->nlmsg_type;
  61  *
  62  *      // Parse the netlink message and continue creating the object.
  63  *
  64  *      err = pp->pp_cb((struct nl_object *) obj, pp);
  65  *      if (err < 0)
  66  *              goto errout;
  67  * }
  68  *
  69  * struct nl_cache_ops my_cache_ops = {
  70  *      ...
  71  *      .co_request_update      = my_request_update,
  72  *      .co_msg_parser          = my_msg_parser,
  73  * };
  74  * @endcode
  75  *
  76  * @par 3) Notification based Updates
  77  * @code
  78  * // Caches can be kept up-to-date based on notifications if the kernel
  79  * // sends out notifications whenever an object is added/removed/changed.
  80  * //
  81  * // It is trivial to support this, first a list of groups needs to be
  82  * // defined which are required to join in order to receive all necessary
  83  * // notifications. The groups are separated by address family to support
  84  * // the common situation where a separate group is used for each address
  85  * // family. If there is only one group, simply specify AF_UNSPEC.
  86  * static struct nl_af_group addr_groups[] = {
  87  *      { AF_INET,      RTNLGRP_IPV4_IFADDR },
  88  *      { AF_INET6,     RTNLGRP_IPV6_IFADDR },
  89  *      { END_OF_GROUP_LIST },
  90  * };
  91  *
  92  * // In order for the caching system to know the meaning of each message
  93  * // type it requires a table which maps each supported message type to
  94  * // a cache action, e.g. RTM_NEWADDR means address has been added or
  95  * // updated, RTM_DELADDR means address has been removed.
  96  * static struct nl_cache_ops rtnl_addr_ops = {
  97  *      ...
  98  *      .co_msgtypes            = {
  99  *                                      { RTM_NEWADDR, NL_ACT_NEW, "new" },
 100  *                                      { RTM_DELADDR, NL_ACT_DEL, "del" },
 101  *                                      { RTM_GETADDR, NL_ACT_GET, "get" },
 102  *                                      END_OF_MSGTYPES_LIST,
 103  *                              },
 104  *      .co_groups              = addr_groups,
 105  * };
 106  *
 107  * // It is now possible to keep the cache up-to-date using the cache manager.
 108  * @endcode
 109  * @{
 110  */
 111
 112 #define END_OF_MSGTYPES_LIST    { -1, -1, NULL }
 113
 114 /**
 115  * Message type to cache action association
 116  */
 117 struct nl_msgtype
 118 {
 119         /** Netlink message type */
 120         int                     mt_id;
 121
 122         /** Cache action to take */
 123         int                     mt_act;
 124
 125         /** Name of operation for human-readable printing */
 126         char *                  mt_name;
 127 };
 128
 129 /**
 130  * Address family to netlink group association
 131  */
 132 struct nl_af_group
 133 {
 134         /** Address family */
 135         int                     ag_family;
 136
 137         /** Netlink group identifier */
 138         int                     ag_group;
 139 };
 140
 141 #define END_OF_GROUP_LIST AF_UNSPEC, 0
 142
 143 /**
 144  * Parser parameters
 145  *
 146  * This structure is used to configure what kind of parser to use
 147  * when parsing netlink messages to create objects.
 148  */
 149 struct nl_parser_param
 150 {
 151         /** Function to parse netlink messages into objects */
 152         int             (*pp_cb)(struct nl_object *, struct nl_parser_param *);
 153
 154         /** Arbitary argument to be passed to the parser */
 155         void *            pp_arg;
 156 };
 157
 158 /**
 159  * Cache Operations
 160  *
 161  * This structure defines the characterstics of a cache type. It contains
 162  * pointers to functions which implement the specifics of the object type
 163  * the cache can hold.
 164  */
 165 struct nl_cache_ops
 166 {
 167         /** Name of cache type (must be unique) */
 168         char  *                 co_name;
 169
 170         /** Size of family specific netlink header */
 171         int                     co_hdrsize;
 172
 173         /** Netlink protocol */
 174         int                     co_protocol;
 175
 176         /** cache object hash size **/
 177         int                     co_hash_size;
 178
 179         /** cache flags */
 180         unsigned int            co_flags;
 181
 182         /** Reference counter */
 183         unsigned int            co_refcnt;
 184
 185         /** Group definition */
 186         struct nl_af_group *    co_groups;
 187
 188         /**
 189          * Called whenever an update of the cache is required. Must send
 190          * a request message to the kernel requesting a complete dump.
 191          */
 192         int   (*co_request_update)(struct nl_cache *, struct nl_sock *);
 193
 194         /**
 195          * Called whenever a message was received that needs to be parsed.
 196          * Must parse the message and call the paser callback function
 197          * (nl_parser_param) provided via the argument.
 198          */
 199         int   (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *,
 200                                struct nlmsghdr *, struct nl_parser_param *);
 201
 202         /**
 203          * The function registered under this callback is called after a
 204          * netlink notification associated with this cache type has been
 205          * parsed into an object and is being considered for inclusio into
 206          * the specified cache.
 207          *
 208          * The purpose of this function is to filter out notifications
 209          * which should be ignored when updating caches.
 210          *
 211          * The function must return NL_SKIP to prevent the object from
 212          * being included, or NL_OK to include it.
 213          *
 214          * @code
 215          * int my_filter(struct nl_cache *cache, struct nl_object *obj)
 216          * {
 217          *      if (reason_to_not_include_obj(obj))
 218          *              return NL_SKIP;
 219          *
 220          *      return NL_OK;
 221          * }
 222          * @endcode
 223          */
 224         int   (*co_event_filter)(struct nl_cache *, struct nl_object *obj);
 225
 226         /**
 227          * The function registered under this callback is called when an
 228          * object formed from a notification event needs to be included in
 229          * a cache.
 230          *
 231          * For each modified object, the change callback \c change_cb must
 232          * be called with the \c data argument provided.
 233          *
 234          * If no function is registered, the function nl_cache_include()
 235          * will be used for this purpose.
 236          *
 237          * @see nl_cache_include()
 238          */
 239         int   (*co_include_event)(struct nl_cache *cache, struct nl_object *obj,
 240                                   change_func_t change_cb, void *data);
 241
 242         void (*reserved_1)(void);
 243         void (*reserved_2)(void);
 244         void (*reserved_3)(void);
 245         void (*reserved_4)(void);
 246         void (*reserved_5)(void);
 247         void (*reserved_6)(void);
 248         void (*reserved_7)(void);
 249         void (*reserved_8)(void);
 250
 251         /** Object operations */
 252         struct nl_object_ops *  co_obj_ops;
 253
 254         /** Internal, do not touch! */
 255         struct nl_cache_ops *co_next;
 256
 257         struct nl_cache *co_major_cache;
 258         struct genl_ops *       co_genl;
 259
 260         /* Message type definition */
 261         struct nl_msgtype       co_msgtypes[];
 262 };
 263
 264 /** @} */
 265
 266 #ifdef __cplusplus
 267 }
 268 #endif
 269
 270 #endif