object-api.h 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331
  1. /*
  2. * netlink/object-api.c Object 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-2007 Thomas Graf <tgraf@suug.ch>
  10. */
  11. #ifndef NETLINK_OBJECT_API_H_
  12. #define NETLINK_OBJECT_API_H_
  13. #include <netlink/netlink.h>
  14. #include <netlink/utils.h>
  15. #ifdef __cplusplus
  16. extern "C" {
  17. #endif
  18. /**
  19. * @ingroup object
  20. * @defgroup object_api Object API
  21. * @brief
  22. *
  23. * @par 1) Object Definition
  24. * @code
  25. * // Define your object starting with the common object header
  26. * struct my_obj {
  27. * NLHDR_COMMON
  28. * int my_data;
  29. * };
  30. *
  31. * // Fill out the object operations structure
  32. * struct nl_object_ops my_ops = {
  33. * .oo_name = "my_obj",
  34. * .oo_size = sizeof(struct my_obj),
  35. * };
  36. *
  37. * // At this point the object can be allocated, you may want to provide a
  38. * // separate _alloc() function to ease allocting objects of this kind.
  39. * struct nl_object *obj = nl_object_alloc(&my_ops);
  40. *
  41. * // And release it again...
  42. * nl_object_put(obj);
  43. * @endcode
  44. *
  45. * @par 2) Allocating additional data
  46. * @code
  47. * // You may require to allocate additional data and store it inside
  48. * // object, f.e. assuming there is a field `ptr'.
  49. * struct my_obj {
  50. * NLHDR_COMMON
  51. * void * ptr;
  52. * };
  53. *
  54. * // And at some point you may assign allocated data to this field:
  55. * my_obj->ptr = calloc(1, ...);
  56. *
  57. * // In order to not introduce any memory leaks you have to release
  58. * // this data again when the last reference is given back.
  59. * static void my_obj_free_data(struct nl_object *obj)
  60. * {
  61. * struct my_obj *my_obj = nl_object_priv(obj);
  62. *
  63. * free(my_obj->ptr);
  64. * }
  65. *
  66. * // Also when the object is cloned, you must ensure for your pointer
  67. * // stay valid even if one of the clones is freed by either making
  68. * // a clone as well or increase the reference count.
  69. * static int my_obj_clone(struct nl_object *src, struct nl_object *dst)
  70. * {
  71. * struct my_obj *my_src = nl_object_priv(src);
  72. * struct my_obj *my_dst = nl_object_priv(dst);
  73. *
  74. * if (src->ptr) {
  75. * dst->ptr = calloc(1, ...);
  76. * memcpy(dst->ptr, src->ptr, ...);
  77. * }
  78. * }
  79. *
  80. * struct nl_object_ops my_ops = {
  81. * ...
  82. * .oo_free_data = my_obj_free_data,
  83. * .oo_clone = my_obj_clone,
  84. * };
  85. * @endcode
  86. *
  87. * @par 3) Object Dumping
  88. * @code
  89. * static int my_obj_dump_detailed(struct nl_object *obj,
  90. * struct nl_dump_params *params)
  91. * {
  92. * struct my_obj *my_obj = nl_object_priv(obj);
  93. *
  94. * // It is absolutely essential to use nl_dump() when printing
  95. * // any text to make sure the dumping parameters are respected.
  96. * nl_dump(params, "Obj Integer: %d\n", my_obj->my_int);
  97. *
  98. * // Before we can dump the next line, make sure to prefix
  99. * // this line correctly.
  100. * nl_new_line(params);
  101. *
  102. * // You may also split a line into multiple nl_dump() calls.
  103. * nl_dump(params, "String: %s ", my_obj->my_string);
  104. * nl_dump(params, "String-2: %s\n", my_obj->another_string);
  105. * }
  106. *
  107. * struct nl_object_ops my_ops = {
  108. * ...
  109. * .oo_dump[NL_DUMP_FULL] = my_obj_dump_detailed,
  110. * };
  111. * @endcode
  112. *
  113. * @par 4) Object Attributes
  114. * @code
  115. * // The concept of object attributes is optional but can ease the typical
  116. * // case of objects that have optional attributes, e.g. a route may have a
  117. * // nexthop assigned but it is not required to.
  118. *
  119. * // The first step to define your object specific bitmask listing all
  120. * // attributes
  121. * #define MY_ATTR_FOO (1<<0)
  122. * #define MY_ATTR_BAR (1<<1)
  123. *
  124. * // When assigning an optional attribute to the object, make sure
  125. * // to mark its availability.
  126. * my_obj->foo = 123123;
  127. * my_obj->ce_mask |= MY_ATTR_FOO;
  128. *
  129. * // At any time you may use this mask to check for the availability
  130. * // of the attribute, e.g. while dumping
  131. * if (my_obj->ce_mask & MY_ATTR_FOO)
  132. * nl_dump(params, "foo %d ", my_obj->foo);
  133. *
  134. * // One of the big advantages of this concept is that it allows for
  135. * // standardized comparisons which make it trivial for caches to
  136. * // identify unique objects by use of unified comparison functions.
  137. * // In order for it to work, your object implementation must provide
  138. * // a comparison function and define a list of attributes which
  139. * // combined together make an object unique.
  140. *
  141. * static int my_obj_compare(struct nl_object *_a, struct nl_object *_b,
  142. * uint32_t attrs, int flags)
  143. * {
  144. * struct my_obj *a = nl_object_priv(_a):
  145. * struct my_obj *b = nl_object_priv(_b):
  146. * int diff = 0;
  147. *
  148. * // We help ourselves in defining our own DIFF macro which will
  149. * // call ATTR_DIFF() on both objects which will make sure to only
  150. * // compare the attributes if required.
  151. * #define MY_DIFF(ATTR, EXPR) ATTR_DIFF(attrs, MY_ATTR_##ATTR, a, b, EXPR)
  152. *
  153. * // Call our own diff macro for each attribute to build a bitmask
  154. * // representing the attributes which mismatch.
  155. * diff |= MY_DIFF(FOO, a->foo != b->foo)
  156. * diff |= MY_DIFF(BAR, strcmp(a->bar, b->bar))
  157. *
  158. * return diff;
  159. * }
  160. *
  161. * // In order to identify identical objects with differing attributes
  162. * // you must specify the attributes required to uniquely identify
  163. * // your object. Make sure to not include too many attributes, this
  164. * // list is used when caches look for an old version of an object.
  165. * struct nl_object_ops my_ops = {
  166. * ...
  167. * .oo_id_attrs = MY_ATTR_FOO,
  168. * .oo_compare = my_obj_compare,
  169. * };
  170. * @endcode
  171. * @{
  172. */
  173. /**
  174. * Common Object Header
  175. *
  176. * This macro must be included as first member in every object
  177. * definition to allow objects to be cached.
  178. */
  179. #define NLHDR_COMMON \
  180. int ce_refcnt; \
  181. struct nl_object_ops * ce_ops; \
  182. struct nl_cache * ce_cache; \
  183. struct nl_list_head ce_list; \
  184. int ce_msgtype; \
  185. int ce_flags; \
  186. uint32_t ce_mask;
  187. /**
  188. * Return true if attribute is available in both objects
  189. * @arg A an object
  190. * @arg B another object
  191. * @arg ATTR attribute bit
  192. *
  193. * @return True if the attribute is available, otherwise false is returned.
  194. */
  195. #define AVAILABLE(A, B, ATTR) (((A)->ce_mask & (B)->ce_mask) & (ATTR))
  196. /**
  197. * Return true if attributes mismatch
  198. * @arg A an object
  199. * @arg B another object
  200. * @arg ATTR attribute bit
  201. * @arg EXPR Comparison expression
  202. *
  203. * This function will check if the attribute in question is available
  204. * in both objects, if not this will count as a mismatch.
  205. *
  206. * If available the function will execute the expression which must
  207. * return true if the attributes mismatch.
  208. *
  209. * @return True if the attribute mismatch, or false if they match.
  210. */
  211. #define ATTR_MISMATCH(A, B, ATTR, EXPR) (!AVAILABLE(A, B, ATTR) || (EXPR))
  212. /**
  213. * Return attribute bit if attribute does not match
  214. * @arg LIST list of attributes to be compared
  215. * @arg ATTR attribute bit
  216. * @arg A an object
  217. * @arg B another object
  218. * @arg EXPR Comparison expression
  219. *
  220. * This function will check if the attribute in question is available
  221. * in both objects, if not this will count as a mismatch.
  222. *
  223. * If available the function will execute the expression which must
  224. * return true if the attributes mismatch.
  225. *
  226. * In case the attributes mismatch, the attribute is returned, otherwise
  227. * 0 is returned.
  228. *
  229. * @code
  230. * diff |= ATTR_DIFF(attrs, MY_ATTR_FOO, a, b, a->foo != b->foo);
  231. * @endcode
  232. */
  233. #define ATTR_DIFF(LIST, ATTR, A, B, EXPR) \
  234. ({ int diff = 0; \
  235. if (((LIST) & (ATTR)) && ATTR_MISMATCH(A, B, ATTR, EXPR)) \
  236. diff = ATTR; \
  237. diff; })
  238. /**
  239. * Object Operations
  240. */
  241. struct nl_object;
  242. struct nl_object_ops
  243. {
  244. /**
  245. * Unique name of object type
  246. *
  247. * Must be in the form family/name, e.g. "route/addr"
  248. */
  249. char * oo_name;
  250. /** Size of object including its header */
  251. size_t oo_size;
  252. /* List of attributes needed to uniquely identify the object */
  253. uint32_t oo_id_attrs;
  254. /**
  255. * Constructor function
  256. *
  257. * Will be called when a new object of this type is allocated.
  258. * Can be used to initialize members such as lists etc.
  259. */
  260. void (*oo_constructor)(struct nl_object *);
  261. /**
  262. * Destructor function
  263. *
  264. * Will be called when an object is freed. Must free all
  265. * resources which may have been allocated as part of this
  266. * object.
  267. */
  268. void (*oo_free_data)(struct nl_object *);
  269. /**
  270. * Cloning function
  271. *
  272. * Will be called when an object needs to be cloned. Please
  273. * note that the generic object code will make an exact
  274. * copy of the object first, therefore you only need to take
  275. * care of members which require reference counting etc.
  276. *
  277. * May return a negative error code to abort cloning.
  278. */
  279. int (*oo_clone)(struct nl_object *, struct nl_object *);
  280. /**
  281. * Dumping functions
  282. *
  283. * Will be called when an object is dumped. The implementations
  284. * have to use nl_dump(), nl_dump_line(), and nl_new_line() to
  285. * dump objects.
  286. *
  287. * The functions must return the number of lines printed.
  288. */
  289. void (*oo_dump[NL_DUMP_MAX+1])(struct nl_object *,
  290. struct nl_dump_params *);
  291. /**
  292. * Comparison function
  293. *
  294. * Will be called when two objects of the same type are
  295. * compared. It takes the two objects in question, an object
  296. * specific bitmask defining which attributes should be
  297. * compared and flags to control the behaviour.
  298. *
  299. * The function must return a bitmask with the relevant bit
  300. * set for each attribute that mismatches.
  301. */
  302. int (*oo_compare)(struct nl_object *, struct nl_object *,
  303. uint32_t, int);
  304. char *(*oo_attrs2str)(int, char *, size_t);
  305. };
  306. /** @} */
  307. #ifdef __cplusplus
  308. }
  309. #endif
  310. #endif