codec.h File Reference

Codec API. More...

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

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_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...

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

codec

to register

Return values

0	success
-1	failure

Definition at line 122 of file codec.h.

Referenced by AST_TEST_DEFINE(), and load_module().

Enumeration Type Documentation

ast_media_type

enum 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.

                    {
   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,
};

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

int ast_codec_builtin_init

(

void

)

Initialize built-in codecs within the core.

Return values

0	success
-1	failure

Definition at line 942 of file codec_builtin.c.

References CODEC_REGISTER_AND_CACHE, and CODEC_REGISTER_AND_CACHE_NAMED.

Referenced by asterisk_daemon().

{
   int res = 0;

   res |= CODEC_REGISTER_AND_CACHE(codec2);
   res |= CODEC_REGISTER_AND_CACHE(g723);
   res |= CODEC_REGISTER_AND_CACHE(ulaw);
   res |= CODEC_REGISTER_AND_CACHE(alaw);
   res |= CODEC_REGISTER_AND_CACHE(gsm);
   res |= CODEC_REGISTER_AND_CACHE(g726rfc3551);
   res |= CODEC_REGISTER_AND_CACHE(g726aal2);
   res |= CODEC_REGISTER_AND_CACHE(adpcm);
   res |= CODEC_REGISTER_AND_CACHE(slin8);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("slin12", slin12);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("slin16", slin16);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("slin24", slin24);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("slin32", slin32);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("slin44", slin44);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("slin48", slin48);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("slin96", slin96);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("slin192", slin192);
   res |= CODEC_REGISTER_AND_CACHE(lpc10);
   res |= CODEC_REGISTER_AND_CACHE(g729a);
   res |= CODEC_REGISTER_AND_CACHE(speex8);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("speex16", speex16);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("speex32", speex32);
   res |= CODEC_REGISTER_AND_CACHE(ilbc);
   res |= CODEC_REGISTER_AND_CACHE(g722);
   res |= CODEC_REGISTER_AND_CACHE(siren7);
   res |= CODEC_REGISTER_AND_CACHE(siren14);
   res |= CODEC_REGISTER_AND_CACHE(testlaw);
   res |= CODEC_REGISTER_AND_CACHE(g719);
   res |= CODEC_REGISTER_AND_CACHE(opus);
   res |= CODEC_REGISTER_AND_CACHE(jpeg);
   res |= CODEC_REGISTER_AND_CACHE(png);
   res |= CODEC_REGISTER_AND_CACHE(h261);
   res |= CODEC_REGISTER_AND_CACHE(h263);
   res |= CODEC_REGISTER_AND_CACHE(h263p);
   res |= CODEC_REGISTER_AND_CACHE(h264);
   res |= CODEC_REGISTER_AND_CACHE(h265);
   res |= CODEC_REGISTER_AND_CACHE(mpeg4);
   res |= CODEC_REGISTER_AND_CACHE(vp8);
   res |= CODEC_REGISTER_AND_CACHE(vp9);
   res |= CODEC_REGISTER_AND_CACHE(t140red);
   res |= CODEC_REGISTER_AND_CACHE(t140);
   res |= CODEC_REGISTER_AND_CACHE(t38);
   res |= CODEC_REGISTER_AND_CACHE(none);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("silk8", silk8);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("silk12", silk12);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("silk16", silk16);
   res |= CODEC_REGISTER_AND_CACHE_NAMED("silk24", silk24);

   return res;
}

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;
   }
}