translate.h File Reference

Support for translation of data formats. translate.c. More...

#include "asterisk/frame.h"
#include "asterisk/plc.h"
#include "asterisk/linkedlists.h"
#include "asterisk/format_cap.h"
#include "asterisk/format_cache.h"

Include dependency graph for translate.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_trans_pvt
	Default structure for translators, with the basic fields and buffers, all allocated as part of the same chunk of memory. The buffer is preceded by AST_FRIENDLY_OFFSET bytes in front of the user portion. 'buf' points right after this space. More...
struct	ast_translator
	Descriptor of a translator. More...

Macros
#define	ast_register_translator(t)   __ast_register_translator(t, AST_MODULE_SELF)
	See __ast_register_translator() More...

Enumerations
enum	ast_trans_cost_table {   AST_TRANS_COST_LL_LL_ORIGSAMP = 400000 , AST_TRANS_COST_LL_LY_ORIGSAMP = 600000 , AST_TRANS_COST_LL_LL_UPSAMP = 800000 , AST_TRANS_COST_LL_LY_UPSAMP = 825000 ,   AST_TRANS_COST_LL_LL_DOWNSAMP = 850000 , AST_TRANS_COST_LL_LY_DOWNSAMP = 875000 , AST_TRANS_COST_LL_UNKNOWN = 885000 , AST_TRANS_COST_LY_LL_ORIGSAMP = 900000 ,   AST_TRANS_COST_LY_LY_ORIGSAMP = 915000 , AST_TRANS_COST_LY_LL_UPSAMP = 930000 , AST_TRANS_COST_LY_LY_UPSAMP = 945000 , AST_TRANS_COST_LY_LL_DOWNSAMP = 960000 ,   AST_TRANS_COST_LY_LY_DOWNSAMP = 975000 , AST_TRANS_COST_LY_UNKNOWN = 985000 }
	Translator Cost Table definition. More...

Functions
int	__ast_register_translator (struct ast_translator *t, struct ast_module *module)
	Register a translator This registers a codec translator with asterisk. More...
struct ast_frame *	ast_trans_frameout (struct ast_trans_pvt *pvt, int datalen, int samples)
	generic frameout function More...
struct ast_frame *	ast_translate (struct ast_trans_pvt *tr, struct ast_frame *f, int consume)
	translates one or more frames Apply an input frame into the translator and receive zero or one output frames. Consume determines whether the original frame should be freed. In case the frame type is AST_FRAME_RTCP, the frame is not translated but passed to the translator codecs via the feedback callback, and a pointer to ast_null_frame is returned after that. More...
void	ast_translate_available_formats (struct ast_format_cap *dest, struct ast_format_cap *src, struct ast_format_cap *result)
	Find available formats. More...
int	ast_translate_init (void)
	Initialize the translation matrix and index to format conversion table. More...
unsigned int	ast_translate_path_steps (struct ast_format *dest, struct ast_format *src)
	Returns the number of steps required to convert from 'src' to 'dest'. More...
const char *	ast_translate_path_to_str (struct ast_trans_pvt *t, struct ast_str **str)
	Puts a string representation of the translation path into outbuf. More...
void	ast_translator_activate (struct ast_translator *t)
	Activate a previously deactivated translator. More...
int	ast_translator_best_choice (struct ast_format_cap *dst_cap, struct ast_format_cap *src_cap, struct ast_format **dst_fmt_out, struct ast_format **src_fmt_out)
	Chooses the best translation path. More...
struct ast_trans_pvt *	ast_translator_build_path (struct ast_format *dest, struct ast_format *source)
	Builds a translator path Build a path (possibly NULL) from source to dest. More...
void	ast_translator_deactivate (struct ast_translator *t)
	Deactivate a translator. More...
void	ast_translator_free_path (struct ast_trans_pvt *tr)
	Frees a translator path Frees the given translator path structure. More...
int	ast_unregister_translator (struct ast_translator *t)
	Unregister a translator Unregisters the given translator. More...

Detailed Description

Support for translation of data formats. translate.c.

Definition in file translate.h.

Macro Definition Documentation

ast_register_translator

#define ast_register_translator

(

t

)

__ast_register_translator(t, AST_MODULE_SELF)

See __ast_register_translator()

Definition at line 258 of file translate.h.

Enumeration Type Documentation

ast_trans_cost_table

enum ast_trans_cost_table

Translator Cost Table definition.

Note

The defined values in this table must be used to set the translator's table_cost value.

The cost value of the first two values must always add up to be greater than the largest value defined in this table. This is done to guarantee a direct translation will always have precedence over a multi step translation.

This table is built in a way that allows translation paths to be built that guarantee the best possible balance between performance and quality. With this table direct translation paths between two formats will always take precedence over multi step paths, lossless intermediate steps will always be chosen over lossy intermediate steps, and preservation of sample rate across the translation will always have precedence over a path that involves any re-sampling.

Enumerator
AST_TRANS_COST_LL_LL_ORIGSAMP	[lossless -> lossless] original sampling
AST_TRANS_COST_LL_LY_ORIGSAMP	[lossless -> lossy] original sampling
AST_TRANS_COST_LL_LL_UPSAMP	[lossless -> lossless] up sample
AST_TRANS_COST_LL_LY_UPSAMP	[lossless -> lossy] up sample
AST_TRANS_COST_LL_LL_DOWNSAMP	[lossless -> lossless] down sample
AST_TRANS_COST_LL_LY_DOWNSAMP	[lossless -> lossy] down sample
AST_TRANS_COST_LL_UNKNOWN	[lossless -> unknown] unknown. This value is for a lossless source translation with an unknown destination and or sample rate conversion.
AST_TRANS_COST_LY_LL_ORIGSAMP	[lossy -> lossless] original sampling
AST_TRANS_COST_LY_LY_ORIGSAMP	[lossy -> lossy] original sampling
AST_TRANS_COST_LY_LL_UPSAMP	[lossy -> lossless] up sample
AST_TRANS_COST_LY_LY_UPSAMP	[lossy -> lossy] up sample
AST_TRANS_COST_LY_LL_DOWNSAMP	[lossy -> lossless] down sample
AST_TRANS_COST_LY_LY_DOWNSAMP	[lossy -> lossy] down sample
AST_TRANS_COST_LY_UNKNOWN	[lossy -> unknown] unknown. This value is for a lossy source translation with an unknown destination and or sample rate conversion.

Definition at line 61 of file translate.h.

                          {
 
    /* Lossless Source Translation Costs */
 
    /*! [lossless -> lossless] original sampling */
    AST_TRANS_COST_LL_LL_ORIGSAMP = 400000,
    /*! [lossless -> lossy]    original sampling */
    AST_TRANS_COST_LL_LY_ORIGSAMP = 600000,
 
    /*! [lossless -> lossless] up sample */
    AST_TRANS_COST_LL_LL_UPSAMP   = 800000,
    /*! [lossless -> lossy]    up sample */
    AST_TRANS_COST_LL_LY_UPSAMP   = 825000,
 
    /*! [lossless -> lossless] down sample */
    AST_TRANS_COST_LL_LL_DOWNSAMP = 850000,
    /*! [lossless -> lossy]    down sample */
    AST_TRANS_COST_LL_LY_DOWNSAMP = 875000,
 
    /*! [lossless -> unknown]    unknown.
     * This value is for a lossless source translation
     * with an unknown destination and or sample rate conversion. */
    AST_TRANS_COST_LL_UNKNOWN     = 885000,
 
    /* Lossy Source Translation Costs */
 
    /*! [lossy -> lossless]    original sampling */
    AST_TRANS_COST_LY_LL_ORIGSAMP = 900000,
    /*! [lossy -> lossy]       original sampling */
    AST_TRANS_COST_LY_LY_ORIGSAMP = 915000,
 
    /*! [lossy -> lossless]    up sample */
    AST_TRANS_COST_LY_LL_UPSAMP   = 930000,
    /*! [lossy -> lossy]       up sample */
    AST_TRANS_COST_LY_LY_UPSAMP   = 945000,
 
    /*! [lossy -> lossless]    down sample */
    AST_TRANS_COST_LY_LL_DOWNSAMP = 960000,
    /*! [lossy -> lossy]       down sample */
    AST_TRANS_COST_LY_LY_DOWNSAMP = 975000,
 
    /*! [lossy -> unknown]    unknown.
     * This value is for a lossy source translation
     * with an unknown destination and or sample rate conversion. */
    AST_TRANS_COST_LY_UNKNOWN     = 985000,
 
};

Function Documentation

__ast_register_translator()

int __ast_register_translator	(	struct ast_translator *	t,
		struct ast_module *	mod
	)

Register a translator This registers a codec translator with asterisk.

Parameters

t	populated ast_translator structure
mod	module handle to the module that owns this translator

Return values

0	on success
-1	on failure

Register a translator This registers a codec translator with asterisk.

Definition at line 1237 of file translate.c.

{
    struct ast_translator *u;
    char tmp[80];
    RAII_VAR(struct ast_codec *, src_codec, NULL, ao2_cleanup);
    RAII_VAR(struct ast_codec *, dst_codec, NULL, ao2_cleanup);
 
    src_codec = ast_codec_get(t->src_codec.name, t->src_codec.type, t->src_codec.sample_rate);
    if (!src_codec) {
        ast_assert(0);
        ast_log(LOG_WARNING, "Failed to register translator: unknown source codec %s\n", t->src_codec.name);
        return -1;
    }
 
    dst_codec = ast_codec_get(t->dst_codec.name, t->dst_codec.type, t->dst_codec.sample_rate);
    if (!dst_codec) {
        ast_log(LOG_WARNING, "Failed to register translator: unknown destination codec %s\n", t->dst_codec.name);
        return -1;
    }
 
    if (add_codec2index(src_codec) || add_codec2index(dst_codec)) {
        if (matrix_resize(0)) {
            ast_log(LOG_WARNING, "Translator matrix can not represent any more translators.  Out of resources.\n");
            return -1;
        }
        add_codec2index(src_codec);
        add_codec2index(dst_codec);
    }
 
    if (!mod) {
        ast_log(LOG_WARNING, "Missing module pointer, you need to supply one\n");
        return -1;
    }
 
    if (!t->buf_size) {
        ast_log(LOG_WARNING, "empty buf size, you need to supply one\n");
        return -1;
    }
    if (!t->table_cost && !(t->table_cost = generate_table_cost(src_codec, dst_codec))) {
        ast_log(LOG_WARNING, "Table cost could not be generated for %s, "
            "Please set table_cost variable on translator.\n", t->name);
        return -1;
    }
 
    t->module = mod;
    t->src_fmt_index = codec2index(src_codec);
    t->dst_fmt_index = codec2index(dst_codec);
    t->active = 1;
 
    if (t->src_fmt_index < 0 || t->dst_fmt_index < 0) {
        ast_log(LOG_WARNING, "Invalid translator path: (%s codec is not valid)\n", t->src_fmt_index < 0 ? "starting" : "ending");
        return -1;
    }
    if (t->src_fmt_index >= cur_max_index) {
        ast_log(LOG_WARNING, "Source codec %s is larger than cur_max_index\n", t->src_codec.name);
        return -1;
    }
 
    if (t->dst_fmt_index >= cur_max_index) {
        ast_log(LOG_WARNING, "Destination codec %s is larger than cur_max_index\n", t->dst_codec.name);
        return -1;
    }
 
    if (t->buf_size) {
        /*
         * Align buf_size properly, rounding up to the machine-specific
         * alignment for pointers.
         */
        struct _test_align { void *a, *b; } p;
        int align = (char *)&p.b - (char *)&p.a;
 
        t->buf_size = ((t->buf_size + align - 1) / align) * align;
    }
 
    if (t->frameout == NULL) {
        t->frameout = default_frameout;
    }
 
    generate_computational_cost(t, 1);
 
    ast_verb(5, "Registered translator '%s' from codec %s to %s, table cost, %d, computational cost %d\n",
         term_color(tmp, t->name, COLOR_MAGENTA, COLOR_BLACK, sizeof(tmp)),
         t->src_codec.name, t->dst_codec.name, t->table_cost, t->comp_cost);
 
    AST_RWLIST_WRLOCK(&translators);
 
    /* find any existing translators that provide this same srcfmt/dstfmt,
       and put this one in order based on computational cost */
    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&translators, u, list) {
        if ((u->src_fmt_index == t->src_fmt_index) &&
            (u->dst_fmt_index == t->dst_fmt_index) &&
            (u->comp_cost > t->comp_cost)) {
            AST_RWLIST_INSERT_BEFORE_CURRENT(t, list);
            t = NULL;
            break;
        }
    }
    AST_RWLIST_TRAVERSE_SAFE_END;
 
    /* if no existing translator was found for this codec combination,
       add it to the beginning of the list */
    if (t) {
        AST_RWLIST_INSERT_HEAD(&translators, t, list);
    }
 
    matrix_rebuild(0);
 
    AST_RWLIST_UNLOCK(&translators);
 
    return 0;
}

References a, ast_translator::active, add_codec2index(), ao2_cleanup, ast_assert, ast_codec_get(), ast_log, AST_RWLIST_INSERT_BEFORE_CURRENT, AST_RWLIST_INSERT_HEAD, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_verb, b, ast_translator::buf_size, codec2index(), COLOR_BLACK, COLOR_MAGENTA, ast_translator::comp_cost, cur_max_index, default_frameout(), ast_translator::dst_codec, ast_translator::dst_fmt_index, ast_translator::frameout, generate_computational_cost(), generate_table_cost(), LOG_WARNING, matrix_rebuild(), matrix_resize(), ast_translator::module, ast_codec::name, ast_translator::name, NULL, RAII_VAR, ast_codec::sample_rate, ast_translator::src_codec, ast_translator::src_fmt_index, ast_translator::table_cost, term_color(), tmp(), and ast_codec::type.

ast_trans_frameout()

struct ast_frame * ast_trans_frameout	(	struct ast_trans_pvt *	pvt,
		int	datalen,
		int	samples
	)

generic frameout function

generic frameout function

Definition at line 439 of file translate.c.

{
    struct ast_frame *f = &pvt->f;
 
    if (samples) {
        f->samples = samples;
    } else {
        if (pvt->samples == 0) {
            return NULL;
        }
        f->samples = pvt->samples;
        pvt->samples = 0;
    }
    if (datalen) {
        f->datalen = datalen;
        f->data.ptr = pvt->outbuf.c;
    } else {
        f->datalen = pvt->datalen;
        if (!f->datalen) {
            f->data.ptr = NULL;
        } else {
            f->data.ptr = pvt->outbuf.c;
        }
        pvt->datalen = 0;
    }
 
    return ast_frisolate(f);
}

References ast_frisolate, ast_trans_pvt::c, ast_frame::data, ast_frame::datalen, ast_trans_pvt::datalen, ast_trans_pvt::f, NULL, ast_trans_pvt::outbuf, ast_frame::ptr, ast_frame::samples, and ast_trans_pvt::samples.

Referenced by default_frameout(), lintoadpcm_frameout(), lintocodec2_frameout(), lintogsm_frameout(), lintoilbc_frameout(), lintolpc10_frameout(), and lintospeex_frameout().

ast_translate()

struct ast_frame * ast_translate	(	struct ast_trans_pvt *	path,
		struct ast_frame *	f,
		int	consume
	)

translates one or more frames Apply an input frame into the translator and receive zero or one output frames. Consume determines whether the original frame should be freed. In case the frame type is AST_FRAME_RTCP, the frame is not translated but passed to the translator codecs via the feedback callback, and a pointer to ast_null_frame is returned after that.

Parameters

path	tr translator structure to use for translation
f	frame to translate
consume	Whether or not to free the original frame

Returns

an ast_frame of the new translation format on success

Return values

NULL	on failure

translates one or more frames Apply an input frame into the translator and receive zero or one output frames. Consume determines whether the original frame should be freed. In case the frame type is AST_FRAME_RTCP, the frame is not translated but passed to the translator codecs via the feedback callback, and a pointer to ast_null_frame is returned after that.

Definition at line 566 of file translate.c.

{
    struct ast_trans_pvt *p = path;
    struct ast_frame *out;
    struct timeval delivery;
    int has_timing_info;
    long ts;
    long len;
    int seqno;
 
    if (f->frametype == AST_FRAME_RTCP) {
        /* Just pass the feedback to the right callback, if it exists.
         * This "translation" does nothing so return a null frame. */
        struct ast_trans_pvt *tp;
        for (tp = p; tp; tp = tp->next) {
            if (tp->t->feedback)
                tp->t->feedback(tp, f);
        }
        return &ast_null_frame;
    }
 
    has_timing_info = ast_test_flag(f, AST_FRFLAG_HAS_TIMING_INFO);
    ts = f->ts;
    len = f->len;
    seqno = f->seqno;
 
    if (!ast_tvzero(f->delivery)) {
        if (!ast_tvzero(path->nextin)) {
            /* Make sure this is in line with what we were expecting */
            if (!ast_tveq(path->nextin, f->delivery)) {
                /* The time has changed between what we expected and this
                   most recent time on the new packet.  If we have a
                   valid prediction adjust our output time appropriately */
                if (!ast_tvzero(path->nextout)) {
                    path->nextout = ast_tvadd(path->nextout,
                                  ast_tvsub(f->delivery, path->nextin));
                }
                path->nextin = f->delivery;
            }
        } else {
            /* This is our first pass.  Make sure the timing looks good */
            path->nextin = f->delivery;
            path->nextout = f->delivery;
        }
        /* Predict next incoming sample */
        path->nextin = ast_tvadd(path->nextin, ast_samp2tv(
             f->samples, ast_format_get_sample_rate(f->subclass.format)));
    }
    delivery = f->delivery;
    for (out = f; out && p ; p = p->next) {
        struct ast_frame *current = out;
 
        do {
            framein(p, current);
            current = AST_LIST_NEXT(current, frame_list);
        } while (current);
        if (out != f) {
            ast_frfree(out);
        }
        out = p->t->frameout(p);
    }
 
    if (!out) {
        out = generate_interpolated_slin(path, f);
    }
 
    if (out) {
        /* we have a frame, play with times */
        if (!ast_tvzero(delivery)) {
            struct ast_frame *current = out;
 
            do {
                /* Regenerate prediction after a discontinuity */
                if (ast_tvzero(path->nextout)) {
                    path->nextout = ast_tvnow();
                }
 
                /* Use next predicted outgoing timestamp */
                current->delivery = path->nextout;
 
                /* Invalidate prediction if we're entering a silence period */
                if (current->frametype == AST_FRAME_CNG) {
                    path->nextout = ast_tv(0, 0);
                /* Predict next outgoing timestamp from samples in this
                   frame. */
                } else {
                    path->nextout = ast_tvadd(path->nextout, ast_samp2tv(
                        current->samples, ast_format_get_sample_rate(current->subclass.format)));
                }
 
                if (f->samples != current->samples && ast_test_flag(current, AST_FRFLAG_HAS_TIMING_INFO)) {
                    ast_debug(4, "Sample size different %d vs %d\n", f->samples, current->samples);
                    ast_clear_flag(current, AST_FRFLAG_HAS_TIMING_INFO);
                }
                current = AST_LIST_NEXT(current, frame_list);
            } while (current);
        } else {
            out->delivery = ast_tv(0, 0);
            ast_set2_flag(out, has_timing_info, AST_FRFLAG_HAS_TIMING_INFO);
            if (has_timing_info) {
                out->ts = ts;
                out->len = len;
                out->seqno = seqno;
            }
            /* Invalidate prediction if we're entering a silence period */
            if (out->frametype == AST_FRAME_CNG) {
                path->nextout = ast_tv(0, 0);
            }
        }
    }
    if (consume) {
        ast_frfree(f);
    }
    return out;
}

References ast_clear_flag, ast_debug, ast_format_get_sample_rate(), AST_FRAME_CNG, AST_FRAME_RTCP, AST_FRFLAG_HAS_TIMING_INFO, ast_frfree, AST_LIST_NEXT, ast_null_frame, ast_samp2tv(), ast_set2_flag, ast_test_flag, ast_tv(), ast_tvadd(), ast_tveq(), ast_tvnow(), ast_tvsub(), ast_tvzero(), current, ast_frame::delivery, ast_trans_pvt::f, ast_translator::feedback, ast_frame_subclass::format, framein(), ast_translator::frameout, ast_frame::frametype, generate_interpolated_slin(), len(), ast_frame::len, ast_trans_pvt::next, ast_trans_pvt::nextin, ast_trans_pvt::nextout, out, ast_frame::samples, ast_frame::seqno, ast_frame::subclass, ast_trans_pvt::t, and ast_frame::ts.

Referenced by __ast_read(), ast_slinfactory_feed(), ast_write_stream(), ast_writestream(), audiohook_list_translate_to_native(), audiohook_list_translate_to_slin(), audiohook_read_frame_helper(), conf_run(), fax_gateway_framehook(), and softmix_process_write_audio().

ast_translate_available_formats()

void ast_translate_available_formats	(	struct ast_format_cap *	dest,
		struct ast_format_cap *	src,
		struct ast_format_cap *	result
	)

Find available formats.

Parameters

	dest	possible destination formats
	src	source formats
[out]	result	capabilities structure to store available formats in returns the destination formats that are available in the source or translatable

The result will include all formats from 'dest' that are either present in 'src' or translatable from a format present in 'src'.

Note

Only a single audio format and a single video format can be present in 'src', or the function will produce unexpected results.

Definition at line 1616 of file translate.c.

{
    struct ast_format *cur_dest, *cur_src;
    int index;
 
    for (index = 0; index < ast_format_cap_count(dest); ++index) {
        if (!(cur_dest = ast_format_cap_get_format(dest, index))) {
            continue;
        }
 
        /* We give preference to a joint format structure if possible */
        if ((cur_src = ast_format_cap_get_compatible_format(src, cur_dest))) {
            ast_format_cap_append(result, cur_src, 0);
            ao2_ref(cur_src, -1);
        } else {
            /* Otherwise we just use the destination format */
            ast_format_cap_append(result, cur_dest, 0);
        }
        ao2_ref(cur_dest, -1);
    }
 
    /* if we don't have a source format, we just have to try all
       possible destination formats */
    if (!src) {
        return;
    }
 
    for (index = 0; index < ast_format_cap_count(src); ++index) {
        if (!(cur_src = ast_format_cap_get_format(src, index))) {
            continue;
        }
 
        AST_RWLIST_RDLOCK(&translators);
        check_translation_path(dest, src, result,
                       cur_src, AST_MEDIA_TYPE_AUDIO);
        check_translation_path(dest, src, result,
                       cur_src, AST_MEDIA_TYPE_VIDEO);
        AST_RWLIST_UNLOCK(&translators);
        ao2_ref(cur_src, -1);
    }
}

References ao2_ref, ast_format_cap_append, ast_format_cap_count(), ast_format_cap_get_compatible_format(), ast_format_cap_get_format(), AST_MEDIA_TYPE_AUDIO, AST_MEDIA_TYPE_VIDEO, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, check_translation_path(), and result.

Referenced by ast_rtp_instance_available_formats().

ast_translate_init()

int ast_translate_init

(

void

)

Initialize the translation matrix and index to format conversion table.

Return values

0	on success
-1	on failure

Definition at line 1675 of file translate.c.

{
    int res = 0;
    ast_rwlock_init(&tablelock);
    res = matrix_resize(1);
    res |= ast_cli_register_multiple(cli_translate, ARRAY_LEN(cli_translate));
    ast_register_cleanup(translate_shutdown);
    return res;
}

References ARRAY_LEN, ast_cli_register_multiple, ast_register_cleanup(), ast_rwlock_init, cli_translate, matrix_resize(), tablelock, and translate_shutdown().

Referenced by asterisk_daemon().

ast_translate_path_steps()

unsigned int ast_translate_path_steps	(	struct ast_format *	dest,
		struct ast_format *	src
	)

Returns the number of steps required to convert from 'src' to 'dest'.

Parameters

dest	destination format
src	source format

Returns

the number of translation steps required

Return values

-1	if no path is available

Definition at line 1536 of file translate.c.

{
    unsigned int res = -1;
    /* convert bitwise format numbers into array indices */
    int src = format2index(src_format);
    int dest = format2index(dst_format);
 
    if (src < 0 || dest < 0) {
        ast_log(LOG_WARNING, "No translator path: (%s codec is not valid)\n", src < 0 ? "starting" : "ending");
        return -1;
    }
    AST_RWLIST_RDLOCK(&translators);
 
    if (matrix_get(src, dest)->step) {
        res = matrix_get(src, dest)->multistep + 1;
    }
 
    AST_RWLIST_UNLOCK(&translators);
 
    return res;
}

References ast_log, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, format2index(), LOG_WARNING, matrix_get(), and translator_path::multistep.

Referenced by ast_channel_make_compatible_helper().

ast_translate_path_to_str()

const char * ast_translate_path_to_str	(	struct ast_trans_pvt *	t,
		struct ast_str **	str
	)

Puts a string representation of the translation path into outbuf.

Parameters

t	translator structure containing the translation path
str	ast_str output buffer

Returns

on success pointer to beginning of outbuf

Return values

""	on failure

Definition at line 930 of file translate.c.

{
    if (!p || !p->t) {
        return "";
    }
 
    ast_str_reset(*str);
    codec_append_name(&p->t->src_codec, str);
    while (p) {
        ast_str_append(str, 0, "->");
        codec_append_name(&p->t->dst_codec, str);
        p = p->next;
    }
 
    return ast_str_buffer(*str);
}

References ast_str_append(), ast_str_buffer(), ast_str_reset(), codec_append_name(), ast_translator::dst_codec, ast_trans_pvt::next, ast_translator::src_codec, str, and ast_trans_pvt::t.

Referenced by chan_pjsip_write_stream(), generate_status(), handle_showchan(), and serialize_showchan().

ast_translator_activate()

void ast_translator_activate

(

struct ast_translator *

t

)

Activate a previously deactivated translator.

Parameters

t	translator to activate

Enables the specified translator for use.

Definition at line 1378 of file translate.c.

{
    AST_RWLIST_WRLOCK(&translators);
    t->active = 1;
    matrix_rebuild(0);
    AST_RWLIST_UNLOCK(&translators);
}

References ast_translator::active, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, and matrix_rebuild().

ast_translator_best_choice()

int ast_translator_best_choice	(	struct ast_format_cap *	dst_cap,
		struct ast_format_cap *	src_cap,
		struct ast_format **	dst_fmt_out,
		struct ast_format **	src_fmt_out
	)

Chooses the best translation path.

Given a list of sources, and a designed destination format, which should I choose?

Parameters

dst_cap	destination capabilities
src_cap	source capabilities
dst_fmt_out	destination format chosen out of destination capabilities
src_fmt_out	source format chosen out of source capabilities

Return values

0	on success
-1	if no path could be found.

Note

dst_cap and src_cap are not mondified.

Chooses the best translation path.

Definition at line 1402 of file translate.c.

{
    unsigned int besttablecost = INT_MAX;
    unsigned int beststeps = INT_MAX;
    struct ast_format *fmt;
    struct ast_format *dst;
    struct ast_format *src;
    RAII_VAR(struct ast_format *, best, NULL, ao2_cleanup);
    RAII_VAR(struct ast_format *, bestdst, NULL, ao2_cleanup);
    struct ast_format_cap *joint_cap;
    int i;
    int j;
 
    if (ast_format_cap_empty(dst_cap) || ast_format_cap_empty(src_cap)) {
        ast_log(LOG_ERROR, "Cannot determine best translation path since one capability supports no formats\n");
        return -1;
    }
 
    joint_cap = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
    if (!joint_cap) {
        return -1;
    }
    ast_format_cap_get_compatible(dst_cap, src_cap, joint_cap);
 
    for (i = 0; i < ast_format_cap_count(joint_cap); ++i, ao2_cleanup(fmt)) {
        fmt = ast_format_cap_get_format(joint_cap, i);
        if (!fmt
            || ast_format_get_type(fmt) != AST_MEDIA_TYPE_AUDIO) {
            continue;
        }
 
        if (!best
            || ast_format_get_sample_rate(best) < ast_format_get_sample_rate(fmt)) {
            ao2_replace(best, fmt);
        }
    }
    ao2_ref(joint_cap, -1);
 
    if (best) {
        ao2_replace(*dst_fmt_out, best);
        ao2_replace(*src_fmt_out, best);
        return 0;
    }
 
    /* need to translate */
    AST_RWLIST_RDLOCK(&translators);
    for (i = 0; i < ast_format_cap_count(dst_cap); ++i, ao2_cleanup(dst)) {
        dst = ast_format_cap_get_format(dst_cap, i);
        if (!dst
            || ast_format_get_type(dst) != AST_MEDIA_TYPE_AUDIO) {
            continue;
        }
 
        for (j = 0; j < ast_format_cap_count(src_cap); ++j, ao2_cleanup(src)) {
            int x;
            int y;
 
            src = ast_format_cap_get_format(src_cap, j);
            if (!src
                || ast_format_get_type(src) != AST_MEDIA_TYPE_AUDIO) {
                continue;
            }
 
            x = format2index(src);
            y = format2index(dst);
            if (x < 0 || y < 0) {
                continue;
            }
            if (!matrix_get(x, y) || !(matrix_get(x, y)->step)) {
                continue;
            }
            if (matrix_get(x, y)->table_cost < besttablecost
                || matrix_get(x, y)->multistep < beststeps) {
                /* better than what we have so far */
                ao2_replace(best, src);
                ao2_replace(bestdst, dst);
                besttablecost = matrix_get(x, y)->table_cost;
                beststeps = matrix_get(x, y)->multistep;
            } else if (matrix_get(x, y)->table_cost == besttablecost
                    && matrix_get(x, y)->multistep == beststeps) {
                int replace = 0;
                unsigned int gap_selected = format_sample_rate_absdiff(best, bestdst);
                unsigned int gap_current = format_sample_rate_absdiff(src, dst);
 
                if (gap_current < gap_selected) {
                    /* better than what we have so far */
                    replace = 1;
                } else if (gap_current == gap_selected) {
                    int src_quality, best_quality;
                    struct ast_codec *src_codec, *best_codec;
 
                    src_codec = ast_format_get_codec(src);
                    best_codec = ast_format_get_codec(best);
                    src_quality = src_codec->quality;
                    best_quality = best_codec->quality;
 
                    ao2_cleanup(src_codec);
                    ao2_cleanup(best_codec);
 
                    /* We have a tie, so choose the format with the higher quality, if they differ. */
                    if (src_quality > best_quality) {
                        /* Better than what we had before. */
                        replace = 1;
                        ast_debug(2, "Tiebreaker: preferring format %s (%d) to %s (%d)\n", ast_format_get_name(src), src_quality,
                            ast_format_get_name(best), best_quality);
                    } else {
                        /* This isn't necessarily indicative of a problem, but in reality this shouldn't really happen, unless
                         * there are 2 formats that are basically the same. */
                        ast_debug(1, "Completely ambiguous tie between formats %s and %s (quality %d): sticking with %s, but this is arbitrary\n",
                            ast_format_get_name(src), ast_format_get_name(best), best_quality, ast_format_get_name(best));
                    }
                }
                if (replace) {
                    ao2_replace(best, src);
                    ao2_replace(bestdst, dst);
                    besttablecost = matrix_get(x, y)->table_cost;
                    beststeps = matrix_get(x, y)->multistep;
                }
            }
        }
    }
    AST_RWLIST_UNLOCK(&translators);
 
    if (!best) {
        return -1;
    }
    ao2_replace(*dst_fmt_out, bestdst);
    ao2_replace(*src_fmt_out, best);
    return 0;
}

References ao2_cleanup, ao2_ref, ao2_replace, ast_debug, ast_format_cap_alloc, ast_format_cap_count(), ast_format_cap_empty(), AST_FORMAT_CAP_FLAG_DEFAULT, ast_format_cap_get_compatible(), ast_format_cap_get_format(), ast_format_get_codec(), ast_format_get_name(), ast_format_get_sample_rate(), ast_format_get_type(), ast_log, AST_MEDIA_TYPE_AUDIO, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, format2index(), format_sample_rate_absdiff, LOG_ERROR, matrix_get(), translator_path::multistep, NULL, ast_codec::quality, RAII_VAR, replace(), and translator_path::table_cost.

Referenced by ast_channel_make_compatible_helper(), ast_speech_new(), iax2_request(), local_request_with_stream_topology(), request_channel(), and set_format().

ast_translator_build_path()

struct ast_trans_pvt * ast_translator_build_path	(	struct ast_format *	dst,
		struct ast_format *	src
	)

Builds a translator path Build a path (possibly NULL) from source to dest.

Parameters

dst	dest destination format
src	source source format

Returns

ast_trans_pvt on success

Return values

NULL	on failure

Builds a translator path Build a path (possibly NULL) from source to dest.

Definition at line 486 of file translate.c.

{
    struct ast_trans_pvt *head = NULL, *tail = NULL;
    int src_index, dst_index;
 
    src_index = format2index(src);
    dst_index = format2index(dst);
 
    if (src_index < 0 || dst_index < 0) {
        ast_log(LOG_WARNING, "No translator path: (%s codec is not valid)\n", src_index < 0 ? "starting" : "ending");
        return NULL;
    }
 
    AST_RWLIST_RDLOCK(&translators);
 
    while (src_index != dst_index) {
        struct ast_trans_pvt *cur;
        struct ast_format *explicit_dst = NULL;
        struct ast_translator *t = matrix_get(src_index, dst_index)->step;
        if (!t) {
            ast_log(LOG_WARNING, "No translator path from %s to %s\n",
                ast_format_get_name(src), ast_format_get_name(dst));
            AST_RWLIST_UNLOCK(&translators);
            ast_translator_free_path(head);
            return NULL;
        }
        if ((t->dst_codec.sample_rate == ast_format_get_sample_rate(dst)) && (t->dst_codec.type == ast_format_get_type(dst))) {
            explicit_dst = dst;
        }
        if (!(cur = newpvt(t, explicit_dst))) {
            ast_log(LOG_WARNING, "Failed to build translator step from %s to %s\n",
                ast_format_get_name(src), ast_format_get_name(dst));
            ast_translator_free_path(head);
            AST_RWLIST_UNLOCK(&translators);
            return NULL;
        }
        if (!head) {
            head = cur;
        } else {
            tail->next = cur;
        }
        tail = cur;
        cur->nextin = cur->nextout = ast_tv(0, 0);
        /* Keep going if this isn't the final destination */
        src_index = cur->t->dst_fmt_index;
    }
 
    AST_RWLIST_UNLOCK(&translators);
    return head;
}

References ast_format_get_name(), ast_format_get_sample_rate(), ast_format_get_type(), ast_log, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_translator_free_path(), ast_tv(), ast_translator::dst_codec, ast_translator::dst_fmt_index, format2index(), LOG_WARNING, matrix_get(), newpvt(), ast_trans_pvt::next, ast_trans_pvt::nextin, ast_trans_pvt::nextout, NULL, ast_codec::sample_rate, translator_path::step, ast_trans_pvt::t, and ast_codec::type.

Referenced by ast_set_read_format_path(), ast_set_write_format_path(), ast_slinfactory_feed(), ast_writestream(), audiohook_list_translate_to_native(), audiohook_list_translate_to_slin(), audiohook_read_frame_helper(), conf_run(), set_format(), softmix_process_write_audio(), and softmix_translate_helper_change_rate().

ast_translator_deactivate()

void ast_translator_deactivate

(

struct ast_translator *

t

)

Deactivate a translator.

Parameters

t	translator to deactivate

Disables the specified translator from being used.

Definition at line 1386 of file translate.c.

{
    AST_RWLIST_WRLOCK(&translators);
    t->active = 0;
    matrix_rebuild(0);
    AST_RWLIST_UNLOCK(&translators);
}

References ast_translator::active, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, and matrix_rebuild().

ast_translator_free_path()

void ast_translator_free_path

(

struct ast_trans_pvt *

tr

)

Frees a translator path Frees the given translator path structure.

Parameters

tr	translator path to get rid of

Definition at line 476 of file translate.c.

{
    struct ast_trans_pvt *pn = p;
    while ( (p = pn) ) {
        pn = p->next;
        destroy(p);
    }
}

References destroy(), and ast_trans_pvt::next.

Referenced by ast_audiohook_destroy(), ast_audiohook_detach_list(), ast_channel_destructor(), ast_set_read_format_path(), ast_set_write_format_path(), ast_slinfactory_destroy(), ast_slinfactory_feed(), ast_slinfactory_flush(), ast_translator_build_path(), ast_writestream(), audiohook_list_translate_to_native(), audiohook_list_translate_to_slin(), audiohook_read_frame_helper(), conf_free(), filestream_destructor(), free_translation(), set_format(), softmix_translate_helper_change_rate(), softmix_translate_helper_cleanup(), and softmix_translate_helper_free_entry().

ast_unregister_translator()

int ast_unregister_translator

(

struct ast_translator *

t

)

Unregister a translator Unregisters the given translator.

Parameters

t	translator to unregister

Return values

0	on success
-1	on failure

Unregister a translator Unregisters the given translator.

Definition at line 1350 of file translate.c.

{
    char tmp[80];
    struct ast_translator *u;
    int found = 0;
 
    AST_RWLIST_WRLOCK(&translators);
    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&translators, u, list) {
        if (u == t) {
            AST_RWLIST_REMOVE_CURRENT(list);
            ast_verb(5, "Unregistered translator '%s' from codec %s to %s\n",
                term_color(tmp, t->name, COLOR_MAGENTA, COLOR_BLACK, sizeof(tmp)),
                t->src_codec.name, t->dst_codec.name);
            found = 1;
            break;
        }
    }
    AST_RWLIST_TRAVERSE_SAFE_END;
 
    if (found && !ast_shutting_down()) {
        matrix_rebuild(0);
    }
 
    AST_RWLIST_UNLOCK(&translators);
 
    return (u ? 0 : -1);
}

References AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_shutting_down(), ast_verb, COLOR_BLACK, COLOR_MAGENTA, ast_translator::dst_codec, ast_translator::list, matrix_rebuild(), ast_codec::name, ast_translator::name, ast_translator::src_codec, term_color(), and tmp().

Referenced by unload_module(), and unregister_translators().