[asterisk-commits] russell: branch russell/indications r174706 - in /team/russell/indications: c...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Tue Feb 10 13:46:54 CST 2009
Author: russell
Date: Tue Feb 10 13:46:54 2009
New Revision: 174706
URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=174706
Log:
API docs
Modified:
team/russell/indications/configs/indications.conf.sample
team/russell/indications/include/asterisk/indications.h
team/russell/indications/main/indications.c
Modified: team/russell/indications/configs/indications.conf.sample
URL: http://svn.digium.com/svn-view/asterisk/team/russell/indications/configs/indications.conf.sample?view=diff&rev=174706&r1=174705&r2=174706
==============================================================================
--- team/russell/indications/configs/indications.conf.sample (original)
+++ team/russell/indications/configs/indications.conf.sample Tue Feb 10 13:46:54 2009
@@ -1,6 +1,9 @@
+;
; indications.conf
+;
; Configuration file for location specific tone indications
-; used by the pbx_indications module.
+;
+
;
; NOTE:
; When adding countries to this file, please keep them in alphabetical
@@ -9,7 +12,7 @@
; The [general] category is for certain global variables.
; All other categories are interpreted as location specific indications
;
-;
+
[general]
country=us ; default location
@@ -52,8 +55,6 @@
; concisely:
; element = [!]freq[+|*freq2][/duration]
; tonelist = element[,element]*
-;
-; Please note that SPACES ARE NOT ALLOWED in tone lists!
;
[at]
Modified: team/russell/indications/include/asterisk/indications.h
URL: http://svn.digium.com/svn-view/asterisk/team/russell/indications/include/asterisk/indications.h?view=diff&rev=174706&r1=174705&r2=174706
==============================================================================
--- team/russell/indications/include/asterisk/indications.h (original)
+++ team/russell/indications/include/asterisk/indications.h Tue Feb 10 13:46:54 2009
@@ -30,17 +30,28 @@
/*!
* \brief Description of a tone
- *
- * Description is a series of tones of the format:
- * [!]freq1[+freq2][/duration] separated by commas. There
- * are no spaces. The sequence is repeated back to the
- * first tone description not preceeded by !. Duration is
- * specified in milliseconds
*/
struct ast_tone_zone_sound {
- const char *name; /*!< Identifying name */
- const char *data; /*!< Actual zone description */
+ /*! \brief Name of the tone. For example, "busy". */
+ const char *name;
+ /*!
+ * \brief Description of a tone
+ *
+ * The format is a comma separated list of tone parts in the following format:
+ *
+ * Format: [!][M]freq[<+|*>freq2][/duration]
+ * - '!' - means that the element is NOT repeated
+ * - 'M' - interpret the frequencies as midi notes instead of frequencies
+ * - freq - The first frequency
+ * - freq2 - The second freency (optional)
+ * - '*' - modulate freq by freq2 at a fixed depth of 90%
+ * - '+' - combine the frequencies
+ * - duration - the length of the tone part (optional, forever if not specified)
+ */
+ const char *data;
+ /*! \brief Linked list fields for including in the list on an ast_tone_zone */
AST_LIST_ENTRY(ast_tone_zone_sound) entry;
+ /*! \brief Flags only used internally */
union {
uint32_t __padding;
struct {
@@ -49,12 +60,35 @@
};
};
+/*!
+ * \brief A set of tones for a given locale
+ *
+ * \note If a reference to this tone zone is held, then the country
+ * is guaranteed not to change. It is safe to read it without
+ * locking the tone zone. This is not the case for any other
+ * field.
+ */
struct ast_tone_zone {
- char country[5]; /*!< Country code */
- char description[40]; /*!< Description */
- int nrringcadence; /*!< # registered ringcadence elements */
- int *ringcadence; /*!< Ring cadence */
- AST_LIST_HEAD_NOLOCK(, ast_tone_zone_sound) tones; /*!< The known tones for this zone */
+ /*! \brief Country code that this set of tones is for */
+ char country[5];
+ /*!
+ * \brief Text description of the given country.
+ *
+ * This is for nothing more than friendly display to a human.
+ */
+ char description[40];
+ /*! \brief Number of ring cadence elements in the ringcadence array */
+ unsigned int nrringcadence;
+ /*!
+ * \brief Array of ring cadence parts
+ *
+ * Each element is an amount of time in milliseconds. The first element
+ * is for time on, and from there it alternates between on and off.
+ */
+ int *ringcadence;
+ /*! \brief A list of tones for this locale */
+ AST_LIST_HEAD_NOLOCK(, ast_tone_zone_sound) tones;
+ /*! \brief Flags only used internally */
union {
uint32_t __padding;
struct {
@@ -64,27 +98,106 @@
};
/*!
+ * \brief A description of a part of a tone
+ *
+ * The elements in this structure map to the format described for the data
+ * part of the ast_tone_zone_sound struct.
+ */
+struct ast_tone_zone_part {
+ unsigned int freq1;
+ unsigned int freq2;
+ unsigned int time;
+ unsigned int modulate:1;
+ unsigned int midinote:1;
+};
+
+/*!
+ * \brief Parse a tone part
+ *
+ * \param s The part of a tone to parse. This should be in the form described for
+ * the data part of ast_tone_zone_sound. '!' should be removed if present.
+ * \param tone_data An output parameter that contains the result of the parsing.
+ *
+ * \retval 0 success
+ * \retval -1 failure, and the contents of tone_data are undefined
+ */
+int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data);
+
+/*!
* \brief locate ast_tone_zone
*
- * \param county country to find, if== NULL, get the default country
+ * \param county country to find. If NULL is provided, get the default.
+ *
+ * \return a pointer to the specified country if found or NULL if not found
*/
struct ast_tone_zone *ast_get_indication_zone(const char *country);
-/*! \brief locate a ast_tone_zone_sound, given the ast_tone_zone. if ast_tone_zone == NULL, use the default ast_tone_zone */
+/*!
+ * \brief Locate a tone zone sound
+ *
+ * \param zone Zone to look in for a sound, if NULL, the default will be used
+ * \param indication Sound to look for, such as "busy"
+ *
+ * \return a pointer to the specified sound if it exists, NULL if not
+ */
struct ast_tone_zone_sound *ast_get_indication_tone(const struct ast_tone_zone *zone, const char *indication);
-/*! \brief Start a tone-list going */
-int ast_playtones_start(struct ast_channel *chan, int vol, const char* tonelist, int interruptible);
-
-/*! \brief Stop the tones from playing */
+/*!
+ * \brief Start playing a list of tones on a channel
+ *
+ * \param chan the channel to play tones on
+ * \param vol volume
+ * \param tonelist the list of tones to play, comma separated
+ * \param interruptible whether or not this tone can be interrupted
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
+int ast_playtones_start(struct ast_channel *chan, int vol, const char *tonelist, int interruptible);
+
+/*!
+ * \brief Stop playing tones on a channel
+ *
+ * \param chan the channel to stop tones on
+ */
void ast_playtones_stop(struct ast_channel *chan);
+/*!
+ * \brief Get an iterator for the available tone zones
+ *
+ * Use ao2_iterator_next() to iterate the tone zones.
+ *
+ * \return an initialized iterator
+ */
struct ao2_iterator ast_tone_zone_iterator_init(void);
+/*!
+ * \brief Lock an ast_tone_zone
+ */
#define ast_tone_zone_lock(tz) ao2_lock(tz)
+
+/*!
+ * \brief Unlock an ast_tone_zone
+ */
#define ast_tone_zone_unlock(tz) ao2_unlock(tz)
+
+/*!
+ * \brief Trylock an ast_tone_zone
+ */
#define ast_tone_zone_trylock(tz) ao2_trylock(tz)
+
+/*!
+ * \brief Release a reference to an ast_tone_zone
+ *
+ * \return NULL
+ */
#define ast_tone_zone_unref(tz) ({ ao2_ref(tz, -1); (NULL); })
+
+/*!
+ * \brief Increase the reference count on an ast_tone_zone
+ *
+ * \return The tone zone provided as an argument
+ */
#define ast_tone_zone_ref(tz) ({ ao2_ref(tz, +1); (tz); })
#endif /* _ASTERISK_INDICATIONS_H */
Modified: team/russell/indications/main/indications.c
URL: http://svn.digium.com/svn-view/asterisk/team/russell/indications/main/indications.c?view=diff&rev=174706&r1=174705&r2=174706
==============================================================================
--- team/russell/indications/main/indications.c (original)
+++ team/russell/indications/main/indications.c Tue Feb 10 13:46:54 2009
@@ -21,13 +21,6 @@
*
* \author Pauline Middelink <middelink at polyware.nl>
* \author Russell Bryant <russell at digium.com>
- */
-
-/*
- * XXX TODO
- * - API documentation
- * - change the code such that tone definitions are only parsed once
- * instead of every time they are used.
*/
#include "asterisk.h"
@@ -111,14 +104,6 @@
*/
static struct ast_tone_zone *default_tone_zone;
-struct ast_tone_zone_part {
- unsigned int freq1;
- unsigned int freq2;
- unsigned int time;
- unsigned int modulate:1;
- unsigned int midinote:1;
-};
-
struct playtones_item {
int fac1;
int init_v2_1;
@@ -291,7 +276,7 @@
.generate = playtones_generator,
};
-static int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data)
+int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data)
{
if (sscanf(s, "%u+%u/%u", &tone_data->freq1, &tone_data->freq2,
&tone_data->time) == 3) {
@@ -490,7 +475,6 @@
return ao2_find(ast_tone_zones, &zone_arg, OBJ_POINTER);
}
-/* locate a ast_tone_zone_sound, given the ast_tone_zone. if ast_tone_zone == NULL, use the default ast_tone_zone */
struct ast_tone_zone_sound *ast_get_indication_tone(const struct ast_tone_zone *_zone, const char *indication)
{
struct ast_tone_zone_sound *ts = NULL;
More information about the asterisk-commits
mailing list