From: Tilghman Lesher <tilghman@meg.abyt.es>
Date: Wed, 1 Dec 2010 16:59:26 +0000 (+0000)
Subject: Clarify documentation on how we store codec preference lists.
X-Git-Tag: 1.4.39-rc1~3^2~11
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=415e95df9a0d75d4976778d7ed503bcf1ebbb588;p=thirdparty%2Fasterisk.git

Clarify documentation on how we store codec preference lists.

(closes issue #18397)
 Reported by: birgita


git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/1.4@296990 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---

diff --git a/include/asterisk/frame.h b/include/asterisk/frame.h
index 645e4071d9..5ded71fa89 100644
--- a/include/asterisk/frame.h
+++ b/include/asterisk/frame.h
@@ -556,7 +556,15 @@ void ast_parse_allow_disallow(struct ast_codec_pref *pref, int *mask, const char
 /*! \brief Dump audio codec preference list into a string */
 int ast_codec_pref_string(struct ast_codec_pref *pref, char *buf, size_t size);
 
-/*! \brief Shift an audio codec preference list up or down 65 bytes so that it becomes an ASCII string */
+/*! \brief 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.
+ * \param pref A codec preference list structure
+ * \param buf A string denoting codec preference, appropriate for use in line transmission
+ * \param size Size of \a buf
+ * \param right Boolean:  if 0, convert from \a buf to \a pref; if 1, convert from \a pref to \a buf.
+ */
 void ast_codec_pref_convert(struct ast_codec_pref *pref, char *buf, size_t size, int right);
 
 /*! \brief Returns the number of samples contained in the frame */