codec.c File Reference

Codecs API. More...

#include "asterisk.h"
#include "asterisk/logger.h"
#include "asterisk/codec.h"
#include "asterisk/format.h"
#include "asterisk/frame.h"
#include "asterisk/astobj2.h"
#include "asterisk/strings.h"
#include "asterisk/module.h"
#include "asterisk/cli.h"

Include dependency graph for codec.c:

Go to the source code of this file.

Data Structures
struct	internal_ast_codec

Macros
#define	CODEC_BUCKETS   53
	Number of buckets to use for codecs (should be prime for performance reasons) 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_register_with_format (struct ast_codec *codec, const char *format_name, struct ast_module *mod)
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_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. More...
struct ast_codec *	ast_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...
static int	codec_cmp (void *obj, void *arg, int flags)
static void	codec_dtor (void *obj)
static int	codec_id_cmp (void *obj, void *arg, int flags)
	Callback function for getting a codec based on unique identifier. More...
static void	codec_shutdown (void)
	Function called when the process is shutting down. More...
static char *	show_codec (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
static char *	show_codecs (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)

Variables
static struct ast_cli_entry	codec_cli []
static int	codec_id = 1
	Current identifier value for newly registered codec. More...
static struct ao2_container *	codecs
	Registered codecs. More...

Detailed Description

Codecs API.

Author

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

Definition in file codec.c.

Macro Definition Documentation

CODEC_BUCKETS

#define CODEC_BUCKETS   53

Number of buckets to use for codecs (should be prime for performance reasons)

Definition at line 42 of file codec.c.

Referenced by ast_codec_init().

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

codec	to register
mod	the module this codec is provided by

Return values

0	success
-1	failure

Definition at line 272 of file codec.c.

References __ast_codec_register_with_format(), and NULL.

{
   return __ast_codec_register_with_format(codec, NULL, mod);
}

__ast_codec_register_with_format()

int __ast_codec_register_with_format	(	struct ast_codec *	codec,
		const char *	format_name,
		struct ast_module *	mod
	)

Definition at line 277 of file codec.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_find, ao2_link_flags, ao2_ref, ao2_t_alloc_options, ast_codec_media_type2str(), ast_log, AST_MEDIA_TYPE_AUDIO, AST_MEDIA_TYPE_UNKNOWN, ast_module_shutdown_ref, ast_verb, codec_dtor(), codec_id, ast_codec::description, internal_ast_codec::external, internal_ast_codec::format_name, ast_codec::id, lock, LOG_ERROR, ast_codec::name, OBJ_NOLOCK, OBJ_SEARCH_OBJECT, S_OR, ast_codec::sample_rate, SCOPED_AO2WRLOCK, and ast_codec::type.

Referenced by __ast_codec_register().

{
   SCOPED_AO2WRLOCK(lock, codecs);
   struct internal_ast_codec *codec_new;

   /* Some types have specific requirements */
   if (codec->type == AST_MEDIA_TYPE_UNKNOWN) {
      ast_log(LOG_ERROR, "A media type must be specified for codec '%s'\n", codec->name);
      return -1;
   } else if (codec->type == AST_MEDIA_TYPE_AUDIO) {
      if (!codec->sample_rate) {
         ast_log(LOG_ERROR, "A sample rate must be specified for codec '%s' of type '%s'\n",
            codec->name, ast_codec_media_type2str(codec->type));
         return -1;
      }
   }

   codec_new = ao2_find(codecs, codec, OBJ_SEARCH_OBJECT | OBJ_NOLOCK);
   if (codec_new) {
      ast_log(LOG_ERROR, "A codec with name '%s' of type '%s' and sample rate '%u' is already registered\n",
         codec->name, ast_codec_media_type2str(codec->type), codec->sample_rate);
      ao2_ref(codec_new, -1);
      return -1;
   }

   codec_new = ao2_t_alloc_options(sizeof(*codec_new), codec_dtor,
      AO2_ALLOC_OPT_LOCK_NOLOCK, S_OR(codec->description, ""));
   if (!codec_new) {
      ast_log(LOG_ERROR, "Could not allocate a codec with name '%s' of type '%s' and sample rate '%u'\n",
         codec->name, ast_codec_media_type2str(codec->type), codec->sample_rate);
      return -1;
   }
   codec_new->external = *codec;
   codec_new->format_name = format_name;
   codec_new->external.id = codec_id++;

   ao2_link_flags(codecs, codec_new, OBJ_NOLOCK);

   /* Once registered a codec can not be unregistered, and the module must persist until shutdown */
   ast_module_shutdown_ref(mod);

   ast_verb(2, "Registered '%s' codec '%s' at sample rate '%u' with id '%u'\n",
      ast_codec_media_type2str(codec->type), codec->name, codec->sample_rate, codec_new->external.id);

   ao2_ref(codec_new, -1);

   return 0;
}

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

codec	The codec itself
samples	The number of samples

Return values

length

of media (in milliseconds)

Definition at line 407 of file codec.c.

References ast_codec::get_length.

Referenced by ast_format_determine_length().

{
   if (!codec->get_length) {
      return 0;
   }

   return codec->get_length(samples);
}

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

name	The name of the codec
type	The type of the codec
sample_rate	Optional sample rate, may not be applicable for some types

Return values

non-NULL	success
NULL	failure

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

{
   struct ast_codec codec = {
      .name = name,
      .type = type,
      .sample_rate = sample_rate,
   };

   return ao2_find(codecs, &codec, OBJ_SEARCH_OBJECT);
}

ast_codec_get_by_id()

struct ast_codec* ast_codec_get_by_id

(

int

id

)

Retrieve a codec given the unique identifier.

Parameters

id	The unique identifier

Return values

non-NULL	success
NULL	failure

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

{
   return ao2_callback(codecs, 0, codec_id_cmp, &id);
}

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

{
   return codec_id;
}

ast_codec_init()

int ast_codec_init

(

void

)

Initialize codec support within the core.

Return values

0	success
-1	failure

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

{
   codecs = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_RWLOCK, 0, CODEC_BUCKETS,
      ast_codec_hash_fn, NULL, codec_cmp);
   if (!codecs) {
      return -1;
   }

   ast_cli_register_multiple(codec_cli, ARRAY_LEN(codec_cli));
   ast_register_cleanup(codec_shutdown);

   return 0;
}

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

type	The media type

Return values

string

representation 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(), stream_echo_write_error(), and validate_stream().

{
   switch (type) {
   case AST_MEDIA_TYPE_AUDIO:
      return "audio";
   case AST_MEDIA_TYPE_VIDEO:
      return "video";
   case AST_MEDIA_TYPE_IMAGE:
      return "image";
   case AST_MEDIA_TYPE_TEXT:
      return "text";
   default:
      return "<unknown>";
   }
}

ast_codec_samples_count()

unsigned int ast_codec_samples_count

(

struct ast_frame *

frame

)

Get the number of samples contained within a frame.

Parameters

frame

The frame itself

Return values

number

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

{
   struct ast_codec *codec;
   unsigned int samples = 0;

   if ((frame->frametype != AST_FRAME_VOICE) &&
      (frame->frametype != AST_FRAME_VIDEO) &&
      (frame->frametype != AST_FRAME_IMAGE)) {
      return 0;
   }

   codec = ast_format_get_codec(frame->subclass.format);

   if (codec->samples_count) {
      samples = codec->samples_count(frame);
      if ((int) samples < 0) {
         ast_log(LOG_WARNING, "Codec %s returned invalid number of samples.\n",
            ast_format_get_name(frame->subclass.format));
         samples = 0;
      }
   } else {
      ast_log(LOG_WARNING, "Unable to calculate samples for codec %s\n",
         ast_format_get_name(frame->subclass.format));
   }

   ao2_ref(codec, -1);
   return samples;
}

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_str

The media type string

Return values

The	ast_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().

{
   if (!strcasecmp(media_type_str, "audio")) {
      return AST_MEDIA_TYPE_AUDIO;
   } else if (!strcasecmp(media_type_str, "video")) {
      return AST_MEDIA_TYPE_VIDEO;
   } else if (!strcasecmp(media_type_str, "image")) {
      return AST_MEDIA_TYPE_IMAGE;
   } else if (!strcasecmp(media_type_str, "text")) {
      return AST_MEDIA_TYPE_TEXT;
   } else {
      return AST_MEDIA_TYPE_UNKNOWN;
   }
}

codec_cmp()

static int codec_cmp ( void *  obj, void *  arg, int  flags  )

static

Definition at line 78 of file codec.c.

References ast_assert, AST_MEDIA_TYPE_UNKNOWN, CMP_MATCH, ast_codec::name, OBJ_SEARCH_KEY, OBJ_SEARCH_MASK, OBJ_SEARCH_OBJECT, OBJ_SEARCH_PARTIAL_KEY, ast_codec::sample_rate, and ast_codec::type.

Referenced by ast_codec_init().

{
   const struct ast_codec *left = obj;
   const struct ast_codec *right = arg;
   const char *right_key = arg;
   int cmp;

   switch (flags & OBJ_SEARCH_MASK) {
   case OBJ_SEARCH_OBJECT:
      right_key = right->name;
      cmp = strcmp(left->name, right_key);

      if (right->type != AST_MEDIA_TYPE_UNKNOWN) {
         cmp |= (right->type != left->type);
      }

      /* BUGBUG: this will allow a match on a codec by name only.
       * This is particularly useful when executed by the CLI; if
       * that is not needed in translate.c, this can be removed.
       */
      if (right->sample_rate) {
         cmp |= (right->sample_rate != left->sample_rate);
      }
      break;
   case OBJ_SEARCH_KEY:
      cmp = strcmp(left->name, right_key);
      break;
   case OBJ_SEARCH_PARTIAL_KEY:
      cmp = strncmp(left->name, right_key, strlen(right_key));
      break;
   default:
      ast_assert(0);
      cmp = 0;
      break;
   }
   if (cmp) {
      return 0;
   }

   return CMP_MATCH;
}

codec_dtor()

static void codec_dtor ( void *  obj )

static

Definition at line 263 of file codec.c.

References ast_module_unref, and ast_codec::mod.

Referenced by __ast_codec_register_with_format().

{
   struct ast_codec *codec;

   codec = obj;

   ast_module_unref(codec->mod);
}

codec_id_cmp()

static int codec_id_cmp ( void *  obj, void *  arg, int  flags  )

static

Callback function for getting a codec based on unique identifier.

Definition at line 189 of file codec.c.

References CMP_MATCH, CMP_STOP, and ast_codec::id.

Referenced by ast_codec_get_by_id(), and show_codec().

{
   struct ast_codec *codec = obj;
   int *id = arg;

   return (codec->id == *id) ? CMP_MATCH | CMP_STOP : 0;
}

codec_shutdown()

static void codec_shutdown ( void  )

static

Function called when the process is shutting down.

Definition at line 242 of file codec.c.

References ao2_cleanup, ARRAY_LEN, ast_cli_unregister_multiple(), and NULL.

Referenced by ast_codec_init().

{
   ast_cli_unregister_multiple(codec_cli, ARRAY_LEN(codec_cli));
   ao2_cleanup(codecs);
   codecs = NULL;
}

show_codec()

static char* show_codec ( struct ast_cli_entry *  e, int  cmd, struct ast_cli_args *  a  )

static

Definition at line 197 of file codec.c.

References ao2_callback, ao2_ref, ast_cli_args::argc, ast_cli_args::argv, ast_cli(), CLI_GENERATE, CLI_INIT, CLI_SHOWUSAGE, CLI_SUCCESS, codec_id_cmp(), ast_cli_entry::command, ast_codec::description, internal_ast_codec::external, ast_cli_args::fd, internal_ast_codec::format_name, ast_codec::id, NULL, S_OR, and ast_cli_entry::usage.

{
   int type_punned_codec;
   struct internal_ast_codec *codec;

   switch (cmd) {
   case CLI_INIT:
      e->command = "core show codec";
      e->usage =
         "Usage: core show codec <number>\n"
         "       Displays codec mapping\n";
      return NULL;
   case CLI_GENERATE:
      return NULL;
   }

   if (a->argc != 4) {
      return CLI_SHOWUSAGE;
   }

   if (sscanf(a->argv[3], "%30d", &type_punned_codec) != 1) {
      return CLI_SHOWUSAGE;
   }

   codec = ao2_callback(codecs, 0, codec_id_cmp, &type_punned_codec);
   if (!codec) {
      ast_cli(a->fd, "Codec %d not found\n", type_punned_codec);
      return CLI_SUCCESS;
   }

   ast_cli(a->fd, "%11u %s (%s)\n", (unsigned int) codec->external.id, codec->external.description,
      S_OR(codec->format_name, "no format"));

   ao2_ref(codec, -1);

   return CLI_SUCCESS;
}

show_codecs()

static char* show_codecs ( struct ast_cli_entry *  e, int  cmd, struct ast_cli_args *  a  )

static

Definition at line 120 of file codec.c.

References ao2_iterator_destroy(), AO2_ITERATOR_DONTLOCK, ao2_iterator_init(), ao2_iterator_next, ao2_rdlock, ao2_ref, ao2_unlock, ast_cli_args::argc, ast_cli_args::argv, ast_cli(), ast_codec_media_type2str(), AST_MEDIA_TYPE_AUDIO, AST_MEDIA_TYPE_IMAGE, AST_MEDIA_TYPE_TEXT, AST_MEDIA_TYPE_VIDEO, ast_opt_dont_warn, CLI_GENERATE, CLI_INIT, CLI_SHOWUSAGE, CLI_SUCCESS, ast_cli_entry::command, ast_codec::description, internal_ast_codec::external, ast_cli_args::fd, internal_ast_codec::format_name, ast_codec::id, ast_codec::name, NULL, S_OR, ast_codec::type, and ast_cli_entry::usage.

{
   struct ao2_iterator i;
   struct internal_ast_codec *codec;

   switch (cmd) {
   case CLI_INIT:
      e->command = "core show codecs [audio|video|image|text]";
      e->usage =
         "Usage: core show codecs [audio|video|image|text]\n"
         "       Displays codec mapping\n";
      return NULL;
   case CLI_GENERATE:
      return NULL;
   }

   if ((a->argc < 3) || (a->argc > 4)) {
      return CLI_SHOWUSAGE;
   }

   if (!ast_opt_dont_warn) {
      ast_cli(a->fd, "Disclaimer: this command is for informational purposes only.\n"
            "\tIt does not indicate anything about your configuration.\n");
   }

   ast_cli(a->fd, "%8s %-5s %-12s %-16s %s\n","ID","TYPE","NAME","FORMAT","DESCRIPTION");
   ast_cli(a->fd, "------------------------------------------------------------------------------------------------\n");

   ao2_rdlock(codecs);
   i = ao2_iterator_init(codecs, AO2_ITERATOR_DONTLOCK);

   for (; (codec = ao2_iterator_next(&i)); ao2_ref(codec, -1)) {
      if (a->argc == 4) {
         if (!strcasecmp(a->argv[3], "audio")) {
            if (codec->external.type != AST_MEDIA_TYPE_AUDIO) {
               continue;
            }
         } else if (!strcasecmp(a->argv[3], "video")) {
            if (codec->external.type != AST_MEDIA_TYPE_VIDEO) {
               continue;
            }
         } else if (!strcasecmp(a->argv[3], "image")) {
            if (codec->external.type != AST_MEDIA_TYPE_IMAGE) {
               continue;
            }
         } else if (!strcasecmp(a->argv[3], "text")) {
            if (codec->external.type != AST_MEDIA_TYPE_TEXT) {
               continue;
            }
         } else {
            continue;
         }
      }

      ast_cli(a->fd, "%8u %-5s %-12s %-16s (%s)\n",
         codec->external.id,
         ast_codec_media_type2str(codec->external.type),
         codec->external.name,
         S_OR(codec->format_name, "no cached format"),
         codec->external.description);
   }

   ao2_iterator_destroy(&i);
   ao2_unlock(codecs);

   return CLI_SUCCESS;
}

Variable Documentation

codec_cli

struct ast_cli_entry codec_cli[]

static

Initial value:

= {
   { .handler =  show_codecs , .summary =  "Displays a list of registered codecs" ,},
   { .handler =  show_codec , .summary =  "Shows a specific codec" ,},
}

Definition at line 236 of file codec.c.

codec_id

int codec_id = 1

static

Current identifier value for newly registered codec.

Definition at line 45 of file codec.c.

Referenced by __ast_codec_register_with_format(), and ast_codec_get_max().

codecs

struct ao2_container* codecs

static

Registered codecs.

Definition at line 48 of file codec.c.

Referenced by action_originate(), ast_rtp_read(), codec_prefs_to_str(), handle_capabilities_res_message(), and process_sdp().