[asterisk-dev] Format branch naming conventions

[Matthew Jordan]

Hey all -

I'm working on ASTERISK-23715 [1], which is a standardization/renaming
of public functions/structures affected by the media format work (in
the group/media_formats-reviewed branch). Two functions are called out
on ASTERISK-23715, but I've gone through the other major public header
files and made notes on other functions that I think could either use
renaming, could be removed, or just other general tweaks.

As an aside, I personally generally prefer the following nomenclature
for naming:

{namespace}_{object/unit}_{verb}_{target}

For example, if I wanted a function that retrieved an identifier from
a format, I would expect it to be named:

ast_format_get_id

Things get a bit more 'loose' when the item may exist in a particular
header, but may not fit well as the target of the verb. For example,
the format interface functions in format.h are less the target of the
verb and more the object/unit being affected.

Anyway:

-- format.h --

* ast_format_sdp_generate - rename to ast_format_sdp_generate_fmtp.
The purpose of the function is only to generate the fmtp, and we may
as well call that out. If we decide not to rename this, the API
documentation should probably get cleaned up to reflect that the
interface can generate whatever it wants for the SDP.

-- format_cache.h --

None

-- format_cap.h --

* include format.h, as functions in this header return enum
ast_format_cmp_res and use format structures extensively.

* ast_format_cap_remove_bytype - rename to ast_format_cap_remove_by_type.

* ast_getformatname_multiple - keep this function but deprecate it (it
is used extensively and has been around for awhile). Instead, provide
a renamed version: ast_format_cap_get_names(const struct
ast_format_cap *cap, char *buf, size_t size).

* ast_parse_allow_disallow - keep this function but deprecate it
(again, used extensively). Provide a renamed version: int
ast_format_cap_populate_from_config(struct ast_format_cap *, const
char *list, int allowing). Note that this function currently returns
the number of errors, but we rarely (if ever) check the return value.
Instead, this should just return 0 or -1, and the caller should verify
the return value.

-- format_compatibility.h --

* ast_codec_pref* - These will all get removed if possible.
format_pref is generally no longer needed. The biggest consumer of
these is chan_iax2: if possible, it will use ast_format_cap
structures.

Note that format preference is handled by the ast_format_cap
structure, and is the order in which the formats are added to the
capabilities structure (which uses a VECTOR to maintain the formats).

-- format_pref.h --

* Remove entirely.

-- codec.h --

* struct ast_codec - remove bitfield specification from smooth. As the
only bitfield in the structure, this is (a) unlikely to reduce the
size of the structure and (b) will generally require more instructions
to test given that it is a bitfield.

* ast_codec_determine_length - rename to ast_codec_get_length

* ast_codec_samples_count - move to frame.h. Rename to
ast_frame_get_codec_samples.

[1] https://issues.asterisk.org/jira/browse/ASTERISK-23715

-- 
Matthew Jordan
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org