Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Macros | Enumerations | Functions
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"

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()
 

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_frameast_trans_frameout (struct ast_trans_pvt *pvt, int datalen, int samples)
 generic frameout function More...
 
struct ast_frameast_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_pvtast_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.

Enumeration Type Documentation

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.

61  {
62 
63  /* Lossless Source Translation Costs */
64 
65  /*! [lossless -> lossless] original sampling */
67  /*! [lossless -> lossy] original sampling */
69 
70  /*! [lossless -> lossless] up sample */
72  /*! [lossless -> lossy] up sample */
74 
75  /*! [lossless -> lossless] down sample */
77  /*! [lossless -> lossy] down sample */
79 
80  /*! [lossless -> unknown] unknown.
81  * This value is for a lossless source translation
82  * with an unknown destination and or sample rate conversion. */
84 
85  /* Lossy Source Translation Costs */
86 
87  /*! [lossy -> lossless] original sampling */
89  /*! [lossy -> lossy] original sampling */
91 
92  /*! [lossy -> lossless] up sample */
94  /*! [lossy -> lossy] up sample */
96 
97  /*! [lossy -> lossless] down sample */
99  /*! [lossy -> lossy] down sample */
101 
102  /*! [lossy -> unknown] unknown.
103  * This value is for a lossy source translation
104  * with an unknown destination and or sample rate conversion. */
105  AST_TRANS_COST_LY_UNKNOWN = 985000,
106 
107 };

Function Documentation

int __ast_register_translator ( struct ast_translator t,
struct ast_module mod 
)

Register a translator This registers a codec translator with asterisk.

Parameters
tpopulated ast_translator structure
modmodule handle to the module that owns this translator
Return values
0on success
-1on failure

Register a translator This registers a codec translator with asterisk.

Definition at line 1237 of file translate.c.

References ast_translator::active, ast_codec_get(), AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_translator::buf_size, ast_translator::comp_cost, ast_translator::dst_codec, ast_translator::dst_fmt_index, ast_translator::frameout, matrix_rebuild(), ast_translator::module, ast_codec::name, ast_translator::name, RAII_VAR, ast_codec::sample_rate, ast_translator::src_codec, ast_translator::src_fmt_index, ast_translator::table_cost, term_color(), and ast_codec::type.

1238 {
1239  struct ast_translator *u;
1240  char tmp[80];
1241  RAII_VAR(struct ast_codec *, src_codec, NULL, ao2_cleanup);
1242  RAII_VAR(struct ast_codec *, dst_codec, NULL, ao2_cleanup);
1243 
1245  if (!src_codec) {
1246  ast_assert(0);
1247  ast_log(LOG_WARNING, "Failed to register translator: unknown source codec %s\n", t->src_codec.name);
1248  return -1;
1249  }
1250 
1252  if (!dst_codec) {
1253  ast_log(LOG_WARNING, "Failed to register translator: unknown destination codec %s\n", t->dst_codec.name);
1254  return -1;
1255  }
1256 
1257  if (add_codec2index(src_codec) || add_codec2index(dst_codec)) {
1258  if (matrix_resize(0)) {
1259  ast_log(LOG_WARNING, "Translator matrix can not represent any more translators. Out of resources.\n");
1260  return -1;
1261  }
1262  add_codec2index(src_codec);
1263  add_codec2index(dst_codec);
1264  }
1265 
1266  if (!mod) {
1267  ast_log(LOG_WARNING, "Missing module pointer, you need to supply one\n");
1268  return -1;
1269  }
1270 
1271  if (!t->buf_size) {
1272  ast_log(LOG_WARNING, "empty buf size, you need to supply one\n");
1273  return -1;
1274  }
1275  if (!t->table_cost && !(t->table_cost = generate_table_cost(src_codec, dst_codec))) {
1276  ast_log(LOG_WARNING, "Table cost could not be generated for %s, "
1277  "Please set table_cost variable on translator.\n", t->name);
1278  return -1;
1279  }
1280 
1281  t->module = mod;
1282  t->src_fmt_index = codec2index(src_codec);
1283  t->dst_fmt_index = codec2index(dst_codec);
1284  t->active = 1;
1285 
1286  if (t->src_fmt_index < 0 || t->dst_fmt_index < 0) {
1287  ast_log(LOG_WARNING, "Invalid translator path: (%s codec is not valid)\n", t->src_fmt_index < 0 ? "starting" : "ending");
1288  return -1;
1289  }
1290  if (t->src_fmt_index >= cur_max_index) {
1291  ast_log(LOG_WARNING, "Source codec %s is larger than cur_max_index\n", t->src_codec.name);
1292  return -1;
1293  }
1294 
1295  if (t->dst_fmt_index >= cur_max_index) {
1296  ast_log(LOG_WARNING, "Destination codec %s is larger than cur_max_index\n", t->dst_codec.name);
1297  return -1;
1298  }
1299 
1300  if (t->buf_size) {
1301  /*
1302  * Align buf_size properly, rounding up to the machine-specific
1303  * alignment for pointers.
1304  */
1305  struct _test_align { void *a, *b; } p;
1306  int align = (char *)&p.b - (char *)&p.a;
1307 
1308  t->buf_size = ((t->buf_size + align - 1) / align) * align;
1309  }
1310 
1311  if (t->frameout == NULL) {
1312  t->frameout = default_frameout;
1313  }
1314 
1315  generate_computational_cost(t, 1);
1316 
1317  ast_verb(5, "Registered translator '%s' from codec %s to %s, table cost, %d, computational cost %d\n",
1318  term_color(tmp, t->name, COLOR_MAGENTA, COLOR_BLACK, sizeof(tmp)),
1319  t->src_codec.name, t->dst_codec.name, t->table_cost, t->comp_cost);
1320 
1322 
1323  /* find any existing translators that provide this same srcfmt/dstfmt,
1324  and put this one in order based on computational cost */
1325  AST_RWLIST_TRAVERSE_SAFE_BEGIN(&translators, u, list) {
1326  if ((u->src_fmt_index == t->src_fmt_index) &&
1327  (u->dst_fmt_index == t->dst_fmt_index) &&
1328  (u->comp_cost > t->comp_cost)) {
1329  AST_RWLIST_INSERT_BEFORE_CURRENT(t, list);
1330  t = NULL;
1331  break;
1332  }
1333  }
1334  AST_RWLIST_TRAVERSE_SAFE_END;
1335 
1336  /* if no existing translator was found for this codec combination,
1337  add it to the beginning of the list */
1338  if (t) {
1339  AST_RWLIST_INSERT_HEAD(&translators, t, list);
1340  }
1341 
1342  matrix_rebuild(0);
1343 
1345 
1346  return 0;
1347 }
const char * name
Name for this codec.
Definition: codec.h:46
static void matrix_rebuild(int samples)
rebuild a translation matrix.
Definition: translate.c:825
Descriptor of a translator.
Definition: translate.h:137
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
struct ast_codec * ast_codec_get(const char *name, enum ast_media_type type, unsigned int sample_rate)
Retrieve a codec given a name, type, and sample rate.
Definition: codec.c:327
struct ast_module * module
Definition: translate.h:187
int buf_size
size of outbuf, in bytes. Mandatory. The wrapper code will also allocate an AST_FRIENDLY_OFFSET space...
Definition: translate.h:182
char * term_color(char *outbuf, const char *inbuf, int fgcolor, int bgcolor, int maxout)
Colorize a specified string by adding terminal color codes.
Definition: term.c:235
the list of translators
Definition: codec_dahdi.c:281
struct ast_codec dst_codec
Definition: translate.h:140
struct ast_codec src_codec
Definition: translate.h:139
unsigned int sample_rate
Sample rate (number of samples carried in a second)
Definition: codec.h:52
struct ast_frame *(* frameout)(struct ast_trans_pvt *pvt)
Definition: translate.h:158
enum ast_media_type type
Type of media this codec contains.
Definition: codec.h:50
static int cur_max_index
Definition: translate.c:95
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
Represents a media codec within Asterisk.
Definition: codec.h:42
char name[80]
Definition: translate.h:138
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.

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

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

441 {
442  struct ast_frame *f = &pvt->f;
443 
444  if (samples) {
445  f->samples = samples;
446  } else {
447  if (pvt->samples == 0) {
448  return NULL;
449  }
450  f->samples = pvt->samples;
451  pvt->samples = 0;
452  }
453  if (datalen) {
454  f->datalen = datalen;
455  f->data.ptr = pvt->outbuf.c;
456  } else {
457  f->datalen = pvt->datalen;
458  if (!f->datalen) {
459  f->data.ptr = NULL;
460  } else {
461  f->data.ptr = pvt->outbuf.c;
462  }
463  pvt->datalen = 0;
464  }
465 
466  return ast_frisolate(f);
467 }
int datalen
actual space used in outbuf
Definition: translate.h:218
struct ast_frame f
Definition: translate.h:215
union ast_frame::@224 data
#define ast_frisolate(fr)
Makes a frame independent of any static storage.
Data structure associated with a single frame of data.
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
pathtr translator structure to use for translation
fframe to translate
consumeWhether or not to free the original frame
Returns
an ast_frame of the new translation format on success
Return values
NULLon 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.

References ast_debug, ast_format_get_sample_rate(), AST_FRAME_CNG, AST_FRAME_RTCP, AST_FRFLAG_HAS_TIMING_INFO, AST_LIST_NEXT, ast_null_frame, ast_samp2tv(), ast_tv(), ast_tvadd(), ast_tveq(), ast_tvnow(), ast_tvsub(), ast_tvzero(), ast_frame::delivery, ast_translator::feedback, ast_frame_subclass::format, framein(), ast_frame::frametype, ast_frame::len, ast_trans_pvt::next, ast_frame::samples, ast_frame::seqno, ast_frame::subclass, and ast_frame::ts.

Referenced by __ast_read(), ast_slinfactory_feed(), ast_write_stream(), ast_writestream(), and fax_gateway_framehook().

567 {
568  struct ast_trans_pvt *p = path;
569  struct ast_frame *out;
570  struct timeval delivery;
571  int has_timing_info;
572  long ts;
573  long len;
574  int seqno;
575 
576  if (f->frametype == AST_FRAME_RTCP) {
577  /* Just pass the feedback to the right callback, if it exists.
578  * This "translation" does nothing so return a null frame. */
579  struct ast_trans_pvt *tp;
580  for (tp = p; tp; tp = tp->next) {
581  if (tp->t->feedback)
582  tp->t->feedback(tp, f);
583  }
584  return &ast_null_frame;
585  }
586 
587  has_timing_info = ast_test_flag(f, AST_FRFLAG_HAS_TIMING_INFO);
588  ts = f->ts;
589  len = f->len;
590  seqno = f->seqno;
591 
592  if (!ast_tvzero(f->delivery)) {
593  if (!ast_tvzero(path->nextin)) {
594  /* Make sure this is in line with what we were expecting */
595  if (!ast_tveq(path->nextin, f->delivery)) {
596  /* The time has changed between what we expected and this
597  most recent time on the new packet. If we have a
598  valid prediction adjust our output time appropriately */
599  if (!ast_tvzero(path->nextout)) {
600  path->nextout = ast_tvadd(path->nextout,
601  ast_tvsub(f->delivery, path->nextin));
602  }
603  path->nextin = f->delivery;
604  }
605  } else {
606  /* This is our first pass. Make sure the timing looks good */
607  path->nextin = f->delivery;
608  path->nextout = f->delivery;
609  }
610  /* Predict next incoming sample */
611  path->nextin = ast_tvadd(path->nextin, ast_samp2tv(
613  }
614  delivery = f->delivery;
615  for (out = f; out && p ; p = p->next) {
616  struct ast_frame *current = out;
617 
618  do {
619  framein(p, current);
620  current = AST_LIST_NEXT(current, frame_list);
621  } while (current);
622  if (out != f) {
623  ast_frfree(out);
624  }
625  out = p->t->frameout(p);
626  }
627 
628  if (!out) {
629  out = generate_interpolated_slin(path, f);
630  }
631 
632  if (out) {
633  /* we have a frame, play with times */
634  if (!ast_tvzero(delivery)) {
635  struct ast_frame *current = out;
636 
637  do {
638  /* Regenerate prediction after a discontinuity */
639  if (ast_tvzero(path->nextout)) {
640  path->nextout = ast_tvnow();
641  }
642 
643  /* Use next predicted outgoing timestamp */
644  current->delivery = path->nextout;
645 
646  /* Invalidate prediction if we're entering a silence period */
647  if (current->frametype == AST_FRAME_CNG) {
648  path->nextout = ast_tv(0, 0);
649  /* Predict next outgoing timestamp from samples in this
650  frame. */
651  } else {
652  path->nextout = ast_tvadd(path->nextout, ast_samp2tv(
653  current->samples, ast_format_get_sample_rate(current->subclass.format)));
654  }
655 
656  if (f->samples != current->samples && ast_test_flag(current, AST_FRFLAG_HAS_TIMING_INFO)) {
657  ast_debug(4, "Sample size different %d vs %d\n", f->samples, current->samples);
658  ast_clear_flag(current, AST_FRFLAG_HAS_TIMING_INFO);
659  }
660  current = AST_LIST_NEXT(current, frame_list);
661  } while (current);
662  } else {
663  out->delivery = ast_tv(0, 0);
664  ast_set2_flag(out, has_timing_info, AST_FRFLAG_HAS_TIMING_INFO);
665  if (has_timing_info) {
666  out->ts = ts;
667  out->len = len;
668  out->seqno = seqno;
669  }
670  /* Invalidate prediction if we're entering a silence period */
671  if (out->frametype == AST_FRAME_CNG) {
672  path->nextout = ast_tv(0, 0);
673  }
674  }
675  }
676  if (consume) {
677  ast_frfree(f);
678  }
679  return out;
680 }
int ast_tveq(struct timeval _a, struct timeval _b)
Returns true if the two struct timeval arguments are equal.
Definition: time.h:147
int ast_tvzero(const struct timeval t)
Returns true if the argument is 0,0.
Definition: time.h:117
#define AST_LIST_NEXT(elm, field)
Returns the next entry in the list after the given entry.
Definition: linkedlists.h:439
struct timeval ast_tvnow(void)
Returns current timeval. Meant to replace calls to gettimeofday().
Definition: time.h:159
struct ast_trans_pvt * next
Definition: translate.h:227
struct ast_frame_subclass subclass
static int framein(struct ast_trans_pvt *pvt, struct ast_frame *f)
framein wrapper, deals with bound checks.
Definition: translate.c:397
struct timeval ast_samp2tv(unsigned int _nsamp, unsigned int _rate)
Returns a timeval corresponding to the duration of n samples at rate r. Useful to convert samples to ...
Definition: time.h:282
#define ast_debug(level,...)
Log a DEBUG message.
void(* feedback)(struct ast_trans_pvt *pvt, struct ast_frame *feedback)
Definition: translate.h:162
Default structure for translators, with the basic fields and buffers, all allocated as part of the sa...
Definition: translate.h:213
struct timeval ast_tvadd(struct timeval a, struct timeval b)
Returns the sum of two timevals a + b.
Definition: extconf.c:2282
struct timeval delivery
struct ast_frame ast_null_frame
Definition: main/frame.c:79
struct timeval ast_tv(ast_time_t sec, ast_suseconds_t usec)
Returns a timeval from sec, usec.
Definition: time.h:235
unsigned int ast_format_get_sample_rate(const struct ast_format *format)
Get the sample rate of a media format.
Definition: format.c:379
Data structure associated with a single frame of data.
struct timeval ast_tvsub(struct timeval a, struct timeval b)
Returns the difference of two timevals a - b.
Definition: extconf.c:2297
enum ast_frame_type frametype
struct ast_format * format
void ast_translate_available_formats ( struct ast_format_cap dest,
struct ast_format_cap src,
struct ast_format_cap result 
)

Find available formats.

Parameters
destpossible destination formats
srcsource formats
[out]resultcapabilities 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.

References ao2_ref, ast_format_cap_append, ast_format_cap_count(), ast_format_cap_get_compatible_format(), ast_format_cap_get_format(), AST_RWLIST_RDLOCK, and AST_RWLIST_UNLOCK.

Referenced by ast_rtp_instance_available_formats().

1617 {
1618  struct ast_format *cur_dest, *cur_src;
1619  int index;
1620 
1621  for (index = 0; index < ast_format_cap_count(dest); ++index) {
1622  if (!(cur_dest = ast_format_cap_get_format(dest, index))) {
1623  continue;
1624  }
1625 
1626  /* We give preference to a joint format structure if possible */
1627  if ((cur_src = ast_format_cap_get_compatible_format(src, cur_dest))) {
1628  ast_format_cap_append(result, cur_src, 0);
1629  ao2_ref(cur_src, -1);
1630  } else {
1631  /* Otherwise we just use the destination format */
1632  ast_format_cap_append(result, cur_dest, 0);
1633  }
1634  ao2_ref(cur_dest, -1);
1635  }
1636 
1637  /* if we don't have a source format, we just have to try all
1638  possible destination formats */
1639  if (!src) {
1640  return;
1641  }
1642 
1643  for (index = 0; index < ast_format_cap_count(src); ++index) {
1644  if (!(cur_src = ast_format_cap_get_format(src, index))) {
1645  continue;
1646  }
1647 
1649  check_translation_path(dest, src, result,
1650  cur_src, AST_MEDIA_TYPE_AUDIO);
1651  check_translation_path(dest, src, result,
1652  cur_src, AST_MEDIA_TYPE_VIDEO);
1654  ao2_ref(cur_src, -1);
1655  }
1656 }
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
Definition of a media format.
Definition: format.c:43
size_t ast_format_cap_count(const struct ast_format_cap *cap)
Get the number of formats present within the capabilities structure.
Definition: format_cap.c:395
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
struct ast_format * ast_format_cap_get_compatible_format(const struct ast_format_cap *cap, const struct ast_format *format)
Find if input ast_format is within the capabilities of the ast_format_cap object then return the comp...
Definition: format_cap.c:546
#define ast_format_cap_append(cap, format, framing)
Add format capability to capabilities structure.
Definition: format_cap.h:99
the list of translators
Definition: codec_dahdi.c:281
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
struct ast_format * ast_format_cap_get_format(const struct ast_format_cap *cap, int position)
Get the format at a specific index.
Definition: format_cap.c:400
int ast_translate_init ( void  )

Initialize the translation matrix and index to format conversion table.

Return values
0on success
-1on failure

Definition at line 1675 of file translate.c.

References ast_cli_register_multiple, ast_register_cleanup(), and ast_rwlock_init.

1676 {
1677  int res = 0;
1679  res = matrix_resize(1);
1680  res |= ast_cli_register_multiple(cli_translate, ARRAY_LEN(cli_translate));
1681  ast_register_cleanup(translate_shutdown);
1682  return res;
1683 }
static ast_rwlock_t tablelock
Definition: translate.c:87
#define ast_rwlock_init(rwlock)
wrapper for rwlock with tracking enabled
Definition: lock.h:224
#define ast_cli_register_multiple(e, len)
Register multiple commands.
Definition: cli.h:265
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
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
destdestination format
srcsource format
Returns
the number of translation steps required
Return values
-1if no path is available

Definition at line 1536 of file translate.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, and translator_path::multistep.

Referenced by ast_channel_make_compatible_helper().

1537 {
1538  unsigned int res = -1;
1539  /* convert bitwise format numbers into array indices */
1540  int src = format2index(src_format);
1541  int dest = format2index(dst_format);
1542 
1543  if (src < 0 || dest < 0) {
1544  ast_log(LOG_WARNING, "No translator path: (%s codec is not valid)\n", src < 0 ? "starting" : "ending");
1545  return -1;
1546  }
1548 
1549  if (matrix_get(src, dest)->step) {
1550  res = matrix_get(src, dest)->multistep + 1;
1551  }
1552 
1554 
1555  return res;
1556 }
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
the list of translators
Definition: codec_dahdi.c:281
uint8_t multistep
Definition: translate.c:63
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
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
ttranslator structure containing the translation path
strast_str output buffer
Returns
on success pointer to beginning of outbuf
Return values
""on failure

Definition at line 930 of file translate.c.

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

Referenced by handle_showchan().

931 {
932  if (!p || !p->t) {
933  return "";
934  }
935 
936  ast_str_reset(*str);
937  codec_append_name(&p->t->src_codec, str);
938  while (p) {
939  ast_str_append(str, 0, "->");
940  codec_append_name(&p->t->dst_codec, str);
941  p = p->next;
942  }
943 
944  return ast_str_buffer(*str);
945 }
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:761
int ast_str_append(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Append to a thread local dynamic string.
Definition: strings.h:1139
void ast_str_reset(struct ast_str *buf)
Reset the content of a dynamic string. Useful before a series of ast_str_append.
Definition: strings.h:693
void ast_translator_activate ( struct ast_translator t)

Activate a previously deactivated translator.

Parameters
ttranslator to activate

Enables the specified translator for use.

Definition at line 1378 of file translate.c.

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

1379 {
1381  t->active = 1;
1382  matrix_rebuild(0);
1384 }
static void matrix_rebuild(int samples)
rebuild a translation matrix.
Definition: translate.c:825
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
the list of translators
Definition: codec_dahdi.c:281
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
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_capdestination capabilities
src_capsource capabilities
dst_fmt_outdestination format chosen out of destination capabilities
src_fmt_outsource format chosen out of source capabilities
Return values
0on success
-1if 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.

References 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_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, format_sample_rate_absdiff, translator_path::multistep, ast_codec::quality, RAII_VAR, and translator_path::table_cost.

Referenced by ast_channel_make_compatible_helper(), ast_speech_new(), and local_request_with_stream_topology().

1406 {
1407  unsigned int besttablecost = INT_MAX;
1408  unsigned int beststeps = INT_MAX;
1409  struct ast_format *fmt;
1410  struct ast_format *dst;
1411  struct ast_format *src;
1412  RAII_VAR(struct ast_format *, best, NULL, ao2_cleanup);
1413  RAII_VAR(struct ast_format *, bestdst, NULL, ao2_cleanup);
1414  struct ast_format_cap *joint_cap;
1415  int i;
1416  int j;
1417 
1418  if (ast_format_cap_empty(dst_cap) || ast_format_cap_empty(src_cap)) {
1419  ast_log(LOG_ERROR, "Cannot determine best translation path since one capability supports no formats\n");
1420  return -1;
1421  }
1422 
1424  if (!joint_cap) {
1425  return -1;
1426  }
1427  ast_format_cap_get_compatible(dst_cap, src_cap, joint_cap);
1428 
1429  for (i = 0; i < ast_format_cap_count(joint_cap); ++i, ao2_cleanup(fmt)) {
1430  fmt = ast_format_cap_get_format(joint_cap, i);
1431  if (!fmt
1432  || ast_format_get_type(fmt) != AST_MEDIA_TYPE_AUDIO) {
1433  continue;
1434  }
1435 
1436  if (!best
1438  ao2_replace(best, fmt);
1439  }
1440  }
1441  ao2_ref(joint_cap, -1);
1442 
1443  if (best) {
1444  ao2_replace(*dst_fmt_out, best);
1445  ao2_replace(*src_fmt_out, best);
1446  return 0;
1447  }
1448 
1449  /* need to translate */
1451  for (i = 0; i < ast_format_cap_count(dst_cap); ++i, ao2_cleanup(dst)) {
1452  dst = ast_format_cap_get_format(dst_cap, i);
1453  if (!dst
1454  || ast_format_get_type(dst) != AST_MEDIA_TYPE_AUDIO) {
1455  continue;
1456  }
1457 
1458  for (j = 0; j < ast_format_cap_count(src_cap); ++j, ao2_cleanup(src)) {
1459  int x;
1460  int y;
1461 
1462  src = ast_format_cap_get_format(src_cap, j);
1463  if (!src
1464  || ast_format_get_type(src) != AST_MEDIA_TYPE_AUDIO) {
1465  continue;
1466  }
1467 
1468  x = format2index(src);
1469  y = format2index(dst);
1470  if (x < 0 || y < 0) {
1471  continue;
1472  }
1473  if (!matrix_get(x, y) || !(matrix_get(x, y)->step)) {
1474  continue;
1475  }
1476  if (matrix_get(x, y)->table_cost < besttablecost
1477  || matrix_get(x, y)->multistep < beststeps) {
1478  /* better than what we have so far */
1479  ao2_replace(best, src);
1480  ao2_replace(bestdst, dst);
1481  besttablecost = matrix_get(x, y)->table_cost;
1482  beststeps = matrix_get(x, y)->multistep;
1483  } else if (matrix_get(x, y)->table_cost == besttablecost
1484  && matrix_get(x, y)->multistep == beststeps) {
1485  int replace = 0;
1486  unsigned int gap_selected = format_sample_rate_absdiff(best, bestdst);
1487  unsigned int gap_current = format_sample_rate_absdiff(src, dst);
1488 
1489  if (gap_current < gap_selected) {
1490  /* better than what we have so far */
1491  replace = 1;
1492  } else if (gap_current == gap_selected) {
1493  int src_quality, best_quality;
1494  struct ast_codec *src_codec, *best_codec;
1495 
1496  src_codec = ast_format_get_codec(src);
1497  best_codec = ast_format_get_codec(best);
1498  src_quality = src_codec->quality;
1499  best_quality = best_codec->quality;
1500 
1501  ao2_cleanup(src_codec);
1502  ao2_cleanup(best_codec);
1503 
1504  /* We have a tie, so choose the format with the higher quality, if they differ. */
1505  if (src_quality > best_quality) {
1506  /* Better than what we had before. */
1507  replace = 1;
1508  ast_debug(2, "Tiebreaker: preferring format %s (%d) to %s (%d)\n", ast_format_get_name(src), src_quality,
1509  ast_format_get_name(best), best_quality);
1510  } else {
1511  /* This isn't necessarily indicative of a problem, but in reality this shouldn't really happen, unless
1512  * there are 2 formats that are basically the same. */
1513  ast_debug(1, "Completely ambiguous tie between formats %s and %s (quality %d): sticking with %s, but this is arbitrary\n",
1514  ast_format_get_name(src), ast_format_get_name(best), best_quality, ast_format_get_name(best));
1515  }
1516  }
1517  if (replace) {
1518  ao2_replace(best, src);
1519  ao2_replace(bestdst, dst);
1520  besttablecost = matrix_get(x, y)->table_cost;
1521  beststeps = matrix_get(x, y)->multistep;
1522  }
1523  }
1524  }
1525  }
1527 
1528  if (!best) {
1529  return -1;
1530  }
1531  ao2_replace(*dst_fmt_out, bestdst);
1532  ao2_replace(*src_fmt_out, best);
1533  return 0;
1534 }
enum ast_media_type ast_format_get_type(const struct ast_format *format)
Get the media type of a format.
Definition: format.c:354
struct ast_codec * ast_format_get_codec(const struct ast_format *format)
Get the codec associated with a format.
Definition: format.c:324
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
Definition of a media format.
Definition: format.c:43
size_t ast_format_cap_count(const struct ast_format_cap *cap)
Get the number of formats present within the capabilities structure.
Definition: format_cap.c:395
const char * ast_format_get_name(const struct ast_format *format)
Get the name associated with a format.
Definition: format.c:334
#define format_sample_rate_absdiff(fmt1, fmt2)
Definition: translate.c:1395
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
unsigned int quality
Format quality, on scale from 0 to 150 (100 is ulaw, the reference). This allows better format to be ...
Definition: codec.h:82
#define ast_debug(level,...)
Log a DEBUG message.
#define ast_format_cap_alloc(flags)
Allocate a new ast_format_cap structure.
Definition: format_cap.h:49
the list of translators
Definition: codec_dahdi.c:281
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
uint32_t table_cost
Definition: translate.c:61
uint8_t multistep
Definition: translate.c:63
#define ao2_replace(dst, src)
Replace one object reference with another cleaning up the original.
Definition: astobj2.h:501
unsigned int ast_format_get_sample_rate(const struct ast_format *format)
Get the sample rate of a media format.
Definition: format.c:379
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
int ast_format_cap_empty(const struct ast_format_cap *cap)
Determine if a format cap has no formats in it.
Definition: format_cap.c:744
struct ast_format * ast_format_cap_get_format(const struct ast_format_cap *cap, int position)
Get the format at a specific index.
Definition: format_cap.c:400
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
int ast_format_cap_get_compatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result)
Find the compatible formats between two capabilities structures.
Definition: format_cap.c:628
Represents a media codec within Asterisk.
Definition: codec.h:42
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
dstdest destination format
srcsource source format
Returns
ast_trans_pvt on success
Return values
NULLon failure

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

Definition at line 486 of file translate.c.

References ast_format_get_name(), ast_format_get_sample_rate(), ast_format_get_type(), AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_translator_free_path(), ast_tv(), ast_translator::dst_codec, ast_translator::dst_fmt_index, newpvt(), ast_trans_pvt::next, ast_codec::sample_rate, translator_path::step, and ast_codec::type.

Referenced by ast_set_read_format_path(), ast_set_write_format_path(), ast_slinfactory_feed(), and ast_writestream().

487 {
488  struct ast_trans_pvt *head = NULL, *tail = NULL;
489  int src_index, dst_index;
490 
491  src_index = format2index(src);
492  dst_index = format2index(dst);
493 
494  if (src_index < 0 || dst_index < 0) {
495  ast_log(LOG_WARNING, "No translator path: (%s codec is not valid)\n", src_index < 0 ? "starting" : "ending");
496  return NULL;
497  }
498 
500 
501  while (src_index != dst_index) {
502  struct ast_trans_pvt *cur;
503  struct ast_format *explicit_dst = NULL;
504  struct ast_translator *t = matrix_get(src_index, dst_index)->step;
505  if (!t) {
506  ast_log(LOG_WARNING, "No translator path from %s to %s\n",
510  return NULL;
511  }
513  explicit_dst = dst;
514  }
515  if (!(cur = newpvt(t, explicit_dst))) {
516  ast_log(LOG_WARNING, "Failed to build translator step from %s to %s\n",
520  return NULL;
521  }
522  if (!head) {
523  head = cur;
524  } else {
525  tail->next = cur;
526  }
527  tail = cur;
528  cur->nextin = cur->nextout = ast_tv(0, 0);
529  /* Keep going if this isn't the final destination */
530  src_index = cur->t->dst_fmt_index;
531  }
532 
534  return head;
535 }
enum ast_media_type ast_format_get_type(const struct ast_format *format)
Get the media type of a format.
Definition: format.c:354
Descriptor of a translator.
Definition: translate.h:137
#define AST_RWLIST_RDLOCK(head)
Read locks a list.
Definition: linkedlists.h:78
Definition of a media format.
Definition: format.c:43
const char * ast_format_get_name(const struct ast_format *format)
Get the name associated with a format.
Definition: format.c:334
struct ast_trans_pvt * next
Definition: translate.h:227
struct ast_translator * step
Definition: translate.c:60
void ast_translator_free_path(struct ast_trans_pvt *p)
Frees a translator path Frees the given translator path structure.
Definition: translate.c:476
static struct ast_trans_pvt * newpvt(struct ast_translator *t, struct ast_format *explicit_dst)
Allocate the descriptor, required outbuf space, and possibly desc.
Definition: translate.c:312
the list of translators
Definition: codec_dahdi.c:281
struct ast_codec dst_codec
Definition: translate.h:140
Default structure for translators, with the basic fields and buffers, all allocated as part of the sa...
Definition: translate.h:213
unsigned int sample_rate
Sample rate (number of samples carried in a second)
Definition: codec.h:52
struct timeval ast_tv(ast_time_t sec, ast_suseconds_t usec)
Returns a timeval from sec, usec.
Definition: time.h:235
unsigned int ast_format_get_sample_rate(const struct ast_format *format)
Get the sample rate of a media format.
Definition: format.c:379
enum ast_media_type type
Type of media this codec contains.
Definition: codec.h:50
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
void ast_translator_deactivate ( struct ast_translator t)

Deactivate a translator.

Parameters
ttranslator to deactivate

Disables the specified translator from being used.

Definition at line 1386 of file translate.c.

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

1387 {
1389  t->active = 0;
1390  matrix_rebuild(0);
1392 }
static void matrix_rebuild(int samples)
rebuild a translation matrix.
Definition: translate.c:825
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
the list of translators
Definition: codec_dahdi.c:281
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
void ast_translator_free_path ( struct ast_trans_pvt tr)

Frees a translator path Frees the given translator path structure.

Parameters
trtranslator path to get rid of

Definition at line 476 of file translate.c.

References 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(), and conf_free().

477 {
478  struct ast_trans_pvt *pn = p;
479  while ( (p = pn) ) {
480  pn = p->next;
481  destroy(p);
482  }
483 }
struct ast_trans_pvt * next
Definition: translate.h:227
Default structure for translators, with the basic fields and buffers, all allocated as part of the sa...
Definition: translate.h:213
int ast_unregister_translator ( struct ast_translator t)

Unregister a translator Unregisters the given translator.

Parameters
ttranslator to unregister
Return values
0on success
-1on failure

Unregister a translator Unregisters the given translator.

Definition at line 1350 of file translate.c.

References AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_shutting_down(), ast_translator::dst_codec, ast_translator::list, matrix_rebuild(), ast_codec::name, ast_translator::name, ast_translator::src_codec, and term_color().

Referenced by unload_module().

1351 {
1352  char tmp[80];
1353  struct ast_translator *u;
1354  int found = 0;
1355 
1357  AST_RWLIST_TRAVERSE_SAFE_BEGIN(&translators, u, list) {
1358  if (u == t) {
1359  AST_RWLIST_REMOVE_CURRENT(list);
1360  ast_verb(5, "Unregistered translator '%s' from codec %s to %s\n",
1361  term_color(tmp, t->name, COLOR_MAGENTA, COLOR_BLACK, sizeof(tmp)),
1362  t->src_codec.name, t->dst_codec.name);
1363  found = 1;
1364  break;
1365  }
1366  }
1367  AST_RWLIST_TRAVERSE_SAFE_END;
1368 
1369  if (found && !ast_shutting_down()) {
1370  matrix_rebuild(0);
1371  }
1372 
1374 
1375  return (u ? 0 : -1);
1376 }
const char * name
Name for this codec.
Definition: codec.h:46
int ast_shutting_down(void)
Definition: asterisk.c:1876
static void matrix_rebuild(int samples)
rebuild a translation matrix.
Definition: translate.c:825
Descriptor of a translator.
Definition: translate.h:137
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:52
char * term_color(char *outbuf, const char *inbuf, int fgcolor, int bgcolor, int maxout)
Colorize a specified string by adding terminal color codes.
Definition: term.c:235
the list of translators
Definition: codec_dahdi.c:281
struct ast_codec dst_codec
Definition: translate.h:140
struct ast_codec src_codec
Definition: translate.h:139
struct ast_translator::@290 list
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:151
char name[80]
Definition: translate.h:138