String Fields

String fields in structures

This file contains objects and macros used to manage string fields in structures without requiring them to be allocated as fixed-size buffers or requiring individual allocations for for each field.

Using this functionality is quite simple. An example structure with three fields is defined like this:

struct sample_fields {
   int x1;
   AST_DECLARE_STRING_FIELDS(
     AST_STRING_FIELD(foo);
     AST_STRING_FIELD(bar);
     AST_STRING_FIELD(blah);
   );
   long x2;
};

When an instance of this structure is allocated (either statically or dynamically), the fields and the pool of storage for them must be initialized:

struct sample_fields *x;

x = ast_calloc(1, sizeof(*x));
if (x == NULL || ast_string_field_init(x, 252)) {
 if (x)
   ast_free(x);
 x = NULL;
   ... handle error
}

Fields will default to pointing to an empty string, and will revert to that when ast_string_field_set() is called with a NULL argument. A string field will never contain NULL.

ast_string_field_init(x, 0) will reset fields to the initial value while keeping the pool allocated.

Reading the fields is much like using 'const char * const' fields in the structure: you cannot write to the field or to the memory it points to.

Writing to the fields must be done using the wrapper macros listed below; and assignments are always by value (i.e. strings are copied): ast_string_field_set() stores a simple value; ast_string_field_build() builds the string using a printf-style format; ast_string_field_build_va() is the varargs version of the above; variants of these function allow passing a pointer to the field as an argument.

ast_string_field_set(x, foo, "infinite loop");
ast_string_field_set(x, foo, NULL); // set to an empty string
ast_string_field_ptr_set(x, &x->bar, "right way");

ast_string_field_build(x, blah, "%d %s", zipcode, city);
ast_string_field_ptr_build(x, &x->blah, "%d %s", zipcode, city);

ast_string_field_build_va(x, bar, fmt, args)
ast_string_field_ptr_build_va(x, &x->bar, fmt, args)

When the structure instance is no longer needed, the fields and their storage pool must be freed:

ast_string_field_free_memory(x);
ast_free(x);

A new feature "Extended String Fields" has been added in 13.9.0.

An extended field is one that is declared outside the AST_DECLARE_STRING_FIELDS block but still inside the parent structure. It's most useful for extending structures where adding a new string field to an existing AST_DECLARE_STRING_FIELDS block would break ABI compatibility.

Example:

struct original_structure_version {
    AST_DECLARE_STRING_FIELDS(
        AST_STRING_FIELD(foo);
        AST_STRING_FIELD(bar);
    );
    int x1;
    int x2;
};

Adding "blah" to the existing string fields breaks ABI compatibility because it changes the offsets of x1 and x2.

struct new_structure_version {
    AST_DECLARE_STRING_FIELDS(
        AST_STRING_FIELD(foo);
        AST_STRING_FIELD(bar);
        AST_STRING_FIELD(blah);
    );
    int x1;
    int x2;
};

However, adding "blah" as an extended string field to the end of the structure doesn't break ABI compatibility but still allows the use of the existing pool.

struct new_structure_version {
    AST_DECLARE_STRING_FIELDS(
        AST_STRING_FIELD(foo);
        AST_STRING_FIELD(bar);
    );
    int x1;
    int x2;
    AST_STRING_FIELD_EXTENDED(blah);
};

The only additional step required is to call ast_string_field_init_extended so the pool knows about the new field. It must be called AFTER ast_string_field_init or ast_calloc_with_stringfields. Although ast_calloc_with_stringfields is used in the sample below, it's not necessary for extended string fields.

struct new_structure_version *x = ast_calloc_with_stringfields(1, struct new_structure_version, 252);
if (!x) {
    return;
}

ast_string_field_init_extended(x, blah);

The new field can now be treated just like any other string field and it's storage will be released with the rest of the string fields.

ast_string_field_set(x, foo, "infinite loop");
ast_stringfield_free_memory(x);
ast_free(x);

This completes the API description.