From 1f57cd4e5150eb916b30f5183deb3449a0d6795d Mon Sep 17 00:00:00 2001
From: russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b>
Date: Tue, 17 Feb 2009 20:41:24 +0000
Subject: 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: http://svn.digium.com/svn/asterisk/trunk@176627 f38db490-d61c-443f-a65b-d21fe96a405b
---
 apps/app_playtones.c | 129 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 apps/app_playtones.c

(limited to 'apps/app_playtones.c')

diff --git a/apps/app_playtones.c b/apps/app_playtones.c
new file mode 100644
index 000000000..6aff16860
--- /dev/null
+++ b/apps/app_playtones.c
@@ -0,0 +1,129 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2009, Digium, Inc.
+ *
+ * Russell Bryant <russell@digium.com>
+ *
+ * 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 Playtones application
+ *
+ * \author Russell Bryant <russell@digium.com>
+ *
+ * \ingroup applications
+ */
+
+#include "asterisk.h"
+
+ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
+
+#include "asterisk/module.h"
+#include "asterisk/pbx.h"
+#include "asterisk/channel.h"
+#include "asterisk/indications.h"
+
+static const char playtones_app[] = "PlayTones";
+static const char stopplaytones_app[] = "StopPlayTones";
+
+/*** DOCUMENTATION
+	<application name="PlayTones" language="en_US">
+		<synopsis>
+			Play a tone list.
+		</synopsis>
+		<syntax>
+			<parameter name="arg" required="true">
+				<para>Arg is either the tone name defined in the <filename>indications.conf</filename>
+				configuration file, or a directly specified list of frequencies and durations.</para>
+			</parameter>
+		</syntax>
+		<description>
+			<para>Plays a tone list. Execution will continue with the next step in the dialplan
+			immediately while the tones continue to play.</para>
+			<para>See the sample <filename>indications.conf</filename> for a description of the
+			specification of a tonelist.</para>
+		</description>
+		<see-also>
+			<ref type="application">StopPlayTones</ref>
+		</see-also>
+	</application>
+	<application name="StopPlayTones" language="en_US">
+		<synopsis>
+			Stop playing a tone list.
+		</synopsis>
+		<syntax />
+		<description>
+			<para>Stop playing a tone list, initiated by PlayTones().</para>
+		</description>
+		<see-also>
+			<ref type="application">PlayTones</ref>
+		</see-also>
+	</application>
+ ***/
+
+static int handle_playtones(struct ast_channel *chan, void *data)
+{
+	struct ast_tone_zone_sound *ts;
+	int res;
+	const char *str = data;
+
+	if (ast_strlen_zero(str)) {
+		ast_log(LOG_NOTICE,"Nothing to play\n");
+		return -1;
+	}
+
+	ts = ast_get_indication_tone(chan->zone, str);
+
+	if (ts) {
+		res = ast_playtones_start(chan, 0, ts->data, 0);
+		ts = ast_tone_zone_sound_unref(ts);
+	} else {
+		res = ast_playtones_start(chan, 0, str, 0);
+	}
+
+	if (res) {
+		ast_log(LOG_NOTICE, "Unable to start playtones\n");
+	}
+
+	return res;
+}
+
+static int handle_stopplaytones(struct ast_channel *chan, void *data)
+{
+	ast_playtones_stop(chan);
+
+	return 0;
+}
+
+static int unload_module(void)
+{
+	int res;
+
+	res = ast_unregister_application(playtones_app);
+	res |= ast_unregister_application(stopplaytones_app);
+
+	return res;
+}
+
+static int load_module(void)
+{
+	int res;
+
+	res = ast_register_application_xml(playtones_app, handle_playtones);
+	res |= ast_register_application_xml(stopplaytones_app, handle_stopplaytones);
+
+	return res ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS;
+}
+
+AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Playtones Application");
-- 
cgit v1.2.3