Asterisk - The Open Source Telephony Project  GIT-master-b91fb3c
Data Structures | Macros | Enumerations | Functions
codec.h File Reference

Codec API. More...

Go to the source code of this file.

Data Structures

struct  ast_codec
 Represents a media codec within Asterisk. More...
 

Macros

#define ast_codec_register(codec)   __ast_codec_register(codec, AST_MODULE_SELF)
 This function is used to register a codec with the Asterisk core. Registering allows it to be passed through in frames and configured in channel drivers. More...
 

Enumerations

enum  ast_media_type {
  AST_MEDIA_TYPE_UNKNOWN = 0, AST_MEDIA_TYPE_AUDIO, AST_MEDIA_TYPE_VIDEO, AST_MEDIA_TYPE_IMAGE,
  AST_MEDIA_TYPE_TEXT, AST_MEDIA_TYPE_END
}
 Types of media. More...
 

Functions

int __ast_codec_register (struct ast_codec *codec, struct ast_module *mod)
 This function is used to register a codec with the Asterisk core. Registering allows it to be passed through in frames and configured in channel drivers. More...
 
int ast_codec_builtin_init (void)
 Initialize built-in codecs within the core. More...
 
unsigned int ast_codec_determine_length (const struct ast_codec *codec, unsigned int samples)
 Get the length of media (in milliseconds) given a number of samples. More...
 
struct ast_codecast_codec_get (const char *name, enum ast_media_type type, unsigned int sample_rate)
 Retrieve a codec given a name, type, and sample rate. More...
 
struct ast_codecast_codec_get_by_id (int id)
 Retrieve a codec given the unique identifier. More...
 
int ast_codec_get_max (void)
 Retrieve the current maximum identifier for codec iteration. More...
 
int ast_codec_init (void)
 Initialize codec support within the core. More...
 
const char * ast_codec_media_type2str (enum ast_media_type type)
 Conversion function to take a media type and turn it into a string. More...
 
unsigned int ast_codec_samples_count (struct ast_frame *frame)
 Get the number of samples contained within a frame. More...
 
enum ast_media_type ast_media_type_from_str (const char *media_type_str)
 Conversion function to take a media string and convert it to a media type. More...
 

Detailed Description

Codec API.

Author
Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file codec.h.

Macro Definition Documentation

◆ ast_codec_register

#define ast_codec_register (   codec)    __ast_codec_register(codec, AST_MODULE_SELF)

This function is used to register a codec with the Asterisk core. Registering allows it to be passed through in frames and configured in channel drivers.

Parameters
codecto register
Return values
0success
-1failure

Definition at line 122 of file codec.h.

Referenced by AST_TEST_DEFINE(), and load_module().

Enumeration Type Documentation

◆ ast_media_type

Types of media.

Enumerator
AST_MEDIA_TYPE_UNKNOWN 
AST_MEDIA_TYPE_AUDIO 
AST_MEDIA_TYPE_VIDEO 
AST_MEDIA_TYPE_IMAGE 
AST_MEDIA_TYPE_TEXT 
AST_MEDIA_TYPE_END 

Definition at line 30 of file codec.h.

Function Documentation

◆ __ast_codec_register()

int __ast_codec_register ( struct ast_codec codec,
struct ast_module mod 
)

This function is used to register a codec with the Asterisk core. Registering allows it to be passed through in frames and configured in channel drivers.

Parameters
codecto register
modthe module this codec is provided by
Return values
0success
-1failure

Definition at line 272 of file codec.c.

References __ast_codec_register_with_format(), and NULL.

273 {
274  return __ast_codec_register_with_format(codec, NULL, mod);
275 }
#define NULL
Definition: resample.c:96
int __ast_codec_register_with_format(struct ast_codec *codec, const char *format_name, struct ast_module *mod)
Definition: codec.c:277

◆ ast_codec_builtin_init()

int ast_codec_builtin_init ( void  )

Initialize built-in codecs within the core.

Return values
0success
-1failure

Definition at line 942 of file codec_builtin.c.

References CODEC_REGISTER_AND_CACHE, and CODEC_REGISTER_AND_CACHE_NAMED.

Referenced by asterisk_daemon().

943 {
944  int res = 0;
945 
955  res |= CODEC_REGISTER_AND_CACHE_NAMED("slin12", slin12);
956  res |= CODEC_REGISTER_AND_CACHE_NAMED("slin16", slin16);
957  res |= CODEC_REGISTER_AND_CACHE_NAMED("slin24", slin24);
958  res |= CODEC_REGISTER_AND_CACHE_NAMED("slin32", slin32);
959  res |= CODEC_REGISTER_AND_CACHE_NAMED("slin44", slin44);
960  res |= CODEC_REGISTER_AND_CACHE_NAMED("slin48", slin48);
961  res |= CODEC_REGISTER_AND_CACHE_NAMED("slin96", slin96);
962  res |= CODEC_REGISTER_AND_CACHE_NAMED("slin192", slin192);
966  res |= CODEC_REGISTER_AND_CACHE_NAMED("speex16", speex16);
967  res |= CODEC_REGISTER_AND_CACHE_NAMED("speex32", speex32);
989  res |= CODEC_REGISTER_AND_CACHE_NAMED("silk8", silk8);
990  res |= CODEC_REGISTER_AND_CACHE_NAMED("silk12", silk12);
991  res |= CODEC_REGISTER_AND_CACHE_NAMED("silk16", silk16);
992  res |= CODEC_REGISTER_AND_CACHE_NAMED("silk24", silk24);
993 
994  return res;
995 }
static struct ast_codec testlaw
static struct ast_codec slin8
static struct ast_codec opus
static struct ast_codec ulaw
static struct ast_codec speex8
static struct ast_codec g726aal2
static struct ast_codec slin48
static struct ast_codec silk12
static struct ast_codec none
static struct ast_codec slin44
static struct ast_codec silk24
static struct ast_codec slin16
#define CODEC_REGISTER_AND_CACHE_NAMED(fmt_name, codec)
static struct ast_codec h261
static struct ast_codec siren14
static struct ast_codec speex16
static struct ast_codec t140red
static struct ast_codec alaw
static struct ast_codec siren7
static struct ast_codec silk16
#define CODEC_REGISTER_AND_CACHE(codec)
static struct ast_codec codec2
static struct ast_codec mpeg4
static struct ast_codec g722
static struct ast_codec silk8
static struct ast_codec t38
static struct ast_codec slin192
static struct ast_codec speex32
static struct ast_codec jpeg
static struct ast_codec slin96
static struct ast_codec adpcm
static struct ast_codec g729a
static struct ast_codec h263
static struct ast_codec h264
static struct ast_codec vp8
static struct ast_codec slin32
static struct ast_codec t140
static struct ast_codec g726rfc3551
static struct ast_codec slin24
static struct ast_codec g719
static struct ast_codec h265
static struct ast_codec lpc10
static struct ast_codec png
static struct ast_codec g723
Definition: codec_builtin.c:97
static struct ast_codec vp9
static struct ast_codec slin12
static struct ast_codec h263p
static struct ast_codec ilbc

◆ ast_codec_determine_length()

unsigned int ast_codec_determine_length ( const struct ast_codec codec,
unsigned int  samples 
)

Get the length of media (in milliseconds) given a number of samples.

Parameters
codecThe codec itself
samplesThe number of samples
Return values
lengthof media (in milliseconds)

Definition at line 407 of file codec.c.

References ast_codec::get_length.

Referenced by ast_format_determine_length().

408 {
409  if (!codec->get_length) {
410  return 0;
411  }
412 
413  return codec->get_length(samples);
414 }
int(* get_length)(unsigned int samples)
Retrieve the length of media from number of samples.
Definition: codec.h:76

◆ ast_codec_get()

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.

Parameters
nameThe name of the codec
typeThe type of the codec
sample_rateOptional sample rate, may not be applicable for some types
Return values
non-NULLsuccess
NULLfailure
Note
The returned codec is reference counted and ao2_ref or ao2_cleanup must be used to release the reference.

Definition at line 326 of file codec.c.

References ao2_find, ast_codec::name, name, OBJ_SEARCH_OBJECT, ast_codec::sample_rate, and type.

Referenced by __ast_register_translator(), AST_TEST_DEFINE(), handle_show_translation_path(), and newpvt().

327 {
328  struct ast_codec codec = {
329  .name = name,
330  .type = type,
331  .sample_rate = sample_rate,
332  };
333 
334  return ao2_find(codecs, &codec, OBJ_SEARCH_OBJECT);
335 }
static const char type[]
Definition: chan_ooh323.c:109
const char * name
Name for this codec.
Definition: codec.h:46
static struct ao2_container * codecs
Registered codecs.
Definition: codec.c:48
static const char name[]
Definition: cdr_mysql.c:74
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1756
unsigned int sample_rate
Sample rate (number of samples carried in a second)
Definition: codec.h:52
The arg parameter is an object of the same type.
Definition: astobj2.h:1091
Represents a media codec within Asterisk.
Definition: codec.h:42

◆ ast_codec_get_by_id()

struct ast_codec* ast_codec_get_by_id ( int  id)

Retrieve a codec given the unique identifier.

Parameters
idThe unique identifier
Return values
non-NULLsuccess
NULLfailure
Note
Identifiers start at 1 so if iterating don't start at 0.
The returned codec is reference counted and ao2_ref or ao2_cleanup must be used to release the reference.

Definition at line 337 of file codec.c.

References ao2_callback, and codec_id_cmp().

Referenced by ast_format_cap_append_by_type(), AST_TEST_DEFINE(), complete_trans_path_choice(), handle_show_translation_path(), handle_show_translation_table(), and index2codec().

338 {
339  return ao2_callback(codecs, 0, codec_id_cmp, &id);
340 }
#define ao2_callback(c, flags, cb_fn, arg)
Definition: astobj2.h:1716
static int codec_id_cmp(void *obj, void *arg, int flags)
Callback function for getting a codec based on unique identifier.
Definition: codec.c:189
static struct ao2_container * codecs
Registered codecs.
Definition: codec.c:48

◆ ast_codec_get_max()

int ast_codec_get_max ( void  )

Retrieve the current maximum identifier for codec iteration.

Returns
Maximum codec identifier

Definition at line 342 of file codec.c.

References codec_id.

Referenced by ast_format_cap_append_by_type(), and AST_TEST_DEFINE().

343 {
344  return codec_id;
345 }
static int codec_id
Current identifier value for newly registered codec.
Definition: codec.c:45

◆ ast_codec_init()

int ast_codec_init ( void  )

Initialize codec support within the core.

Return values
0success
-1failure

Definition at line 249 of file codec.c.

References AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_container_alloc_hash, ARRAY_LEN, ast_cli_register_multiple, ast_register_cleanup(), CODEC_BUCKETS, codec_cmp(), codec_shutdown(), and NULL.

Referenced by asterisk_daemon().

250 {
252  ast_codec_hash_fn, NULL, codec_cmp);
253  if (!codecs) {
254  return -1;
255  }
256 
259 
260  return 0;
261 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
static struct ast_cli_entry codec_cli[]
Definition: codec.c:236
#define ast_cli_register_multiple(e, len)
Register multiple commands.
Definition: cli.h:265
#define NULL
Definition: resample.c:96
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
static struct ao2_container * codecs
Registered codecs.
Definition: codec.c:48
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Definition: astobj2.h:1310
static void codec_shutdown(void)
Function called when the process is shutting down.
Definition: codec.c:242
static int codec_cmp(void *obj, void *arg, int flags)
Definition: codec.c:78
#define CODEC_BUCKETS
Number of buckets to use for codecs (should be prime for performance reasons)
Definition: codec.c:42

◆ ast_codec_media_type2str()

const char* ast_codec_media_type2str ( enum ast_media_type  type)

Conversion function to take a media type and turn it into a string.

Parameters
typeThe media type
Return values
stringrepresentation of the media type

Definition at line 347 of file codec.c.

References AST_MEDIA_TYPE_AUDIO, AST_MEDIA_TYPE_IMAGE, AST_MEDIA_TYPE_TEXT, and AST_MEDIA_TYPE_VIDEO.

Referenced by __ast_codec_register_with_format(), add_msid_to_stream(), add_sdp_streams(), ast_rtp_engine_load_format(), ast_rtp_interpret(), ast_rtp_read(), ast_sip_create_joint_call_cap(), ast_sip_session_media_state_add(), ast_stream_create_resolved(), ast_stream_to_str(), ast_stream_topology_append_stream(), ast_stream_topology_create_from_format_cap(), ast_stream_topology_set_stream(), AST_TEST_DEFINE(), chan_pjsip_write_stream(), check_stream_positions(), create_outgoing_sdp_stream(), handle_incoming_sdp(), handle_negotiated_sdp_session_media(), handle_showchan(), is_media_state_valid(), log_caps(), negotiate_incoming_sdp_stream(), rtp_check_timeout(), sdp_requires_deferral(), set_caps(), set_incoming_call_offer_cap(), show_codecs(), stream_echo_exec(), and stream_echo_write_error().

348 {
349  switch (type) {
351  return "audio";
353  return "video";
355  return "image";
356  case AST_MEDIA_TYPE_TEXT:
357  return "text";
358  default:
359  return "<unknown>";
360  }
361 }
static const char type[]
Definition: chan_ooh323.c:109

◆ ast_codec_samples_count()

unsigned int ast_codec_samples_count ( struct ast_frame frame)

Get the number of samples contained within a frame.

Parameters
frameThe frame itself
Return values
numberof samples in the frame

Definition at line 378 of file codec.c.

References ao2_ref, ast_format_get_codec(), ast_format_get_name(), AST_FRAME_IMAGE, AST_FRAME_VIDEO, AST_FRAME_VOICE, ast_log, ast_frame_subclass::format, ast_frame::frametype, LOG_WARNING, ast_codec::samples_count, and ast_frame::subclass.

Referenced by ast_rtp_interpret(), dahdi_encoder_frameout(), isAnsweringMachine(), moh_generate(), ogg_speex_read(), schedule_delivery(), socket_process_helper(), and socket_process_meta().

379 {
380  struct ast_codec *codec;
381  unsigned int samples = 0;
382 
383  if ((frame->frametype != AST_FRAME_VOICE) &&
384  (frame->frametype != AST_FRAME_VIDEO) &&
385  (frame->frametype != AST_FRAME_IMAGE)) {
386  return 0;
387  }
388 
389  codec = ast_format_get_codec(frame->subclass.format);
390 
391  if (codec->samples_count) {
392  samples = codec->samples_count(frame);
393  if ((int) samples < 0) {
394  ast_log(LOG_WARNING, "Codec %s returned invalid number of samples.\n",
396  samples = 0;
397  }
398  } else {
399  ast_log(LOG_WARNING, "Unable to calculate samples for codec %s\n",
401  }
402 
403  ao2_ref(codec, -1);
404  return samples;
405 }
struct ast_codec * ast_format_get_codec(const struct ast_format *format)
Get the codec associated with a format.
Definition: format.c:324
#define LOG_WARNING
Definition: logger.h:274
const char * ast_format_get_name(const struct ast_format *format)
Get the name associated with a format.
Definition: format.c:334
struct ast_frame_subclass subclass
#define ast_log
Definition: astobj2.c:42
#define ao2_ref(o, delta)
Definition: astobj2.h:464
int(* samples_count)(struct ast_frame *frame)
Retrieve the number of samples in a frame.
Definition: codec.h:68
enum ast_frame_type frametype
struct ast_format * format
Represents a media codec within Asterisk.
Definition: codec.h:42

◆ ast_media_type_from_str()

enum ast_media_type ast_media_type_from_str ( const char *  media_type_str)

Conversion function to take a media string and convert it to a media type.

Parameters
media_type_strThe media type string
Return values
Theast_media_type that corresponds to the string
Since
15.0.0

Definition at line 363 of file codec.c.

References AST_MEDIA_TYPE_AUDIO, AST_MEDIA_TYPE_IMAGE, AST_MEDIA_TYPE_TEXT, AST_MEDIA_TYPE_UNKNOWN, and AST_MEDIA_TYPE_VIDEO.

Referenced by handle_incoming_sdp(), sdp_requires_deferral(), and stream_echo_exec().

364 {
365  if (!strcasecmp(media_type_str, "audio")) {
366  return AST_MEDIA_TYPE_AUDIO;
367  } else if (!strcasecmp(media_type_str, "video")) {
368  return AST_MEDIA_TYPE_VIDEO;
369  } else if (!strcasecmp(media_type_str, "image")) {
370  return AST_MEDIA_TYPE_IMAGE;
371  } else if (!strcasecmp(media_type_str, "text")) {
372  return AST_MEDIA_TYPE_TEXT;
373  } else {
374  return AST_MEDIA_TYPE_UNKNOWN;
375  }
376 }