codec_pref.h File Reference

Media Format Bitfield Compatibility API. More...

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

Go to the source code of this file.

Data Structures
struct	iax2_codec_pref

Macros
#define	IAX2_CODEC_PREF_SIZE   64

Functions
void	iax2_codec_pref_append (struct iax2_codec_pref *pref, struct ast_format *format, unsigned int framing)
	Append a audio codec to a preference list, removing it first if it was already there. More...
int	iax2_codec_pref_best_bitfield2cap (uint64_t bitfield, struct iax2_codec_pref *prefs, struct ast_format_cap *cap)
	Convert a bitfield to a format capabilities structure in the "best" order. More...
void	iax2_codec_pref_convert (struct iax2_codec_pref *pref, char *buf, size_t size, int right)
	Shift an audio codec preference list up or down 65 bytes so that it becomes an ASCII string. More...
int	iax2_codec_pref_format_bitfield_to_order_value (uint64_t bitfield)
	Convert a format bitfield into an iax2_codec_pref order value. More...
uint64_t	iax2_codec_pref_from_bitfield (struct iax2_codec_pref *pref, uint64_t bitfield)
	Create codec preference list from the given bitfield formats. More...
struct ast_format *	iax2_codec_pref_index (struct iax2_codec_pref *pref, int index, struct ast_format **result)
	Codec located at a particular place in the preference index. More...
uint64_t	iax2_codec_pref_order_value_to_format_bitfield (int order_value)
	Convert an iax2_codec_pref order value into a format bitfield. More...
void	iax2_codec_pref_prepend (struct iax2_codec_pref *pref, struct ast_format *format, unsigned int framing, int only_if_existing)
	Prepend an audio codec to a preference list, removing it first if it was already there. More...
void	iax2_codec_pref_remove_missing (struct iax2_codec_pref *pref, uint64_t bitfield)
	Removes format from the pref list that aren't in the bitfield. More...
int	iax2_codec_pref_string (struct iax2_codec_pref *pref, char *buf, size_t size)
	Dump audio codec preference list into a string. More...
int	iax2_codec_pref_to_cap (struct iax2_codec_pref *pref, struct ast_format_cap *cap)
	Convert a preference structure to a capabilities structure. More...

Detailed Description

Media Format Bitfield Compatibility API.

Author

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

Definition in file codec_pref.h.

Macro Definition Documentation

IAX2_CODEC_PREF_SIZE

#define IAX2_CODEC_PREF_SIZE   64

Definition at line 33 of file codec_pref.h.

Function Documentation

iax2_codec_pref_append()

void iax2_codec_pref_append	(	struct iax2_codec_pref *	pref,
		struct ast_format *	format,
		unsigned int	framing
	)

Append a audio codec to a preference list, removing it first if it was already there.

Definition at line 422 of file codec_pref.c.

References ast_format_compatibility_format2bitfield(), and iax2_codec_pref_append_bitfield().

Referenced by iax2_parse_allow_disallow().

{
   uint64_t bitfield;

   bitfield = ast_format_compatibility_format2bitfield(format);
   if (!bitfield) {
      return;
   }

   iax2_codec_pref_append_bitfield(pref, bitfield, framing);
}

iax2_codec_pref_best_bitfield2cap()

int iax2_codec_pref_best_bitfield2cap	(	uint64_t	bitfield,
		struct iax2_codec_pref *	prefs,
		struct ast_format_cap *	cap
	)

Convert a bitfield to a format capabilities structure in the "best" order.

Parameters

bitfield	The bitfield for the media formats
prefs	Format preference order to use as a guide. (May be NULL)
cap	Capabilities structure to place formats into

Return values

0	on success.
-1	on error.

Note

If failure occurs the capabilities structure may contain a partial set of formats

Definition at line 112 of file codec_pref.c.

References ARRAY_LEN, ast_assert, ast_format_cap_append, ast_format_compatibility_bitfield2format(), format, iax2_codec_pref::framing, iax2_codec_pref_order_value_to_format_bitfield(), iax2_format_compatibility_best(), NULL, and iax2_codec_pref::order.

Referenced by ast_iax2_new(), and socket_process_helper().

{
   uint64_t best_bitfield;
   struct ast_format *format;

   /* Add any user preferred codecs first. */
   if (prefs) {
      int idx;

      for (idx = 0; bitfield && idx < ARRAY_LEN(prefs->order); ++idx) {
         best_bitfield = iax2_codec_pref_order_value_to_format_bitfield(prefs->order[idx]);
         if (!best_bitfield) {
            break;
         }

         if (best_bitfield & bitfield) {
            format = ast_format_compatibility_bitfield2format(best_bitfield);
            if (format && ast_format_cap_append(cap, format, prefs->framing[idx])) {
               return -1;
            }

            /* Remove just added codec. */
            bitfield &= ~best_bitfield;
         }
      }
   }

   /* Add the hard coded "best" codecs. */
   while (bitfield) {
      best_bitfield = iax2_format_compatibility_best(bitfield);
      if (!best_bitfield) {
         /* No more codecs considered best. */
         break;
      }

      format = ast_format_compatibility_bitfield2format(best_bitfield);
      /* The best_bitfield should always be convertible to a format. */
      ast_assert(format != NULL);

      if (ast_format_cap_append(cap, format, 0)) {
         return -1;
      }

      /* Remove just added "best" codec to find the next "best". */
      bitfield &= ~best_bitfield;
   }

   /* Add any remaining codecs. */
   if (bitfield) {
      int bit;

      for (bit = 0; bit < 64; ++bit) {
         uint64_t mask = (1ULL << bit);

         if (mask & bitfield) {
            format = ast_format_compatibility_bitfield2format(mask);
            if (format && ast_format_cap_append(cap, format, 0)) {
               return -1;
            }
         }
      }
   }

   return 0;
}

iax2_codec_pref_convert()

void iax2_codec_pref_convert	(	struct iax2_codec_pref *	pref,
		char *	buf,
		size_t	size,
		int	right
	)

Shift an audio codec preference list up or down 65 bytes so that it becomes an ASCII string.

Note

Due to a misunderstanding in how codec preferences are stored, this list starts at 'B', not 'A'. For backwards compatibility reasons, this cannot change.

Parameters

pref	A codec preference list structure
buf	A string denoting codec preference, appropriate for use in line transmission
size	Size of buf
right	Boolean: if 0, convert from buf to pref; if 1, convert from pref to buf.

Definition at line 44 of file codec_pref.c.

References ARRAY_LEN, iax2_codec_pref::framing, and iax2_codec_pref::order.

Referenced by check_access(), dump_prefs(), iax2_call(), and socket_process_helper().

{
   static int differential = (int) 'A';
   int x;

   if (right) {
      --size;/* Save room for the nul string terminator. */
      for (x = 0; x < ARRAY_LEN(pref->order) && x < size; ++x) {
         if (!pref->order[x]) {
            break;
         }

         buf[x] = pref->order[x] + differential;
      }

      buf[x] = '\0';
   } else {
      for (x = 0; x < ARRAY_LEN(pref->order) && x < size; ++x) {
         if (buf[x] == '\0') {
            break;
         }

         pref->order[x] = buf[x] - differential;
         pref->framing[x] = 0;
      }

      if (x < ARRAY_LEN(pref->order)) {
         pref->order[x] = 0;
         pref->framing[x] = 0;
      }
   }
}

iax2_codec_pref_format_bitfield_to_order_value()

int iax2_codec_pref_format_bitfield_to_order_value

(

uint64_t

bitfield

)

Convert a format bitfield into an iax2_codec_pref order value.

Parameters

bitfield

value being converted

Returns

the iax2_codec_pref order value of the most significant format in the bitfield.

Note

This is really meant to be used on single format bitfields. It will work with multiformat bitfields, but it can only return the index of the most significant one if that is the case.

Definition at line 376 of file codec_pref.c.

References ARRAY_LEN, and iax2_supported_formats.

Referenced by iax2_codec_pref_append_bitfield(), and iax2_codec_pref_prepend().

{
   int idx;

   if (bitfield) {
      for (idx = 0; idx < ARRAY_LEN(iax2_supported_formats); ++idx) {
         if (iax2_supported_formats[idx] == bitfield) {
            return idx + 1;
         }
      }
   }
   return 0;
}

iax2_codec_pref_from_bitfield()

uint64_t iax2_codec_pref_from_bitfield	(	struct iax2_codec_pref *	pref,
		uint64_t	bitfield
	)

Create codec preference list from the given bitfield formats.

Since

13.0.0

Parameters

pref	Codec preference list to setup from the given bitfield.
bitfield	Format bitfield to guide preference list creation.

Returns

Updated bitfield with any bits not mapped to a format cleared.

Definition at line 483 of file codec_pref.c.

References ast_assert, ast_format_compatibility_bitfield2format(), format, iax2_codec_pref_append_bitfield(), iax2_format_compatibility_best(), and NULL.

Referenced by set_config().

{
   int bit;
   uint64_t working_bitfield;
   uint64_t best_bitfield;
   struct ast_format *format;

   /* Init the preference list. */
   memset(pref, 0, sizeof(*pref));

   working_bitfield = bitfield;

   /* Add the "best" codecs first. */
   while (working_bitfield) {
      best_bitfield = iax2_format_compatibility_best(working_bitfield);
      if (!best_bitfield) {
         /* No more codecs considered best. */
         break;
      }

      /* Remove current "best" codec to find the next "best". */
      working_bitfield &= ~best_bitfield;

      format = ast_format_compatibility_bitfield2format(best_bitfield);
      /* The best_bitfield should always be convertible to a format. */
      ast_assert(format != NULL);

      iax2_codec_pref_append_bitfield(pref, best_bitfield, 0);
   }

   /* Add any remaining codecs. */
   if (working_bitfield) {
      for (bit = 0; bit < 64; ++bit) {
         uint64_t mask = (1ULL << bit);

         if (mask & working_bitfield) {
            format = ast_format_compatibility_bitfield2format(mask);
            if (!format) {
               /* The bit is not associated with any format. */
               bitfield &= ~mask;
               continue;
            }

            iax2_codec_pref_append_bitfield(pref, mask, 0);
         }
      }
   }

   return bitfield;
}

iax2_codec_pref_index()

struct ast_format* iax2_codec_pref_index	(	struct iax2_codec_pref *	pref,
		int	index,
		struct ast_format **	result
	)

Codec located at a particular place in the preference index.

Parameters

pref	preference structure to get the codec out of
index	to retrieve from
result	ast_format structure to store the index value in

Returns

pointer to input ast_format on success, NULL on failure

Definition at line 77 of file codec_pref.c.

References ARRAY_LEN, ast_format_compatibility_bitfield2format(), iax2_codec_pref_order_value_to_format_bitfield(), NULL, iax2_codec_pref::order, and result.

Referenced by function_iaxpeer(), and socket_process_helper().

{
   if (0 <= idx && idx < ARRAY_LEN(pref->order) && pref->order[idx]) {
      uint64_t pref_bitfield;

      pref_bitfield = iax2_codec_pref_order_value_to_format_bitfield(pref->order[idx]);
      *result = ast_format_compatibility_bitfield2format(pref_bitfield);
   } else {
      *result = NULL;
   }

   return *result;
}

iax2_codec_pref_order_value_to_format_bitfield()

uint64_t iax2_codec_pref_order_value_to_format_bitfield

(

int

order_value

)

Convert an iax2_codec_pref order value into a format bitfield.

Parameters

order_value

value being converted

Returns

the bitfield value of the order_value format

Definition at line 367 of file codec_pref.c.

References ARRAY_LEN, and iax2_supported_formats.

Referenced by codec_choose_from_prefs(), iax2_codec_pref_best_bitfield2cap(), iax2_codec_pref_index(), iax2_codec_pref_remove_missing(), and iax2_codec_pref_to_cap().

{
   if (order_value < 1 || ARRAY_LEN(iax2_supported_formats) < order_value) {
      return 0;
   }

   return iax2_supported_formats[order_value - 1];
}

iax2_codec_pref_prepend()

void iax2_codec_pref_prepend	(	struct iax2_codec_pref *	pref,
		struct ast_format *	format,
		unsigned int	framing,
		int	only_if_existing
	)

Prepend an audio codec to a preference list, removing it first if it was already there.

Definition at line 434 of file codec_pref.c.

References ARRAY_LEN, ast_assert, ast_format_compatibility_format2bitfield(), iax2_codec_pref::framing, iax2_codec_pref_format_bitfield_to_order_value(), and iax2_codec_pref::order.

Referenced by create_addr().

{
   uint64_t bitfield;
   int format_index;
   int x;

   bitfield = ast_format_compatibility_format2bitfield(format);
   if (!bitfield) {
      return;
   }
   format_index = iax2_codec_pref_format_bitfield_to_order_value(bitfield);
   if (!format_index) {
      return;
   }

   /* Now find any existing occurrence, or the end */
   for (x = 0; x < ARRAY_LEN(pref->order); ++x) {
      if (!pref->order[x] || pref->order[x] == format_index)
         break;
   }

   /*
    * The array can never be full without format_index
    * also being in the array.
    */
   ast_assert(x < ARRAY_LEN(pref->order));

   /* If we failed to find any occurrence, set to the end for safety. */
   if (ARRAY_LEN(pref->order) <= x) {
      x = ARRAY_LEN(pref->order) - 1;
   }

   if (only_if_existing && !pref->order[x]) {
      return;
   }

   /* Move down to make space to insert - either all the way to the end,
      or as far as the existing location (which will be overwritten) */
   for (; x > 0; --x) {
      pref->order[x] = pref->order[x - 1];
      pref->framing[x] = pref->framing[x - 1];
   }

   /* And insert the new entry */
   pref->order[0] = format_index;
   pref->framing[0] = framing;
}

iax2_codec_pref_remove_missing()

void iax2_codec_pref_remove_missing	(	struct iax2_codec_pref *	pref,
		uint64_t	bitfield
	)

Removes format from the pref list that aren't in the bitfield.

Definition at line 288 of file codec_pref.c.

References ARRAY_LEN, codec_pref_remove_index(), iax2_codec_pref_order_value_to_format_bitfield(), and iax2_codec_pref::order.

Referenced by iax2_parse_allow_disallow().

{
   int idx;

   if (!pref->order[0]) {
      return;
   }

   /*
    * Work from the end of the list so we always deal with
    * unmodified entries in case we have to remove a pref.
    */
   for (idx = ARRAY_LEN(pref->order); idx--;) {
      uint64_t pref_bitfield;

      pref_bitfield = iax2_codec_pref_order_value_to_format_bitfield(pref->order[idx]);
      if (!pref_bitfield) {
         continue;
      }

      /* If this format isn't in the bitfield, remove it from the prefs. */
      if (!(pref_bitfield & bitfield)) {
         codec_pref_remove_index(pref, idx);
      }
   }
}

iax2_codec_pref_string()

int iax2_codec_pref_string	(	struct iax2_codec_pref *	pref,
		char *	buf,
		size_t	size
	)

Dump audio codec preference list into a string.

Parameters

pref	preference structure to dump string representation of order for
buf	character buffer to put string into
size	size of the character buffer

Returns

-1 on error. Otherwise returns the remaining spaaaaaace in the buffer.

Note

Format is (codec1|codec2|codec3|...) – if the list is too long for the size of the buffer, codecs will be written until they exceed the length remaining in which case the list will be closed with '...)' after the last writable codec.

Definition at line 178 of file codec_pref.c.

References ao2_cleanup, ao2_ref, ast_format_cap_alloc, ast_format_cap_count(), AST_FORMAT_CAP_FLAG_DEFAULT, ast_format_cap_get_format(), ast_format_get_name(), iax2_codec_pref_to_cap(), and name.

Referenced by dump_prefs(), handle_cli_iax2_show_peer(), and socket_process_helper().

{
   int x;
   struct ast_format_cap *cap;
   size_t total_len;
   char *cur;

   /* This function is useless if you have less than a 6 character buffer.
    * '(...)' is six characters. */
   if (size < 6) {
      return -1;
   }

   /* Convert the preferences into a format cap so that we can read the format names */
   cap = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
   if (!cap || iax2_codec_pref_to_cap(pref, cap)) {
      strcpy(buf, "(...)"); /* Safe */
      ao2_cleanup(cap);
      return -1;
   }

   /* We know that at a minimum, 3 characters are used - (, ), and \0 */
   total_len = size - 3;

   /* This character has already been accounted for total_len purposes */
   buf[0] = '(';
   cur = buf + 1;

   /* Loop through the formats and write as many into the buffer as we can */
   for (x = 0; x < ast_format_cap_count(cap); x++) {
      size_t name_len;
      struct ast_format *fmt = ast_format_cap_get_format(cap, x);
      const char *name = ast_format_get_name(fmt);

      name_len = strlen(name);

      /* all entries after the first need a delimiter character */
      if (x) {
         name_len++;
      }

      /* Terminate the list early if we don't have room for the entry.
       * If it's not the last entry in the list, save enough room to write '...'.
       */
      if (((x == ast_format_cap_count(cap) - 1) && (total_len < name_len)) ||
            ((x < ast_format_cap_count(cap) - 1) && (total_len < name_len + 3))) {
         strcpy(cur, "...");
         cur += 3;
         total_len -= 3;
         ao2_ref(fmt, -1);
         break;
      }

      sprintf(cur, "%s%s", x ? "|" : "", name);
      cur += name_len;
      total_len -= name_len;

      ao2_ref(fmt, -1);
   }
   ao2_ref(cap, -1);

   /* These two characters have already been accounted for total_len purposes */
   cur[0] = ')';
   cur[1] = '\0';

   return size - total_len;
}

iax2_codec_pref_to_cap()

int iax2_codec_pref_to_cap	(	struct iax2_codec_pref *	pref,
		struct ast_format_cap *	cap
	)

Convert a preference structure to a capabilities structure.

Parameters

pref	Formats in preference order to build the capabilities.
cap	Capabilities structure to place formats into

Return values

0	on success.
-1	on error.

Note

If failure occurs the capabilities structure may contain a partial set of formats

Definition at line 91 of file codec_pref.c.

References ARRAY_LEN, ast_format_cap_append, ast_format_compatibility_bitfield2format(), iax2_codec_pref::framing, iax2_codec_pref_order_value_to_format_bitfield(), and iax2_codec_pref::order.

Referenced by iax2_codec_pref_string(), and iax2_parse_allow_disallow().

{
   int idx;

   for (idx = 0; idx < ARRAY_LEN(pref->order); ++idx) {
      uint64_t pref_bitfield;
      struct ast_format *pref_format;

      pref_bitfield = iax2_codec_pref_order_value_to_format_bitfield(pref->order[idx]);
      if (!pref_bitfield) {
         break;
      }

      pref_format = ast_format_compatibility_bitfield2format(pref_bitfield);
      if (pref_format && ast_format_cap_append(cap, pref_format, pref->framing[idx])) {
         return -1;
      }
   }
   return 0;
}