13040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf/* 23040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * netlink/cache-api.h Caching API 33040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 43040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * This library is free software; you can redistribute it and/or 53040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * modify it under the terms of the GNU Lesser General Public 63040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * License as published by the Free Software Foundation version 2.1 73040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * of the License. 83040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 93040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * Copyright (c) 2003-2006 Thomas Graf <tgraf@suug.ch> 103040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf */ 113040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 123040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#ifndef NETLINK_CACHE_API_H_ 133040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#define NETLINK_CACHE_API_H_ 143040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 153040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#include <netlink/netlink.h> 163040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 173040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#ifdef __cplusplus 183040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Grafextern "C" { 193040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#endif 203040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 213040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf/** 223040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @ingroup cache 233040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @defgroup cache_api Cache Implementation 243040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @brief 253040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 263040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @par 1) Cache Definition 273040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @code 283040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * struct nl_cache_ops my_cache_ops = { 293040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * .co_name = "route/link", 303040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * .co_protocol = NETLINK_ROUTE, 313040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * .co_hdrsize = sizeof(struct ifinfomsg), 323040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * .co_obj_ops = &my_obj_ops, 333040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * }; 343040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @endcode 353040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 363040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @par 2) 373040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @code 383040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // The simplest way to fill a cache is by providing a request-update 393040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // function which must trigger a complete dump on the kernel-side of 403040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // whatever the cache covers. 413040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * static int my_request_update(struct nl_cache *cache, 421155370f520cb64657e25153255cf7dc1424317fThomas Graf * struct nl_sock *socket) 433040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * { 443040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // In this example, we request a full dump of the interface table 453040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * return nl_rtgen_request(socket, RTM_GETLINK, AF_UNSPEC, NLM_F_DUMP); 463040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * } 473040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 483040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // The resulting netlink messages sent back will be fed into a message 493040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // parser one at a time. The message parser has to extract all relevant 503040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // information from the message and create an object reflecting the 513040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // contents of the message and pass it on to the parser callback function 523040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // provide which will add the object to the cache. 533040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * static int my_msg_parser(struct nl_cache_ops *ops, struct sockaddr_nl *who, 543040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * struct nlmsghdr *nlh, struct nl_parser_param *pp) 553040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * { 563040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * struct my_obj *obj; 573040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 583040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * obj = my_obj_alloc(); 593040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * obj->ce_msgtype = nlh->nlmsg_type; 603040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 613040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // Parse the netlink message and continue creating the object. 623040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 633040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * err = pp->pp_cb((struct nl_object *) obj, pp); 643040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * if (err < 0) 653040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * goto errout; 663040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * } 673040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 683040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * struct nl_cache_ops my_cache_ops = { 693040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * ... 703040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * .co_request_update = my_request_update, 713040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * .co_msg_parser = my_msg_parser, 723040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * }; 733040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @endcode 743040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 753040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @par 3) Notification based Updates 763040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @code 773040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // Caches can be kept up-to-date based on notifications if the kernel 783040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // sends out notifications whenever an object is added/removed/changed. 793040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // 803040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // It is trivial to support this, first a list of groups needs to be 813040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // defined which are required to join in order to receive all necessary 823040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // notifications. The groups are separated by address family to support 833040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // the common situation where a separate group is used for each address 843040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // family. If there is only one group, simply specify AF_UNSPEC. 853040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * static struct nl_af_group addr_groups[] = { 863040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * { AF_INET, RTNLGRP_IPV4_IFADDR }, 873040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * { AF_INET6, RTNLGRP_IPV6_IFADDR }, 883040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * { END_OF_GROUP_LIST }, 893040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * }; 903040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 913040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // In order for the caching system to know the meaning of each message 923040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // type it requires a table which maps each supported message type to 933040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // a cache action, e.g. RTM_NEWADDR means address has been added or 943040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // updated, RTM_DELADDR means address has been removed. 953040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * static struct nl_cache_ops rtnl_addr_ops = { 963040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * ... 973040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * .co_msgtypes = { 983040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * { RTM_NEWADDR, NL_ACT_NEW, "new" }, 993040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * { RTM_DELADDR, NL_ACT_DEL, "del" }, 1003040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * { RTM_GETADDR, NL_ACT_GET, "get" }, 1013040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * END_OF_MSGTYPES_LIST, 1023040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * }, 1033040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * .co_groups = addr_groups, 1043040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * }; 1053040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * 1063040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * // It is now possible to keep the cache up-to-date using the cache manager. 1073040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @endcode 1083040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * @{ 1093040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf */ 1103040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1113040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Grafenum { 1123040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf NL_ACT_UNSPEC, 1133040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf NL_ACT_NEW, 1143040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf NL_ACT_DEL, 1153040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf NL_ACT_GET, 1163040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf NL_ACT_SET, 1173040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf NL_ACT_CHANGE, 1183040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf __NL_ACT_MAX, 1193040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf}; 1203040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1213040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#define NL_ACT_MAX (__NL_ACT_MAX - 1) 1223040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1233040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#define END_OF_MSGTYPES_LIST { -1, -1, NULL } 1243040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1253040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf/** 1263040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * Message type to cache action association 1273040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf */ 1283040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Grafstruct nl_msgtype 1293040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf{ 1303040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf /** Netlink message type */ 1313040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf int mt_id; 1323040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1333040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf /** Cache action to take */ 1343040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf int mt_act; 1353040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1363040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf /** Name of operation for human-readable printing */ 1373040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf char * mt_name; 1383040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf}; 1393040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1403040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf/** 1413040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * Address family to netlink group association 1423040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf */ 1433040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Grafstruct nl_af_group 1443040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf{ 1453040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf /** Address family */ 1463040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf int ag_family; 1473040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1483040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf /** Netlink group identifier */ 1493040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf int ag_group; 1503040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf}; 1513040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1523040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#define END_OF_GROUP_LIST AF_UNSPEC, 0 1533040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1543040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Grafstruct nl_parser_param 1553040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf{ 1563040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf int (*pp_cb)(struct nl_object *, struct nl_parser_param *); 1573040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf void * pp_arg; 1583040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf}; 1593040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1603040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf/** 1613040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * Cache Operations 1623040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf */ 1633040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Grafstruct nl_cache_ops 1643040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf{ 1653040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf char * co_name; 1663040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1673040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf int co_hdrsize; 1683040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf int co_protocol; 1693040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf struct nl_af_group * co_groups; 1703040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1713040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf /** 1723040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * Called whenever an update of the cache is required. Must send 1733040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * a request message to the kernel requesting a complete dump. 1743040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf */ 1751155370f520cb64657e25153255cf7dc1424317fThomas Graf int (*co_request_update)(struct nl_cache *, struct nl_sock *); 1763040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1773040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf /** 1783040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * Called whenever a message was received that needs to be parsed. 1793040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * Must parse the message and call the paser callback function 1803040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf * (nl_parser_param) provided via the argument. 1813040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf */ 1823040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf int (*co_msg_parser)(struct nl_cache_ops *, struct sockaddr_nl *, 1833040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf struct nlmsghdr *, struct nl_parser_param *); 1843040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1853040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf struct nl_object_ops * co_obj_ops; 1863040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1873040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf struct nl_cache_ops *co_next; 1883040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf struct nl_cache *co_major_cache; 1893040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf struct genl_ops * co_genl; 1903040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf struct nl_msgtype co_msgtypes[]; 1913040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf}; 1923040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1933040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf/** @} */ 1943040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1953040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#ifdef __cplusplus 1963040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf} 1973040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#endif 1983040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf 1993040a1d6254465bed9e44e4d1bf279c2c50cd16aThomas Graf#endif 200