[asterisk-dev] API changes 1.4.0 -> 1.6.0, review requested on specific files

[Russell Bryant]

Jeff Peeler wrote:
> ./include/asterisk/stringfields.h - Listed below are several removed
> defines that need either replacements listed or need verification they
> are no longer required.
> 
> -#define ast_string_field_count(x)
> -#define ast_string_field_index(x, field)
> -#define ast_string_field_index_free(x, index)
> -#define ast_string_field_free(x, field)
> -#define ast_string_field_free_pools(x)
> -#define ast_string_field_free_all(x)

The implementation has been reworked.  I don't think the first three were ever
used by any modules.  The same goes for string_field_free_pools().

The three free() variants were removed, and a single function was added called
ast_string_field_free_memory().  This was done to avoid confusion as to what you
were supposed to use to free all of the allocated memory for string fields in an
object.

Previously, where string_field_free() was used to basically NULL out a single
string field, you now simply do string_field_set(obj, field, NULL), instead.


> ./include/asterisk/threadstorage.h - Need to figure out where all the
> string handling defines/functions have gone.

We had multiple string APIs in Asterisk 1.4, some with overlapping
functionality.  A new API (ast_str) was written that centralizes all of the
string API code.  It's in strings.h.  This was done so that complex string
handling in Asterisk is more consistent.

> ./include/asterisk/aes.h - Lots of changes, not sure if the ability to
> use keys larger than 128 bits has been removed.

The changes here were made so that we used AES from the OpenSSL library, instead
of a seemingly arbitrary implementation that was included in the tree.  This was
done so that we were using a more reliable and well tested implementation.

> ./include/asterisk/lock.h - It appears that this file may have just been
> reorganized, but would like verification.

The locking API in 1.4 and trunk is the same.

> Functions that only have changed by adding the const qualifier or
> similar obvious changes have been listed but without explanation. Here
> is a small sample of what the documentation currently looks like:
> 
> ./channels/iax2-parser.h
> 
> -int outoforder;
> +unsigned int outoforder:1;
> 
> -int sentyet;
> +unsigned int sentyet:1;
> 
> -int transfer;
> -int final;
> -int direction;
> +unsigned int transfer:1;
> +unsigned int final:1;
> +unsigned int direction:2;
> +unsigned int cacheable:1;
> 
> /*! Amount of space _allocated_ for data */
> -size_t mallocd_datalen;
> +size_t afdatalen;
> 
> -struct iax_frame *iax_frame_new(int direction, int datalen);
> +struct iax_frame *iax_frame_new(int direction, int datalen, unsigned
> int cacheable);
> /Reason: cacheable: the iax_frame if marked as cacheable will stay in
> memory as long as low memory optimization has not been turned on.
> /Old behavior: Pass in 0 for cacheable.
> 
> Any formatting is up for debate. It would be nice if one person claimed
> a file and then emailed the changes. Once the changes have been merged
> I'll post the whole document for review.

It would be nice if you indicated which struct you are referring to when
documenting the struct members that changed.

-- 
Russell Bryant
Senior Software Engineer
Open Source Team Lead
Digium, Inc.