libnl 1.1

include/netlink/object-api.h

00001 /*
00002  * netlink/object-api.c         Object API
00003  *
00004  *      This library is free software; you can redistribute it and/or
00005  *      modify it under the terms of the GNU Lesser General Public
00006  *      License as published by the Free Software Foundation version 2.1
00007  *      of the License.
00008  *
00009  * Copyright (c) 2003-2007 Thomas Graf <tgraf@suug.ch>
00010  */
00011 
00012 #ifndef NETLINK_OBJECT_API_H_
00013 #define NETLINK_OBJECT_API_H_
00014 
00015 #include <netlink/netlink.h>
00016 #include <netlink/utils.h>
00017 
00018 #ifdef __cplusplus
00019 extern "C" {
00020 #endif
00021 
00022 /**
00023  * @ingroup object
00024  * @defgroup object_api Object API
00025  * @brief
00026  *
00027  * @par 1) Object Definition
00028  * @code
00029  * // Define your object starting with the common object header
00030  * struct my_obj {
00031  *      NLHDR_COMMON
00032  *      int             my_data;
00033  * };
00034  *
00035  * // Fill out the object operations structure
00036  * struct nl_object_ops my_ops = {
00037  *      .oo_name        = "my_obj",
00038  *      .oo_size        = sizeof(struct my_obj),
00039  * };
00040  *
00041  * // At this point the object can be allocated, you may want to provide a
00042  * // separate _alloc() function to ease allocting objects of this kind.
00043  * struct nl_object *obj = nl_object_alloc(&my_ops);
00044  *
00045  * // And release it again...
00046  * nl_object_put(obj);
00047  * @endcode
00048  *
00049  * @par 2) Allocating additional data
00050  * @code
00051  * // You may require to allocate additional data and store it inside
00052  * // object, f.e. assuming there is a field `ptr'.
00053  * struct my_obj {
00054  *      NLHDR_COMMON
00055  *      void *          ptr;
00056  * };
00057  *
00058  * // And at some point you may assign allocated data to this field:
00059  * my_obj->ptr = calloc(1, ...);
00060  *
00061  * // In order to not introduce any memory leaks you have to release
00062  * // this data again when the last reference is given back.
00063  * static void my_obj_free_data(struct nl_object *obj)
00064  * {
00065  *      struct my_obj *my_obj = nl_object_priv(obj);
00066  *
00067  *      free(my_obj->ptr);
00068  * }
00069  *
00070  * // Also when the object is cloned, you must ensure for your pointer
00071  * // stay valid even if one of the clones is freed by either making
00072  * // a clone as well or increase the reference count.
00073  * static int my_obj_clone(struct nl_object *src, struct nl_object *dst)
00074  * {
00075  *      struct my_obj *my_src = nl_object_priv(src);
00076  *      struct my_obj *my_dst = nl_object_priv(dst);
00077  *
00078  *      if (src->ptr) {
00079  *              dst->ptr = calloc(1, ...);
00080  *              memcpy(dst->ptr, src->ptr, ...);
00081  *      }
00082  * }
00083  *
00084  * struct nl_object_ops my_ops = {
00085  *      ...
00086  *      .oo_free_data   = my_obj_free_data,
00087  *      .oo_clone       = my_obj_clone,
00088  * };
00089  * @endcode
00090  *
00091  * @par 3) Object Dumping
00092  * @code
00093  * static int my_obj_dump_detailed(struct nl_object *obj,
00094  *                                 struct nl_dump_params *params)
00095  * {
00096  *      struct my_obj *my_obj = nl_object_priv(obj);
00097  *      int line = 1;   // We will print at least one line for sure
00098  *
00099  *      // It is absolutely essential to use nl_dump() when printing
00100  *      // any text to make sure the dumping parameters are respected.
00101  *      nl_dump(params, "Obj Integer: %d\n", my_obj->my_int);
00102  *
00103  *      // Before we can dump the next line, make sure to prefix
00104  *      // this line correctly.
00105  *      nl_new_line(params, line++);
00106  *
00107  *      // You may also split a line into multiple nl_dump() calls.
00108  *      nl_dump(params, "String: %s ", my_obj->my_string);
00109  *      nl_dump(params, "String-2: %s\n", my_obj->another_string);
00110  *
00111  *      // Return the number of lines dumped
00112  *      return line;
00113  * }
00114  *
00115  * struct nl_object_ops my_ops = {
00116  *      ...
00117  *      .oo_dump[NL_DUMP_FULL]  = my_obj_dump_detailed,
00118  * };
00119  * @endcode
00120  *
00121  * @par 4) Object Attributes
00122  * @code
00123  * // The concept of object attributes is optional but can ease the typical
00124  * // case of objects that have optional attributes, e.g. a route may have a
00125  * // nexthop assigned but it is not required to.
00126  *
00127  * // The first step to define your object specific bitmask listing all
00128  * // attributes
00129  * #define MY_ATTR_FOO          (1<<0)
00130  * #define MY_ATTR_BAR          (1<<1)
00131  *
00132  * // When assigning an optional attribute to the object, make sure
00133  * // to mark its availability.
00134  * my_obj->foo = 123123;
00135  * my_obj->ce_mask |= MY_ATTR_FOO;
00136  *
00137  * // At any time you may use this mask to check for the availability
00138  * // of the attribute, e.g. while dumping
00139  * if (my_obj->ce_mask & MY_ATTR_FOO)
00140  *      nl_dump(params, "foo %d ", my_obj->foo);
00141  *
00142  * // One of the big advantages of this concept is that it allows for
00143  * // standardized comparisons which make it trivial for caches to
00144  * // identify unique objects by use of unified comparison functions.
00145  * // In order for it to work, your object implementation must provide
00146  * // a comparison function and define a list of attributes which
00147  * // combined together make an object unique.
00148  *
00149  * static int my_obj_compare(struct nl_object *_a, struct nl_object *_b,
00150  *                           uint32_t attrs, int flags)
00151  * {
00152  *      struct my_obj *a = nl_object_priv(_a):
00153  *      struct my_obj *b = nl_object_priv(_b):
00154  *      int diff = 0;
00155  *
00156  *      // We help ourselves in defining our own DIFF macro which will
00157  *      // call ATTR_DIFF() on both objects which will make sure to only
00158  *      // compare the attributes if required.
00159  *      #define MY_DIFF(ATTR, EXPR) ATTR_DIFF(attrs, MY_ATTR_##ATTR, a, b, EXPR)
00160  *
00161  *      // Call our own diff macro for each attribute to build a bitmask
00162  *      // representing the attributes which mismatch.
00163  *      diff |= MY_DIFF(FOO, a->foo != b->foo)
00164  *      diff |= MY_DIFF(BAR, strcmp(a->bar, b->bar))
00165  *
00166  *      return diff;
00167  * }
00168  *
00169  * // In order to identify identical objects with differing attributes
00170  * // you must specify the attributes required to uniquely identify
00171  * // your object. Make sure to not include too many attributes, this
00172  * // list is used when caches look for an old version of an object.
00173  * struct nl_object_ops my_ops = {
00174  *      ...
00175  *      .oo_id_attrs            = MY_ATTR_FOO,
00176  *      .oo_compare             = my_obj_compare,
00177  * };
00178  * @endcode
00179  * @{
00180  */
00181 
00182 /**
00183  * Common Object Header
00184  *
00185  * This macro must be included as first member in every object
00186  * definition to allow objects to be cached.
00187  */
00188 #define NLHDR_COMMON                            \
00189         int                     ce_refcnt;      \
00190         struct nl_object_ops *  ce_ops;         \
00191         struct nl_cache *       ce_cache;       \
00192         struct nl_list_head     ce_list;        \
00193         int                     ce_msgtype;     \
00194         int                     ce_flags;       \
00195         uint32_t                ce_mask;
00196 
00197 /**
00198  * Return true if attribute is available in both objects
00199  * @arg A               an object
00200  * @arg B               another object
00201  * @arg ATTR            attribute bit
00202  *
00203  * @return True if the attribute is available, otherwise false is returned.
00204  */
00205 #define AVAILABLE(A, B, ATTR)   (((A)->ce_mask & (B)->ce_mask) & (ATTR))
00206 
00207 /**
00208  * Return true if attributes mismatch
00209  * @arg A               an object
00210  * @arg B               another object
00211  * @arg ATTR            attribute bit
00212  * @arg EXPR            Comparison expression
00213  *
00214  * This function will check if the attribute in question is available
00215  * in both objects, if not this will count as a mismatch.
00216  *
00217  * If available the function will execute the expression which must
00218  * return true if the attributes mismatch.
00219  *
00220  * @return True if the attribute mismatch, or false if they match.
00221  */
00222 #define ATTR_MISMATCH(A, B, ATTR, EXPR) (!AVAILABLE(A, B, ATTR) || (EXPR))
00223 
00224 /**
00225  * Return attribute bit if attribute does not match
00226  * @arg LIST            list of attributes to be compared
00227  * @arg ATTR            attribute bit
00228  * @arg A               an object
00229  * @arg B               another object
00230  * @arg EXPR            Comparison expression
00231  *
00232  * This function will check if the attribute in question is available
00233  * in both objects, if not this will count as a mismatch.
00234  *
00235  * If available the function will execute the expression which must
00236  * return true if the attributes mismatch.
00237  *
00238  * In case the attributes mismatch, the attribute is returned, otherwise
00239  * 0 is returned.
00240  *
00241  * @code
00242  * diff |= ATTR_DIFF(attrs, MY_ATTR_FOO, a, b, a->foo != b->foo);
00243  * @endcode
00244  */
00245 #define ATTR_DIFF(LIST, ATTR, A, B, EXPR) \
00246 ({      int diff = 0; \
00247         if (((LIST) & (ATTR)) && ATTR_MISMATCH(A, B, ATTR, EXPR)) \
00248                 diff = ATTR; \
00249         diff; })
00250 
00251 /**
00252  * Object Operations
00253  */
00254 struct nl_object_ops
00255 {
00256         /**
00257          * Unique name of object type
00258          *
00259          * Must be in the form family/name, e.g. "route/addr"
00260          */
00261         char *          oo_name;
00262 
00263         /** Size of object including its header */
00264         size_t          oo_size;
00265 
00266         /* List of attributes needed to uniquely identify the object */
00267         uint32_t        oo_id_attrs;
00268 
00269         /**
00270          * Constructor function
00271          *
00272          * Will be called when a new object of this type is allocated.
00273          * Can be used to initialize members such as lists etc.
00274          */
00275         void  (*oo_constructor)(struct nl_object *);
00276 
00277         /**
00278          * Destructor function
00279          *
00280          * Will be called when an object is freed. Must free all
00281          * resources which may have been allocated as part of this
00282          * object.
00283          */
00284         void  (*oo_free_data)(struct nl_object *);
00285 
00286         /**
00287          * Cloning function
00288          *
00289          * Will be called when an object needs to be cloned. Please
00290          * note that the generic object code will make an exact
00291          * copy of the object first, therefore you only need to take
00292          * care of members which require reference counting etc.
00293          *
00294          * May return a negative error code to abort cloning.
00295          */
00296         int  (*oo_clone)(struct nl_object *, struct nl_object *);
00297 
00298         /**
00299          * Dumping functions
00300          *
00301          * Will be called when an object is dumped. The implementations
00302          * have to use nl_dump(), nl_dump_line(), and nl_new_line() to
00303          * dump objects.
00304          *
00305          * The functions must return the number of lines printed.
00306          */
00307         int   (*oo_dump[NL_DUMP_MAX+1])(struct nl_object *,
00308                                         struct nl_dump_params *);
00309 
00310         /**
00311          * Comparison function
00312          *
00313          * Will be called when two objects of the same type are
00314          * compared. It takes the two objects in question, an object
00315          * specific bitmask defining which attributes should be
00316          * compared and flags to control the behaviour.
00317          *
00318          * The function must return a bitmask with the relevant bit
00319          * set for each attribute that mismatches.
00320          */
00321         int   (*oo_compare)(struct nl_object *, struct nl_object *,
00322                             uint32_t, int);
00323 
00324 
00325         char *(*oo_attrs2str)(int, char *, size_t);
00326 };
00327 
00328 /** @} */
00329 
00330 #ifdef __cplusplus
00331 }
00332 #endif
00333 
00334 #endif