Resolve issues in ConfBridge regarding marked, waitmarked, and unmarked users

Thank's to Neil Tallim (flan)'s tireless testing, issue reporting, and patches
it became clear that app_confbridge had some complex logic in how it handled
interactions between marked, waitmarked, and unmarked users.  In particular,
there were some areas in which the interactions between the users resulted
in inconsistent behavior, and app_confbridge was missing logic in how to handle
some corner cases.  Some areas included:
 * Poor handling of mixing unmarked and waitmarked users
 * Inconsistencies in how MOH and muting was applied to various users
 * Handling of various announcements for different user profile options
flan's patches seem to fix the various issues, but highlighted how hard the
code could be to maintain.  In an attempt to make things easier to maintain and
to more fully enumerate the various cases that exist, this patch breaks up the
logic into a state machine-like setup.

Please note that the various state transitioned are documented on the Asterisk
wiki:

https://wiki.asterisk.org/wiki/display/AST/Confbridge+state+changes

Review: //https://reviewboard.asterisk.org/r/2072/

Note that for the following issues, mjordan uploaded the patch, although it
was written by twilson.  Any contributor license discrepency is due to that.

(closes issue ASTERISK-19562)
Reported by: flan
Tested by: flan, mjordan, jrose
patches:
  bugASTERISK-19562_ASTERISK-19726_ASTERISK-20181.patch uploaded by twilson (license 6283)

(closes issue ASTERISK-19726)
Reported by: flan
Tested by: flan
patches:
  bugASTERISK-19562_ASTERISK-19726_ASTERISK-20181.patch uploaded by twilson (license 6283)

(closes issue ASTERISK-20181)
Reported by: Jonathan White
Tested by: Jonathan White
patches:
  bugASTERISK-19562_ASTERISK-19726_ASTERISK-20181.patch uploaded by twilson (license 6283)
........

Merged revisions 374652 from http://svn.asterisk.org/svn/asterisk/branches/10
........

Merged revisions 374657 from http://svn.asterisk.org/svn/asterisk/branches/11


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

1 files changed, 95 insertions, 0 deletions

diff --git a/apps/confbridge/include/conf_state.h b/apps/confbridge/include/conf_state.h
new file mode 100644
index 000000000..8a2585095
--- /dev/null
+++ b/apps/confbridge/include/conf_state.h
@@ -0,0 +1,95 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2012, Terry Wilson
+ *
+ * Terry Wilson <twilson@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.
+ *
+ * Please follow coding guidelines
+ * http://svn.digium.com/view/asterisk/trunk/doc/CODING-GUIDELINES
+ */
+
+/*! \file
+ *
+ * \brief Confbridge state handling
+ *
+ * \author\verbatim Terry Wilson <twilson@digium.com> \endverbatim
+ *
+ * See https://wiki.asterisk.org/wiki/display/AST/Confbridge+state+changes for
+ * a more complete description of how conference states work.
+ */
+
+/*** MODULEINFO
+	<support_level>core</support_level>
+ ***/
+
+#ifndef _CONF_STATE_H_
+#define _CONF_STATE_H_
+
+struct conference_state;
+struct conference_bridge;
+struct conference_bridge_user;
+
+typedef void (*conference_event_fn)(struct conference_bridge_user *cbu);
+typedef void (*conference_entry_fn)(struct conference_bridge_user *cbu);
+typedef void (*conference_exit_fn)(struct conference_bridge_user *cbu);
+
+/*! \brief A conference state object to hold the various state callback functions */
+struct conference_state {
+	const char *name;
+	conference_event_fn join_unmarked;    /*!< Handle an unmarked join event */
+	conference_event_fn join_waitmarked;  /*!< Handle a waitmarked join event */
+	conference_event_fn join_marked;      /*!< Handle a marked join event */
+	conference_event_fn leave_unmarked;   /*!< Handle an unmarked leave event */
+	conference_event_fn leave_waitmarked; /*!< Handle a waitmarked leave event */
+	conference_event_fn leave_marked;     /*!< Handle a marked leave event */
+	conference_entry_fn entry;            /*!< Function to handle entry to a state */
+	conference_exit_fn exit;              /*!< Function to handle exiting from a state */
+};
+
+/*! \brief Conference state with no active or waiting users */
+extern struct conference_state *CONF_STATE_EMPTY;
+
+/*! \brief Conference state with only waiting users */
+extern struct conference_state *CONF_STATE_INACTIVE;
+
+/*! \brief Conference state with only a single unmarked active user */
+extern struct conference_state *CONF_STATE_SINGLE;
+
+/*! \brief Conference state with only a single marked active user */
+extern struct conference_state *CONF_STATE_SINGLE_MARKED;
+
+/*! \brief Conference state with multiple active users, but no marked users */
+extern struct conference_state *CONF_STATE_MULTI;
+
+/*! \brief Conference state with multiple active users and at least one marked user */
+extern struct conference_state *CONF_STATE_MULTI_MARKED;
+
+/*! \brief Execute conference state transition because of a user action
+ * \param cbu The user that joined/left
+ * \param newstate The state to transition to
+ */
+void conf_change_state(struct conference_bridge_user *cbu, struct conference_state *newstate);
+
+/* Common event handlers shared between different states */
+
+/*! \brief Logic to execute every time a waitmarked user joins an unmarked conference */
+void conf_default_join_waitmarked(struct conference_bridge_user *cbu);
+
+/*! \brief Logic to execute every time a waitmarked user leaves an unmarked conference */
+void conf_default_leave_waitmarked(struct conference_bridge_user *cbu);
+
+/*! \brief A handler for join/leave events that are invalid in a particular state */
+void conf_invalid_event_fn(struct conference_bridge_user *cbu);
+
+#endif