CLI: Create ast_cli_completion_vector.
[asterisk/asterisk.git] / include / asterisk / stringfields.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2006, Digium, Inc.
5  *
6  * Kevin P. Fleming <kpfleming@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20   \page Stringfields String Fields
21   \brief String fields in structures
22
23   This file contains objects and macros used to manage string
24   fields in structures without requiring them to be allocated
25   as fixed-size buffers or requiring individual allocations for
26   for each field.
27
28   Using this functionality is quite simple. An example structure
29   with three fields is defined like this:
30   
31   \code
32   struct sample_fields {
33           int x1;
34           AST_DECLARE_STRING_FIELDS(
35                   AST_STRING_FIELD(foo);
36                   AST_STRING_FIELD(bar);
37                   AST_STRING_FIELD(blah);
38           );
39           long x2;
40   };
41   \endcode
42   
43   When an instance of this structure is allocated (either statically or
44   dynamically), the fields and the pool of storage for them must be
45   initialized:
46   
47   \code
48   struct sample_fields *x;
49   
50   x = ast_calloc(1, sizeof(*x));
51   if (x == NULL || ast_string_field_init(x, 252)) {
52         if (x)
53                 ast_free(x);
54         x = NULL;
55         ... handle error
56   }
57   \endcode
58
59   Fields will default to pointing to an empty string, and will revert to
60   that when ast_string_field_set() is called with a NULL argument.
61   A string field will \b never contain NULL.
62
63   ast_string_field_init(x, 0) will reset fields to the
64   initial value while keeping the pool allocated.
65   
66   Reading the fields is much like using 'const char * const' fields in the
67   structure: you cannot write to the field or to the memory it points to.
68
69   Writing to the fields must be done using the wrapper macros listed below;
70   and assignments are always by value (i.e. strings are copied):
71   * ast_string_field_set() stores a simple value;
72   * ast_string_field_build() builds the string using a printf-style format;
73   * ast_string_field_build_va() is the varargs version of the above;
74   * variants of these function allow passing a pointer to the field
75     as an argument.
76
77   \code
78   ast_string_field_set(x, foo, "infinite loop");
79   ast_string_field_set(x, foo, NULL); // set to an empty string
80   ast_string_field_ptr_set(x, &x->bar, "right way");
81
82   ast_string_field_build(x, blah, "%d %s", zipcode, city);
83   ast_string_field_ptr_build(x, &x->blah, "%d %s", zipcode, city);
84
85   ast_string_field_build_va(x, bar, fmt, args)
86   ast_string_field_ptr_build_va(x, &x->bar, fmt, args)
87   \endcode
88
89   When the structure instance is no longer needed, the fields
90   and their storage pool must be freed:
91   
92   \code
93   ast_string_field_free_memory(x);
94   ast_free(x);
95   \endcode
96
97   A new feature "Extended String Fields" has been added in 13.9.0.
98
99   An extended field is one that is declared outside the AST_DECLARE_STRING_FIELDS
100   block but still inside the parent structure.  It's most useful for extending
101   structures where adding a new string field to an existing AST_DECLARE_STRING_FIELDS
102   block would break ABI compatibility.
103
104   Example:
105
106   \code
107   struct original_structure_version {
108       AST_DECLARE_STRING_FIELDS(
109           AST_STRING_FIELD(foo);
110           AST_STRING_FIELD(bar);
111       );
112       int x1;
113       int x2;
114   };
115   \endcode
116
117   Adding "blah" to the existing string fields breaks ABI compatibility because it changes
118   the offsets of x1 and x2.
119
120   \code
121   struct new_structure_version {
122       AST_DECLARE_STRING_FIELDS(
123           AST_STRING_FIELD(foo);
124           AST_STRING_FIELD(bar);
125           AST_STRING_FIELD(blah);
126       );
127       int x1;
128       int x2;
129   };
130   \endcode
131
132   However, adding "blah" as an extended string field to the end of the structure doesn't break
133   ABI compatibility but still allows the use of the existing pool.
134
135   \code
136   struct new_structure_version {
137       AST_DECLARE_STRING_FIELDS(
138           AST_STRING_FIELD(foo);
139           AST_STRING_FIELD(bar);
140       );
141       int x1;
142       int x2;
143       AST_STRING_FIELD_EXTENDED(blah);
144   };
145   \endcode
146
147   The only additional step required is to call ast_string_field_init_extended so the
148   pool knows about the new field.  It must be called AFTER ast_string_field_init or
149   ast_calloc_with_stringfields.  Although ast_calloc_with_stringfields is used in the
150   sample below, it's not necessary for extended string fields.
151
152   \code
153
154   struct new_structure_version *x = ast_calloc_with_stringfields(1, struct new_structure_version, 252);
155   if (!x) {
156       return;
157   }
158
159   ast_string_field_init_extended(x, blah);
160   \endcode
161
162   The new field can now be treated just like any other string field and it's storage will
163   be released with the rest of the string fields.
164
165   \code
166   ast_string_field_set(x, foo, "infinite loop");
167   ast_stringfield_free_memory(x);
168   ast_free(x);
169   \endcode
170
171   This completes the API description.
172 */
173
174 #ifndef _ASTERISK_STRINGFIELDS_H
175 #define _ASTERISK_STRINGFIELDS_H
176
177 #include "asterisk/inline_api.h"
178 #include "asterisk/vector.h"
179
180 /*!
181   \internal
182   \brief An opaque type for managed string fields in structures
183
184   Don't declare instances of this type directly; use the AST_STRING_FIELD()
185   macro instead.
186
187   In addition to the string itself, the amount of space allocated for the
188   field is stored in the two bytes immediately preceding it.
189 */
190 typedef const char * ast_string_field;
191
192 /* the type of storage used to track how many bytes were allocated for a field */
193
194 typedef uint16_t ast_string_field_allocation;
195
196 /*!
197   \internal
198   \brief A constant empty string used for fields that have no other value
199 */
200 extern const char *__ast_string_field_empty;
201
202 /*!
203   \internal
204   \brief Structure used to hold a pool of space for string fields
205   \note base is aligned so base+used can stay aligned by incrementing used with
206         aligned numbers only
207 */
208 struct ast_string_field_pool {
209         struct ast_string_field_pool *prev;     /*!< pointer to the previous pool, if any */
210         size_t size;                            /*!< the total size of the pool */
211         size_t used;                            /*!< the space used in the pool */
212         size_t active;                          /*!< the amount of space actively in use by fields */
213         char base[0] __attribute__((aligned(__alignof__(ast_string_field_allocation)))); /*!< storage space for the fields */
214 };
215
216 /*!
217   \internal
218   \brief The definition for the string field vector used for compare and copy
219   \since 13.9.0
220 */
221 AST_VECTOR(ast_string_field_vector, const char **);
222
223 /*!
224   \internal
225   \brief Structure used to manage the storage for a set of string fields.
226 */
227 struct ast_string_field_mgr {
228         ast_string_field last_alloc;                    /*!< the last field allocated */
229         struct ast_string_field_pool *embedded_pool;    /*!< pointer to the embedded pool, if any */
230         struct ast_string_field_vector string_fields;   /*!< field vector for compare and copy */
231 #if defined(__AST_DEBUG_MALLOC)
232         const char *owner_file;                         /*!< filename of owner */
233         const char *owner_func;                         /*!< function name of owner */
234         int owner_line;                                 /*!< line number of owner */
235 #endif
236 };
237
238 /*!
239   \internal
240   \brief Attempt to 'grow' an already allocated field to a larger size
241   \param mgr Pointer to the pool manager structure
242   \param needed Amount of space needed for this field
243   \param ptr Pointer to a field within the structure
244   \return 0 on success, non-zero on failure
245
246   This function will attempt to increase the amount of space allocated to
247   an existing field to the amount requested; this is only possible if the
248   field was the last field allocated from the current storage pool and
249   the pool has enough space available. If so, the additional space will be
250   allocated to this field and the field's address will not be changed.
251 */
252 int __ast_string_field_ptr_grow(struct ast_string_field_mgr *mgr,
253                                 struct ast_string_field_pool **pool_head, size_t needed,
254                                 const ast_string_field *ptr);
255
256 /*!
257   \internal
258   \brief Allocate space for a field
259   \param mgr Pointer to the pool manager structure
260   \param needed Amount of space needed for this field
261   \param fields Pointer to the first entry of the field array
262   \return NULL on failure, an address for the field on success.
263
264   This function will allocate the requested amount of space from
265   the field pool. If the requested amount of space is not available,
266   an additional pool will be allocated.
267 */
268 ast_string_field __ast_string_field_alloc_space(struct ast_string_field_mgr *mgr,
269                                                 struct ast_string_field_pool **pool_head, size_t needed);
270
271 /*!
272   \internal
273   \brief Set a field to a complex (built) value
274   \param mgr Pointer to the pool manager structure
275   \param pool_head Pointer to the current pool
276   \param ptr Pointer to a field within the structure
277   \param format printf-style format string
278   \return nothing
279 */
280 void __ast_string_field_ptr_build(struct ast_string_field_mgr *mgr,
281                                   struct ast_string_field_pool **pool_head,
282                                   ast_string_field *ptr, const char *format, ...) __attribute__((format(printf, 4, 5)));
283
284 /*!
285   \internal
286   \brief Set a field to a complex (built) value
287   \param mgr Pointer to the pool manager structure
288   \param pool_head Pointer to the current pool
289   \param ptr Pointer to a field within the structure
290   \param format printf-style format string
291   \param args va_list of the args for the format_string
292   \return nothing
293 */
294 void __ast_string_field_ptr_build_va(struct ast_string_field_mgr *mgr,
295                                      struct ast_string_field_pool **pool_head,
296                                      ast_string_field *ptr, const char *format, va_list ap) __attribute__((format(printf, 4, 0)));
297
298 /*!
299   \brief Declare a string field
300   \param name The field name
301 */
302 #define AST_STRING_FIELD(name) const ast_string_field name
303
304 /*!
305   \brief Declare an extended string field
306   \since 13.9.0
307
308   \param name The field name
309 */
310 #define AST_STRING_FIELD_EXTENDED(name) AST_STRING_FIELD(name)
311
312 enum ast_stringfield_cleanup_type {
313         /*!
314          * Reset all string fields and free all extra pools that may have been created
315          * The allocation or structure can be reused as is.
316          */
317         AST_STRINGFIELD_RESET = 0,
318         /*!
319          * Reset all string fields and free all pools.
320          * If the pointer was returned by ast_calloc_with_stringfields, it can NOT be reused
321          * and should be immediately freed.  Otherwise, you must call ast_string_field_init
322          * again if you want to reuse it.
323          */
324         AST_STRINGFIELD_DESTROY = -1,
325 };
326
327 /*!
328   \brief Declare the fields needed in a structure
329   \param field_list The list of fields to declare, using AST_STRING_FIELD() for each one.
330   Internally, string fields are stored as a pointer to the head of the pool,
331   followed by individual string fields, and then a struct ast_string_field_mgr
332   which describes the space allocated.
333   We split the two variables so they can be used as markers around the
334   field_list, and this allows us to determine how many entries are in
335   the field, and play with them.
336   In particular, for writing to the fields, we rely on __field_mgr_pool to be
337   a non-const pointer, so we know it has the same size as ast_string_field,
338   and we can use it to locate the fields.
339 */
340 #define AST_DECLARE_STRING_FIELDS(field_list) \
341         struct ast_string_field_pool *__field_mgr_pool; \
342         field_list                                      \
343         struct ast_string_field_mgr __field_mgr
344
345 /*!
346   \brief Initialize a field pool and fields
347   \param x Pointer to a structure containing fields
348   \param size Amount of storage to allocate.
349         Use AST_STRINGFIELD_RESET to reset fields to the default value,
350         and release all but the most recent pool.
351         AST_STRINGFIELD_DESTROY (used internally) means free all pools which is
352         equivalent to calling ast_string_field_free_memory.
353
354   \return 0 on success, non-zero on failure
355 */
356 #define ast_string_field_init(x, size) \
357 ({ \
358         int __res__ = -1; \
359         if (((void *)(x)) != NULL) { \
360                 __res__ = __ast_string_field_init(&(x)->__field_mgr, &(x)->__field_mgr_pool, size, __FILE__, __LINE__, __PRETTY_FUNCTION__); \
361         } \
362         __res__ ; \
363 })
364
365 /*!
366  * \brief free all memory - to be called before destroying the object
367  *
368  * \param x
369  *
370  */
371 #define ast_string_field_free_memory(x)  \
372 ({ \
373         int __res__ = -1; \
374         if (((void *)(x)) != NULL) { \
375                 __res__ = __ast_string_field_free_memory(&(x)->__field_mgr, &(x)->__field_mgr_pool, \
376                         AST_STRINGFIELD_DESTROY, __FILE__, __LINE__, __PRETTY_FUNCTION__); \
377         } \
378         __res__; \
379 })
380
381 int __ast_string_field_free_memory(struct ast_string_field_mgr *mgr,
382         struct ast_string_field_pool **pool_head, enum ast_stringfield_cleanup_type cleanup_type,
383         const char *file, int lineno, const char *func);
384
385 /*!
386  * \brief Initialize an extended string field
387  * \since 13.9.0
388  *
389  * \param x Pointer to a structure containing the field
390  * \param field The extended field to initialize
391  * \retval zero on success
392  * \retval non-zero on error
393  *
394  * \note
395  * This macro must be called on ALL fields defined with AST_STRING_FIELD_EXTENDED after
396  * ast_string_field_init has been called.
397  */
398 #define ast_string_field_init_extended(x, field) \
399 ({ \
400         int __res__ = -1; \
401         if (((void *)(x)) != NULL) { \
402                 ast_string_field *non_const = (ast_string_field *)&(x)->field; \
403                 *non_const = __ast_string_field_empty; \
404                 __res__ = AST_VECTOR_APPEND(&(x)->__field_mgr.string_fields, non_const); \
405         } \
406         __res__; \
407 })
408
409 /*!
410  * \internal
411  * \brief internal version of ast_string_field_init
412  */
413 int __ast_string_field_init(struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head,
414                             int needed, const char *file, int lineno, const char *func);
415
416 /*!
417  * \brief Allocate a structure with embedded stringfields in a single allocation
418  * \param n Current imlementation only allows 1 structure to be allocated
419  * \param type The type of structure to allocate
420  * \param size The number of bytes of space (minimum) to allocate for stringfields to use
421  *             in each structure
422  *
423  * This function will allocate memory for one or more structures that use stringfields, and
424  * also allocate space for the stringfields and initialize the stringfield management
425  * structure embedded in the outer structure.
426  *
427  * \since 1.8
428  */
429 #define ast_calloc_with_stringfields(n, type, size) \
430         __ast_calloc_with_stringfields(n, sizeof(type), offsetof(type, __field_mgr), \
431                 offsetof(type, __field_mgr_pool), size, __FILE__, __LINE__, __PRETTY_FUNCTION__)
432
433 /*!
434  * \internal
435  * \brief internal version of ast_calloc_with_stringfields
436  */
437 void * attribute_malloc __ast_calloc_with_stringfields(unsigned int num_structs,
438         size_t struct_size, size_t field_mgr_offset, size_t field_mgr_pool_offset, size_t pool_size,
439         const char *file, int lineno, const char *func);
440
441 /*!
442   \internal
443   \brief Release a field's allocation from a pool
444   \param pool_head Pointer to the current pool
445   \param ptr Field to be released
446   \return nothing
447
448   This function will search the pool list to find the pool that contains
449   the allocation for the specified field, then remove the field's allocation
450   from that pool's 'active' count. If the pool's active count reaches zero,
451   and it is not the current pool, then it will be freed.
452  */
453 void __ast_string_field_release_active(struct ast_string_field_pool *pool_head,
454                                        const ast_string_field ptr);
455
456 /*!
457   \brief Macro to provide access to the allocation field that lives immediately in front of a string field
458   \param x Pointer to the string field
459
460   Note that x must be a pointer to a byte-sized type -- normally (char *) -- or this calculation
461   would break horribly
462 */
463 #define AST_STRING_FIELD_ALLOCATION(x) *((ast_string_field_allocation *) (x - __alignof__(ast_string_field_allocation)))
464
465 /*!
466   \brief Set a field to a simple string value
467   \param x Pointer to a structure containing fields
468   \param ptr Pointer to a field within the structure
469   \param data String value to be copied into the field
470   \retval zero on success
471   \retval non-zero on error
472 */
473 #define ast_string_field_ptr_set(x, ptr, data) \
474 ({ \
475         int __res__ = -1; \
476         if (((void *)(x)) != NULL) { \
477                 __res__ = ast_string_field_ptr_set_by_fields((x)->__field_mgr_pool, (x)->__field_mgr, ptr, data); \
478         } \
479         __res__; \
480 })
481
482 #define ast_string_field_ptr_set_by_fields(field_mgr_pool, field_mgr, ptr, data)               \
483 ({                                                                                             \
484     int __res__ = 0;                                                                           \
485     const char *__d__ = (data);                                                                \
486     size_t __dlen__ = (__d__) ? strlen(__d__) + 1 : 1;                                         \
487     ast_string_field *__p__ = (ast_string_field *) (ptr);                                      \
488     ast_string_field target = *__p__;                                                          \
489     if (__dlen__ == 1) {                                                                       \
490         __ast_string_field_release_active(field_mgr_pool, *__p__);                             \
491         *__p__ = __ast_string_field_empty;                                                     \
492     } else if ((__dlen__ <= AST_STRING_FIELD_ALLOCATION(*__p__)) ||                            \
493            (!__ast_string_field_ptr_grow(&field_mgr, &field_mgr_pool, __dlen__, __p__)) ||     \
494            (target = __ast_string_field_alloc_space(&field_mgr, &field_mgr_pool, __dlen__))) { \
495         if (target != *__p__) {                                                                \
496             __ast_string_field_release_active(field_mgr_pool, *__p__);                         \
497             *__p__ = target;                                                                   \
498         }                                                                                      \
499         memcpy(* (void **) __p__, __d__, __dlen__);                                            \
500     } else {                                                                                   \
501         __res__ = -1;                                                                          \
502     }                                                                                          \
503     __res__;                                                                                   \
504 })
505
506 /*!
507   \brief Set a field to a simple string value
508   \param x Pointer to a structure containing fields
509   \param field Name of the field to set
510   \param data String value to be copied into the field
511   \retval zero on success
512   \retval non-zero on error
513 */
514 #define ast_string_field_set(x, field, data) \
515 ({ \
516         int __res__ = -1; \
517         if (((void *)(x)) != NULL) { \
518                 __res__ = ast_string_field_ptr_set(x, &(x)->field, data); \
519         } \
520         __res__; \
521 })
522
523 /*!
524   \brief Set a field to a complex (built) value
525   \param x Pointer to a structure containing fields
526   \param ptr Pointer to a field within the structure
527   \param fmt printf-style format string
528   \param args Arguments for format string
529   \return nothing
530 */
531 #define ast_string_field_ptr_build(x, ptr, fmt, args...) \
532 ({ \
533         int __res__ = -1; \
534         if (((void *)(x)) != NULL) { \
535                 __ast_string_field_ptr_build(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) ptr, fmt, args); \
536                 __res__ = 0; \
537         } \
538         __res__; \
539 })
540
541 /*!
542   \brief Set a field to a complex (built) value
543   \param x Pointer to a structure containing fields
544   \param field Name of the field to set
545   \param fmt printf-style format string
546   \param args Arguments for format string
547   \return nothing
548 */
549 #define ast_string_field_build(x, field, fmt, args...) \
550 ({ \
551         int __res__ = -1; \
552         if (((void *)(x)) != NULL) { \
553                 __ast_string_field_ptr_build(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) &(x)->field, fmt, args); \
554                 __res__ = 0; \
555         } \
556         __res__; \
557 })
558
559 /*!
560   \brief Set a field to a complex (built) value with prebuilt va_lists.
561   \param x Pointer to a structure containing fields
562   \param ptr Pointer to a field within the structure
563   \param fmt printf-style format string
564   \param args Arguments for format string in va_list format
565   \return nothing
566 */
567 #define ast_string_field_ptr_build_va(x, ptr, fmt, args) \
568 ({ \
569         int __res__ = -1; \
570         if (((void *)(x)) != NULL) { \
571                 __ast_string_field_ptr_build_va(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) ptr, fmt, args); \
572                 __res__ = 0; \
573         } \
574         __res__; \
575 })
576
577 /*!
578   \brief Set a field to a complex (built) value
579   \param x Pointer to a structure containing fields
580   \param field Name of the field to set
581   \param fmt printf-style format string
582   \param args Arguments for format string in va_list format
583   \return nothing
584 */
585 #define ast_string_field_build_va(x, field, fmt, args) \
586 ({ \
587         int __res__ = -1; \
588         if (((void *)(x)) != NULL) { \
589                 __ast_string_field_ptr_build_va(&(x)->__field_mgr, &(x)->__field_mgr_pool, (ast_string_field *) &(x)->field, fmt, args); \
590                 __res__ = 0; \
591         } \
592         __res__; \
593 })
594
595 /*!
596   \brief Compare the string fields in two instances of the same structure
597   \since 12
598   \param instance1 The first instance of the structure to be compared
599   \param instance2 The second instance of the structure to be compared
600   \retval zero if all string fields are equal (does not compare non-string field data)
601   \retval non-zero if the values of the string fields differ
602 */
603 #define ast_string_fields_cmp(instance1, instance2) \
604 ({ \
605         int __res__ = -1; \
606         if (((void *)(instance1)) != NULL && ((void *)(instance2)) != NULL) { \
607                 __res__ = __ast_string_fields_cmp(&(instance1)->__field_mgr.string_fields, \
608                         &(instance2)->__field_mgr.string_fields); \
609         } \
610         __res__; \
611 })
612
613 int __ast_string_fields_cmp(struct ast_string_field_vector *left, struct ast_string_field_vector *right);
614
615 /*!
616   \brief Copy all string fields from one instance to another of the same structure
617   \since 12
618   \param copy The instance of the structure to be copied into
619   \param orig The instance of the structure to be copied from
620   \retval zero on success
621   \retval non-zero on error
622 */
623 #define ast_string_fields_copy(copy, orig) \
624 ({ \
625         int __res__ = -1; \
626         if (((void *)(copy)) != NULL && ((void *)(orig)) != NULL) { \
627                 __res__ = __ast_string_fields_copy(((copy)->__field_mgr_pool), \
628                         (struct ast_string_field_mgr *)&((copy)->__field_mgr), \
629                         (struct ast_string_field_mgr *)&((orig)->__field_mgr)); \
630         } \
631         __res__; \
632 })
633
634 int __ast_string_fields_copy(struct ast_string_field_pool *copy_pool,
635         struct ast_string_field_mgr *copy_mgr, struct ast_string_field_mgr *orig_mgr);
636
637 #endif /* _ASTERISK_STRINGFIELDS_H */