libnl  3.2.21
object.c
1 /*
2  * lib/object.c Generic Cacheable Object
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-2012 Thomas Graf <tgraf@suug.ch>
10  */
11 
12 /**
13  * @ingroup core_types
14  * @defgroup object Object (Cacheable)
15  *
16  * Generic object data type, for inheritance purposes to implement cacheable
17  * data types.
18  *
19  * Related sections in the development guide:
20  *
21  * @{
22  *
23  * Header
24  * ------
25  * ~~~~{.c}
26  * #include <netlink/object.h>
27  * ~~~~
28  */
29 
30 #include <netlink-private/netlink.h>
31 #include <netlink/netlink.h>
32 #include <netlink/cache.h>
33 #include <netlink/object.h>
34 #include <netlink/utils.h>
35 
36 static inline struct nl_object_ops *obj_ops(struct nl_object *obj)
37 {
38  if (!obj->ce_ops)
39  BUG();
40 
41  return obj->ce_ops;
42 }
43 
44 /**
45  * @name Object Creation/Deletion
46  * @{
47  */
48 
49 /**
50  * Allocate a new object of kind specified by the operations handle
51  * @arg ops cache operations handle
52  * @return The new object or NULL
53  */
54 struct nl_object *nl_object_alloc(struct nl_object_ops *ops)
55 {
56  struct nl_object *new;
57 
58  if (ops->oo_size < sizeof(*new))
59  BUG();
60 
61  new = calloc(1, ops->oo_size);
62  if (!new)
63  return NULL;
64 
65  new->ce_refcnt = 1;
66  nl_init_list_head(&new->ce_list);
67 
68  new->ce_ops = ops;
69  if (ops->oo_constructor)
70  ops->oo_constructor(new);
71 
72  NL_DBG(4, "Allocated new object %p\n", new);
73 
74  return new;
75 }
76 
77 /**
78  * Allocate new object of kind specified by the name
79  * @arg kind name of object type
80  * @arg result Result pointer
81  *
82  * @return 0 on success or a negative error code.
83  */
84 int nl_object_alloc_name(const char *kind, struct nl_object **result)
85 {
86  struct nl_cache_ops *ops;
87 
88  ops = nl_cache_ops_lookup_safe(kind);
89  if (!ops)
90  return -NLE_OPNOTSUPP;
91 
92  *result = nl_object_alloc(ops->co_obj_ops);
93  nl_cache_ops_put(ops);
94  if (!*result)
95  return -NLE_NOMEM;
96 
97  return 0;
98 }
99 
101  NLHDR_COMMON
102  char data;
103 };
104 
105 /**
106  * Allocate a new object and copy all data from an existing object
107  * @arg obj object to inherite data from
108  * @return The new object or NULL.
109  */
110 struct nl_object *nl_object_clone(struct nl_object *obj)
111 {
112  struct nl_object *new;
113  struct nl_object_ops *ops = obj_ops(obj);
114  int doff = offsetof(struct nl_derived_object, data);
115  int size;
116 
117  new = nl_object_alloc(ops);
118  if (!new)
119  return NULL;
120 
121  size = ops->oo_size - doff;
122  if (size < 0)
123  BUG();
124 
125  new->ce_ops = obj->ce_ops;
126  new->ce_msgtype = obj->ce_msgtype;
127  new->ce_mask = obj->ce_mask;
128 
129  if (size)
130  memcpy((void *)new + doff, (void *)obj + doff, size);
131 
132  if (ops->oo_clone) {
133  if (ops->oo_clone(new, obj) < 0) {
134  nl_object_free(new);
135  return NULL;
136  }
137  } else if (size && ops->oo_free_data)
138  BUG();
139 
140  return new;
141 }
142 
143 /**
144  * Merge a cacheable object
145  * @arg dst object to be merged into
146  * @arg src new object to be merged into dst
147  *
148  * @return 0 or a negative error code.
149  */
150 int nl_object_update(struct nl_object *dst, struct nl_object *src)
151 {
152  struct nl_object_ops *ops = obj_ops(dst);
153 
154  if (ops->oo_update)
155  return ops->oo_update(dst, src);
156 
157  return -NLE_OPNOTSUPP;
158 }
159 
160 /**
161  * Free a cacheable object
162  * @arg obj object to free
163  *
164  * @return 0 or a negative error code.
165  */
166 void nl_object_free(struct nl_object *obj)
167 {
168  struct nl_object_ops *ops = obj_ops(obj);
169 
170  if (obj->ce_refcnt > 0)
171  NL_DBG(1, "Warning: Freeing object in use...\n");
172 
173  if (obj->ce_cache)
174  nl_cache_remove(obj);
175 
176  if (ops->oo_free_data)
177  ops->oo_free_data(obj);
178 
179  free(obj);
180 
181  NL_DBG(4, "Freed object %p\n", obj);
182 }
183 
184 /** @} */
185 
186 /**
187  * @name Reference Management
188  * @{
189  */
190 
191 /**
192  * Acquire a reference on a object
193  * @arg obj object to acquire reference from
194  */
195 void nl_object_get(struct nl_object *obj)
196 {
197  obj->ce_refcnt++;
198  NL_DBG(4, "New reference to object %p, total %d\n",
199  obj, obj->ce_refcnt);
200 }
201 
202 /**
203  * Release a reference from an object
204  * @arg obj object to release reference from
205  */
206 void nl_object_put(struct nl_object *obj)
207 {
208  if (!obj)
209  return;
210 
211  obj->ce_refcnt--;
212  NL_DBG(4, "Returned object reference %p, %d remaining\n",
213  obj, obj->ce_refcnt);
214 
215  if (obj->ce_refcnt < 0)
216  BUG();
217 
218  if (obj->ce_refcnt <= 0)
219  nl_object_free(obj);
220 }
221 
222 /**
223  * Check whether this object is used by multiple users
224  * @arg obj object to check
225  * @return true or false
226  */
227 int nl_object_shared(struct nl_object *obj)
228 {
229  return obj->ce_refcnt > 1;
230 }
231 
232 /** @} */
233 
234 /**
235  * @name Marks
236  * @{
237  */
238 
239 /**
240  * Add mark to object
241  * @arg obj Object to mark
242  */
243 void nl_object_mark(struct nl_object *obj)
244 {
245  obj->ce_flags |= NL_OBJ_MARK;
246 }
247 
248 /**
249  * Remove mark from object
250  * @arg obj Object to unmark
251  */
252 void nl_object_unmark(struct nl_object *obj)
253 {
254  obj->ce_flags &= ~NL_OBJ_MARK;
255 }
256 
257 /**
258  * Return true if object is marked
259  * @arg obj Object to check
260  * @return true if object is marked, otherwise false
261  */
262 int nl_object_is_marked(struct nl_object *obj)
263 {
264  return (obj->ce_flags & NL_OBJ_MARK);
265 }
266 
267 /** @} */
268 
269 /**
270  * @name Utillities
271  * @{
272  */
273 
274 /**
275  * Dump this object according to the specified parameters
276  * @arg obj object to dump
277  * @arg params dumping parameters
278  */
279 void nl_object_dump(struct nl_object *obj, struct nl_dump_params *params)
280 {
281  if (params->dp_buf)
282  memset(params->dp_buf, 0, params->dp_buflen);
283 
284  dump_from_ops(obj, params);
285 }
286 
287 void nl_object_dump_buf(struct nl_object *obj, char *buf, size_t len)
288 {
289  struct nl_dump_params dp = {
290  .dp_buf = buf,
291  .dp_buflen = len,
292  };
293 
294  return nl_object_dump(obj, &dp);
295 }
296 
297 /**
298  * Check if the identifiers of two objects are identical
299  * @arg a an object
300  * @arg b another object of same type
301  *
302  * @return true if both objects have equal identifiers, otherwise false.
303  */
304 int nl_object_identical(struct nl_object *a, struct nl_object *b)
305 {
306  struct nl_object_ops *ops = obj_ops(a);
307  uint32_t req_attrs;
308 
309  /* Both objects must be of same type */
310  if (ops != obj_ops(b))
311  return 0;
312 
313  if (ops->oo_id_attrs_get) {
314  int req_attrs_a = ops->oo_id_attrs_get(a);
315  int req_attrs_b = ops->oo_id_attrs_get(b);
316  if (req_attrs_a != req_attrs_b)
317  return 0;
318  req_attrs = req_attrs_a;
319  } else {
320  req_attrs = ops->oo_id_attrs;
321  }
322  if (req_attrs == 0xFFFFFFFF)
323  req_attrs = a->ce_mask & b->ce_mask;
324 
325  /* Both objects must provide all required attributes to uniquely
326  * identify an object */
327  if ((a->ce_mask & req_attrs) != req_attrs ||
328  (b->ce_mask & req_attrs) != req_attrs)
329  return 0;
330 
331  /* Can't judge unless we can compare */
332  if (ops->oo_compare == NULL)
333  return 0;
334 
335  return !(ops->oo_compare(a, b, req_attrs, 0));
336 }
337 
338 /**
339  * Compute bitmask representing difference in attribute values
340  * @arg a an object
341  * @arg b another object of same type
342  *
343  * The bitmask returned is specific to an object type, each bit set represents
344  * an attribute which mismatches in either of the two objects. Unavailability
345  * of an attribute in one object and presence in the other is regarded a
346  * mismatch as well.
347  *
348  * @return Bitmask describing differences or 0 if they are completely identical.
349  */
350 uint32_t nl_object_diff(struct nl_object *a, struct nl_object *b)
351 {
352  struct nl_object_ops *ops = obj_ops(a);
353 
354  if (ops != obj_ops(b) || ops->oo_compare == NULL)
355  return UINT_MAX;
356 
357  return ops->oo_compare(a, b, ~0, 0);
358 }
359 
360 /**
361  * Match a filter against an object
362  * @arg obj object to check
363  * @arg filter object of same type acting as filter
364  *
365  * @return 1 if the object matches the filter or 0
366  * if no filter procedure is available or if the
367  * filter does not match.
368  */
369 int nl_object_match_filter(struct nl_object *obj, struct nl_object *filter)
370 {
371  struct nl_object_ops *ops = obj_ops(obj);
372 
373  if (ops != obj_ops(filter) || ops->oo_compare == NULL)
374  return 0;
375 
376  return !(ops->oo_compare(obj, filter, filter->ce_mask,
377  LOOSE_COMPARISON));
378 }
379 
380 /**
381  * Convert bitmask of attributes to a character string
382  * @arg obj object of same type as attribute bitmask
383  * @arg attrs bitmask of attribute types
384  * @arg buf destination buffer
385  * @arg len length of destination buffer
386  *
387  * Converts the bitmask of attribute types into a list of attribute
388  * names separated by comas.
389  *
390  * @return destination buffer.
391  */
392 char *nl_object_attrs2str(struct nl_object *obj, uint32_t attrs,
393  char *buf, size_t len)
394 {
395  struct nl_object_ops *ops = obj_ops(obj);
396 
397  if (ops->oo_attrs2str != NULL)
398  return ops->oo_attrs2str(attrs, buf, len);
399  else {
400  memset(buf, 0, len);
401  return buf;
402  }
403 }
404 
405 /**
406  * Return list of attributes present in an object
407  * @arg obj an object
408  * @arg buf destination buffer
409  * @arg len length of destination buffer
410  *
411  * @return destination buffer.
412  */
413 char *nl_object_attr_list(struct nl_object *obj, char *buf, size_t len)
414 {
415  return nl_object_attrs2str(obj, obj->ce_mask, buf, len);
416 }
417 
418 /**
419  * Generate object hash key
420  * @arg obj the object
421  * @arg hashkey destination buffer to be used for key stream
422  * @arg hashtbl_sz hash table size
423  *
424  * @return hash key in destination buffer
425  */
426 void nl_object_keygen(struct nl_object *obj, uint32_t *hashkey,
427  uint32_t hashtbl_sz)
428 {
429  struct nl_object_ops *ops = obj_ops(obj);
430 
431  if (ops->oo_keygen)
432  ops->oo_keygen(obj, hashkey, hashtbl_sz);
433  else
434  *hashkey = 0;
435 
436  return;
437 }
438 
439 /** @} */
440 
441 /**
442  * @name Attributes
443  * @{
444  */
445 
446 /**
447  * Return number of references held
448  * @arg obj object
449  *
450  * @return The number of references held to this object
451  */
452 int nl_object_get_refcnt(struct nl_object *obj)
453 {
454  return obj->ce_refcnt;
455 }
456 
457 /**
458  * Return cache the object is associated with
459  * @arg obj object
460  *
461  * @note The returned pointer is not protected with a reference counter,
462  * it is your responsibility.
463  *
464  * @return Pointer to cache or NULL if not associated with a cache.
465  */
466 struct nl_cache *nl_object_get_cache(struct nl_object *obj)
467 {
468  return obj->ce_cache;
469 }
470 
471 /**
472  * Return the object's type
473  * @arg obj object
474  *
475  * FIXME: link to list of object types
476  *
477  * @return Name of the object type
478  */
479 const char *nl_object_get_type(const struct nl_object *obj)
480 {
481  if (!obj->ce_ops)
482  BUG();
483 
484  return obj->ce_ops->oo_name;
485 }
486 
487 /**
488  * Return the netlink message type the object was derived from
489  * @arg obj object
490  *
491  * @return Netlink message type or 0.
492  */
493 int nl_object_get_msgtype(const struct nl_object *obj)
494 {
495  return obj->ce_msgtype;
496 }
497 
498 /**
499  * Return object operations structure
500  * @arg obj object
501  *
502  * @return Pointer to the object operations structure
503  */
504 struct nl_object_ops *nl_object_get_ops(const struct nl_object *obj)
505 {
506  return obj->ce_ops;
507 }
508 
509 /**
510  * Return object id attribute mask
511  * @arg obj object
512  *
513  * @return object id attribute mask
514  */
515 uint32_t nl_object_get_id_attrs(struct nl_object *obj)
516 {
517  struct nl_object_ops *ops = obj_ops(obj);
518  uint32_t id_attrs;
519 
520  if (!ops)
521  return 0;
522 
523  if (ops->oo_id_attrs_get)
524  id_attrs = ops->oo_id_attrs_get(obj);
525  else
526  id_attrs = ops->oo_id_attrs;
527 
528  return id_attrs;
529 }
530 
531 /** @} */
532 
533 /** @} */