Merge a large set of updates to the Asterisk indications API.

This patch includes a number of changes to the indications API.  The primary
motivation for this work was to improve stability.  The object management
in this API was significantly flawed, and a number of trivial situations could
cause crashes.

The changes included are:

1) Remove the module res_indications.  This included the critical functionality
   that actually loaded the indications configuration.  I have seen many people
   have Asterisk problems because they accidentally did not have an
   indications.conf present and loaded.  Now, this code is in the core,
   and Asterisk will fail to start without indications configuration.

   There was one part of res_indications, the dialplan applications, which did
   belong in a module, and have been moved to a new module, app_playtones.

2) Object management has been significantly changed.  Tone zones are now
   managed using astobj2, and it is no longer possible to crash Asterisk by
   issuing a reload that destroys tone zones while they are in use.

3) The API documentation has been filled out.

4) The API has been updated to follow our naming conventions.

5) Various bits of code throughout the tree have been updated to account
   for the API update.

6) Configuration parsing has been mostly re-written.

7) "Code cleanup"

The code is from svn/asterisk/team/russell/indications/.

Review: http://reviewboard.digium.com/r/149/


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

1 files changed, 226 insertions, 66 deletions

diff --git a/include/asterisk/indications.h b/include/asterisk/indications.h
index b32fe500e..bf2f323b2 100644
--- a/include/asterisk/indications.h
+++ b/include/asterisk/indications.h
@@ -1,91 +1,251 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
+ * Copyright (C) 2002, Pauline Middelink
+ * Copyright (C) 2009, Digium, Inc.
+ *
  * See http://www.asterisk.org for more information about
  * the Asterisk project. Please do not directly contact
  * any of the maintainers of this project for assistance;
  * the project provides a web site, mailing lists and IRC
  * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
  */
 
-/*! \file
- * \brief BSD Telephony Of Mexico "Tormenta" Tone Zone Support 2/22/01
- * 
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- * 
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- * 
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 
- *
- * Primary Author: Pauline Middelink <middelink@polyware.nl>
+/*!
+ * \file
+ * \brief Tone Indication Support
  *
+ * \author Pauline Middelink <middelink@polyware.nl>
+ * \author Russell Bryant <russell@digium.com>
  */
 
 #ifndef _ASTERISK_INDICATIONS_H
 #define _ASTERISK_INDICATIONS_H
 
-#include "asterisk/lock.h"
-
-/*! \brief 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 tone_zone_sound {
-	const char *name;			/*!< Identifing name */
-	const char *data;			/*!< Actual zone description */
-	AST_LIST_ENTRY(tone_zone_sound) list;
+#include "asterisk/astobj2.h"
+
+/*!
+ * \brief Description of a tone
+ */
+struct ast_tone_zone_sound {
+	/*! \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 frequency (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 {
+			unsigned int killme:1;
+		};
+	};
+};
+
+/*!
+ * \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 {
+	/*! \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 {
+			unsigned int killme:1;
+		};
+	};
 };
 
-struct tone_zone {
-	AST_RWLIST_ENTRY(tone_zone) list;
-	char country[5];				/*!< Country code */
-	char alias[5];					/*!< is this an alias? */
-	char description[40];				/*!< Description */
-	int  nrringcadence;				/*!< # registered ringcadence elements */
-	int *ringcadence;				/*!< Ring cadence */
-	AST_LIST_HEAD_NOLOCK(, tone_zone_sound) tones;		/*!< The known tones for this zone */
+/*!
+ * \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 set the default tone country */
-int ast_set_indication_country(const char *country);
-
-/*! \brief locate tone_zone, given the country. if country == NULL, use the default country */
-struct tone_zone *ast_get_indication_zone(const char *country);
-/*! \brief locate a tone_zone_sound, given the tone_zone. if tone_zone == NULL, use the default tone_zone */
-struct tone_zone_sound *ast_get_indication_tone(const struct tone_zone *zone, const char *indication);
-/*! \brief deallocate the passed tone zone */
-void ast_destroy_indication_zone(struct tone_zone *zone);
-
-/*! \brief add a new country, if country exists, it will be replaced. */
-int ast_register_indication_country(struct tone_zone *country);
-/*! \brief remove an existing country and all its indications, country must exist */
-int ast_unregister_indication_country(const char *country);
-/*! \brief add a new indication to a tone_zone. tone_zone must exist. if the indication already
- * exists, it will be replaced. */
-int ast_register_indication(struct tone_zone *zone, const char *indication, const char *tonelist);
-/*! \brief remove an existing tone_zone's indication. tone_zone must exist */
-int ast_unregister_indication(struct 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 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 country country to find.  If NULL is provided, get the default.
+ *
+ * \return a reference 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 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 reference 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 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 support for walking through a list of indications */
-struct tone_zone *ast_walk_indications(const struct tone_zone *cur);
+/*!
+ * \brief Get the number of registered tone zones
+ *
+ * \return the total number of registered tone zones
+ */
+int ast_tone_zone_count(void);
+
+/*!
+ * \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);
+
+extern struct ast_tone_zone __fake_tone_zone;
+extern struct ast_tone_zone_sound __fake_tone_zone_sound;
+
+#define AST_CHECK_TONE_ZONE(tz) do { \
+	(void) ((tz) == (&__fake_tone_zone)); \
+} while (0)
+
+#define AST_CHECK_TONE_ZONE_SOUND(ts) do { \
+	(void) ((ts) == (&__fake_tone_zone_sound)); \
+} while (0)
+
+/*!
+ * \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)
 
-#if 0
-extern struct tone_zone *tone_zones;
-extern ast_mutex_t tzlock;
-#endif
+/*!
+ * \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) ({  \
+	AST_CHECK_TONE_ZONE(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) ({ \
+	AST_CHECK_TONE_ZONE(tz); \
+	ao2_ref(tz, +1); \
+	(tz); \
+})
+
+/*!
+ * \brief Release a reference to an ast_tone_zone_sound
+ *
+ * \return NULL
+ */
+#define ast_tone_zone_sound_unref(ts) ({ \
+	AST_CHECK_TONE_ZONE_SOUND(ts); \
+	ao2_ref(ts, -1); \
+	(NULL); \
+})
+
+/*!
+ * \brief Increase the reference count on an ast_tone_zone_sound
+ *
+ * \return The tone zone sound provided as an argument
+ */
+#define ast_tone_zone_sound_ref(ts) ({ \
+	AST_CHECK_TONE_ZONE_SOUND(ts); \
+	ao2_ref(ts, +1); \
+	(ts); \
+})
 
 #endif /* _ASTERISK_INDICATIONS_H */