control.h File Reference

Internal API for the Stasis application controller. More...

#include "asterisk/stasis_app.h"

Include dependency graph for control.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
int	control_add_channel_to_bridge (struct stasis_app_control *control, struct ast_channel *chan, void *data)
	Command callback for adding a channel to a bridge. More...
struct stasis_app *	control_app (struct stasis_app_control *control)
	Returns the pointer (non-reffed) to the app associated with this control. More...
int	control_command_count (struct stasis_app_control *control)
	Returns the count of items in a control's command queue. More...
struct stasis_app_control *	control_create (struct ast_channel *channel, struct stasis_app *app)
	Create a control object. More...
int	control_dispatch_all (struct stasis_app_control *control, struct ast_channel *chan)
	Dispatch all commands enqueued to this control. More...
void	control_flush_queue (struct stasis_app_control *control)
	Flush the control command queue. More...
int	control_is_done (struct stasis_app_control *control)
	Returns true if control_continue() has been called on this control. More...
void	control_mark_done (struct stasis_app_control *control)
void	control_move_cleanup (struct stasis_app_control *control)
	Free any memory that was allocated for switching applications via /channels/{channelId}/move. More...
char *	control_next_app (struct stasis_app_control *control)
	Returns the name of the application we are moving to. More...
char **	control_next_app_args (struct stasis_app_control *control)
	Returns the list of arguments to pass to the application we are moving to. More...
int	control_next_app_args_size (struct stasis_app_control *control)
	Returns the number of arguments to be passed to the application we are moving to. More...
int	control_prestart_dispatch_all (struct stasis_app_control *control, struct ast_channel *chan)
	Dispatch all queued prestart commands. More...
void	control_set_app (struct stasis_app_control *control, struct stasis_app *app)
	Set the application the control object belongs to. More...
void	control_silence_stop_now (struct stasis_app_control *control)
	Stop playing silence to a channel right now. More...
int	control_swap_channel_in_bridge (struct stasis_app_control *control, struct ast_bridge *bridge, struct ast_channel *chan, struct ast_channel *swap)
	Command for swapping a channel in a bridge. More...
void	control_wait (struct stasis_app_control *control)
	Blocks until control's command queue has a command available. More...

Detailed Description

Internal API for the Stasis application controller.

Author

David M. Lee, II dlee@.nosp@m.digi.nosp@m.um.co.nosp@m.m

Since

12

Definition in file control.h.

Function Documentation

control_add_channel_to_bridge()

int control_add_channel_to_bridge	(	struct stasis_app_control *	control,
		struct ast_channel *	chan,
		void *	data
	)

Command callback for adding a channel to a bridge.

Parameters

control	The control for chan
chan	The channel on which commands should be executed
data	Bridge to be passed to the callback

Definition at line 1378 of file control.c.

References control_swap_channel_in_bridge(), and NULL.

Referenced by stasis_app_control_add_channel_to_bridge().

{
   return control_swap_channel_in_bridge(control, data, chan, NULL);
}

control_app()

struct stasis_app* control_app

(

struct stasis_app_control *

control

)

Returns the pointer (non-reffed) to the app associated with this control.

Parameters

control

Control to query.

Returns

A pointer to the associated stasis_app

Definition at line 1563 of file control.c.

References stasis_app_control::app.

Referenced by bridge_stasis_moving(), bridge_stasis_push_peek(), channel_replaced_cb(), channel_stolen_cb(), and stasis_app_exec().

{
   return control->app;
}

control_command_count()

int control_command_count

(

struct stasis_app_control *

control

)

Returns the count of items in a control's command queue.

Parameters

control

Control to count commands on

Return values

number

of commands in the command que

Definition at line 343 of file control.c.

References ao2_container_count(), and stasis_app_control::command_queue.

Referenced by stasis_app_control_execute_until_exhausted().

{
   return ao2_container_count(control->command_queue);
}

control_create()

struct stasis_app_control* control_create	(	struct ast_channel *	channel,
		struct stasis_app *	app
	)

Create a control object.

Parameters

channel	Channel to control.
app	stasis_app for which this control is being created.

Returns

New control object.

NULL on error.

Definition at line 123 of file control.c.

References stasis_app_control::add_rules, ao2_alloc, AO2_ALLOC_OPT_LOCK_MUTEX, ao2_bump, ao2_container_alloc_list, ao2_ref, stasis_app_control::app, ast_channel_ref, ast_cond_init, AST_LIST_HEAD_INIT, ast_log, AST_VECTOR_INIT, stasis_app_control::channel, stasis_app_control::command_queue, control_dtor(), errno, LOG_ERROR, stasis_app_control::next_app, NULL, stasis_app_control::remove_rules, and stasis_app_control::wait_cond.

Referenced by stasis_app_control_create(), and stasis_app_exec().

{
   struct stasis_app_control *control;
   int res;

   control = ao2_alloc(sizeof(*control), control_dtor);
   if (!control) {
      return NULL;
   }

   AST_LIST_HEAD_INIT(&control->add_rules);
   AST_LIST_HEAD_INIT(&control->remove_rules);

   res = ast_cond_init(&control->wait_cond, NULL);
   if (res != 0) {
      ast_log(LOG_ERROR, "Error initializing ast_cond_t: %s\n",
         strerror(errno));
      ao2_ref(control, -1);
      return NULL;
   }

   control->app = ao2_bump(app);

   ast_channel_ref(channel);
   control->channel = channel;

   control->command_queue = ao2_container_alloc_list(
      AO2_ALLOC_OPT_LOCK_MUTEX, 0, NULL, NULL);
   if (!control->command_queue) {
      ao2_ref(control, -1);
      return NULL;
   }

   control->next_app = NULL;
   AST_VECTOR_INIT(&control->next_app_args, 0);

   return control;
}

control_dispatch_all()

int control_dispatch_all	(	struct stasis_app_control *	control,
		struct ast_channel *	chan
	)

Dispatch all commands enqueued to this control.

Parameters

control	Control object to dispatch.
chan	Associated channel.

Returns

Number of commands executed

Definition at line 1495 of file control.c.

References ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, AO2_ITERATOR_UNLINK, ao2_ref, ast_assert, stasis_app_control::channel, command_invoke(), and stasis_app_control::command_queue.

Referenced by stasis_app_control_execute_until_exhausted(), and stasis_app_exec().

{
   int count = 0;
   struct ao2_iterator iter;
   struct stasis_app_command *command;

   ast_assert(control->channel == chan);

   iter = ao2_iterator_init(control->command_queue, AO2_ITERATOR_UNLINK);
   while ((command = ao2_iterator_next(&iter))) {
      command_invoke(command, control, chan);
      ao2_ref(command, -1);
      ++count;
   }
   ao2_iterator_destroy(&iter);

   return count;
}

control_flush_queue()

void control_flush_queue

(

struct stasis_app_control *

control

)

Flush the control command queue.

Since

13.9.0

Parameters

control

Control object to flush command queue.

Returns

Nothing

Definition at line 1482 of file control.c.

References ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, AO2_ITERATOR_UNLINK, ao2_ref, command_complete(), and stasis_app_control::command_queue.

Referenced by stasis_app_control_flush_queue(), and stasis_app_exec().

{
   struct ao2_iterator iter;
   struct stasis_app_command *command;

   iter = ao2_iterator_init(control->command_queue, AO2_ITERATOR_UNLINK);
   while ((command = ao2_iterator_next(&iter))) {
      command_complete(command, -1);
      ao2_ref(command, -1);
   }
   ao2_iterator_destroy(&iter);
}

control_is_done()

int control_is_done

(

struct stasis_app_control *

control

)

Returns true if control_continue() has been called on this control.

Parameters

control

Control to query.

Returns

True (non-zero) if control_continue() has been called.

False (zero) otherwise.

Definition at line 348 of file control.c.

Referenced by stasis_app_control_execute_until_exhausted(), stasis_app_control_is_done(), and stasis_app_exec().

{
   /* Called from stasis_app_exec thread; no lock needed */
   return control->is_done;
}

control_mark_done()

void control_mark_done

(

struct stasis_app_control *

control

)

Definition at line 354 of file control.c.

References ao2_lock, ao2_unlock, and stasis_app_control::command_queue.

Referenced by app_control_continue(), stasis_app_control_execute_until_exhausted(), and stasis_app_exec().

{
   /* Locking necessary to sync with other threads adding commands to the queue. */
   ao2_lock(control->command_queue);
   control->is_done = 1;
   ao2_unlock(control->command_queue);
}

control_move_cleanup()

void control_move_cleanup

(

struct stasis_app_control *

control

)

Free any memory that was allocated for switching applications via /channels/{channelId}/move.

Parameters

control

The control for the channel

Definition at line 1702 of file control.c.

References ast_free, ast_free_ptr(), AST_VECTOR_RESET, stasis_app_control::next_app, and NULL.

Referenced by app_control_move(), control_dtor(), and stasis_app_exec().

{
   ast_free(control->next_app);
   control->next_app = NULL;

   AST_VECTOR_RESET(&control->next_app_args, ast_free_ptr);
}

control_next_app()

char* control_next_app

(

struct stasis_app_control *

control

)

Returns the name of the application we are moving to.

Parameters

control

The control for the channel

Returns

The name of the application we are moving to

Definition at line 1697 of file control.c.

References stasis_app_control::next_app.

Referenced by stasis_app_exec().

{
   return control->next_app;
}

control_next_app_args()

char** control_next_app_args

(

struct stasis_app_control *

control

)

Returns the list of arguments to pass to the application we are moving to.

Note

If you wish to get the size of the list, control_next_app_args_size should be called before this, as this function will steal the elements from the string vector and set the size to 0.

Parameters

control

The control for the channel

Returns

The arguments to pass to the application we are moving to

Definition at line 1710 of file control.c.

References AST_VECTOR_STEAL_ELEMENTS.

Referenced by stasis_app_exec().

{
   return AST_VECTOR_STEAL_ELEMENTS(&control->next_app_args);
}

control_next_app_args_size()

int control_next_app_args_size

(

struct stasis_app_control *

control

)

Returns the number of arguments to be passed to the application we are moving to.

Note

This should always be called before control_next_app_args, as calling that function will steal all elements from the string vector and set the size to 0.

Parameters

control

The control for the channel

Returns

The number of arguments to be passed to the application we are moving to

Definition at line 1715 of file control.c.

References AST_VECTOR_SIZE.

Referenced by stasis_app_exec().

{
   return AST_VECTOR_SIZE(&control->next_app_args);
}

control_prestart_dispatch_all()

int control_prestart_dispatch_all	(	struct stasis_app_control *	control,
		struct ast_channel *	chan
	)

Dispatch all queued prestart commands.

Parameters

control	The control for chan
channel	The channel on which commands should be executed

Returns

The number of commands executed

Definition at line 1535 of file control.c.

References ao2_cleanup, ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, AO2_ITERATOR_UNLINK, ast_channel_lock, ast_channel_unlock, command_invoke(), command_prestart_get_container(), and stasis_app_control::command_queue.

Referenced by stasis_app_exec().

{
   struct ao2_container *command_queue;
   int count = 0;
   struct ao2_iterator iter;
   struct stasis_app_command *command;

   ast_channel_lock(chan);
   command_queue = command_prestart_get_container(chan);
   ast_channel_unlock(chan);
   if (!command_queue) {
      return 0;
   }

   iter = ao2_iterator_init(command_queue, AO2_ITERATOR_UNLINK);

   while ((command = ao2_iterator_next(&iter))) {
      command_invoke(command, control, chan);
      ao2_cleanup(command);
      ++count;
   }

   ao2_iterator_destroy(&iter);
   ao2_cleanup(command_queue);
   return count;
}

control_set_app()

void control_set_app	(	struct stasis_app_control *	control,
		struct stasis_app *	app
	)

Set the application the control object belongs to.

Parameters

control	The control for the channel
app	The application this control will now belong to

Note

This will unref control's previous app by 1, and bump app by 1

Definition at line 1691 of file control.c.

References ao2_bump, ao2_cleanup, and stasis_app_control::app.

Referenced by stasis_app_exec().

{
   ao2_cleanup(control->app);
   control->app = ao2_bump(app);
}

control_silence_stop_now()

void control_silence_stop_now

(

struct stasis_app_control *

control

)

Stop playing silence to a channel right now.

Since

13.9.0

Parameters

control

The control for chan

Definition at line 837 of file control.c.

References ast_channel_stop_silence_generator(), ast_debug, stasis_app_control::channel, NULL, stasis_app_control::silgen, and stasis_app_control_get_channel_id().

Referenced by app_control_silence_stop(), and stasis_app_exec().

{
   if (control->silgen) {
      ast_debug(3, "%s: Stopping silence generator\n",
         stasis_app_control_get_channel_id(control));
      ast_channel_stop_silence_generator(
         control->channel, control->silgen);
      control->silgen = NULL;
   }
}

control_swap_channel_in_bridge()

int control_swap_channel_in_bridge	(	struct stasis_app_control *	control,
		struct ast_bridge *	bridge,
		struct ast_channel *	chan,
		struct ast_channel *	swap
	)

Command for swapping a channel in a bridge.

Parameters

control	The control for chan
chan	The channel on which commands should be executed
bridge	Bridge to be passed to the callback
swap	Channel to swap with when joining the bridge

Definition at line 1284 of file control.c.

References ao2_lock, ao2_unlock, stasis_app_control::app, app_subscribe_bridge(), ast_assert, ast_bridge_depart(), ast_bridge_impart(), AST_BRIDGE_IMPART_CHAN_DEPARTABLE, AST_BRIDGE_IMPART_INHIBIT_JOIN_COLP, ast_bridge_set_after_callback(), ast_channel_lock, ast_channel_pbx(), ast_channel_pbx_set(), ast_channel_unlock, ast_debug, ast_log, stasis_app_control::bridge, bridge_after_cb(), bridge_after_cb_failed(), stasis_app_control::bridge_features, ast_bridge_features::inhibit_colp, LOG_ERROR, NULL, stasis_app_control::pbx, set_interval_hook(), stasis_app_control_get_channel_id(), stasis_app_get_bridge(), and ast_bridge::uniqueid.

Referenced by control_add_channel_to_bridge(), and defer_bridge_add().

{
   int res;
   struct ast_bridge_features *features;
   int flags = AST_BRIDGE_IMPART_CHAN_DEPARTABLE;

   if (!control || !bridge) {
      return -1;
   }

   ast_debug(3, "%s: Adding to bridge %s\n",
      stasis_app_control_get_channel_id(control),
      bridge->uniqueid);

   ast_assert(chan != NULL);

   /* Depart whatever Stasis bridge we're currently in. */
   if (stasis_app_get_bridge(control)) {
      /* Note that it looks like there's a race condition here, since
       * we don't have control locked. But this happens from the
       * control callback thread, so there won't be any other
       * concurrent attempts to bridge.
       */
      ast_bridge_depart(chan);
   }


   res = ast_bridge_set_after_callback(chan, bridge_after_cb,
      bridge_after_cb_failed, control);
   if (res != 0) {
      ast_log(LOG_ERROR, "Error setting after-bridge callback\n");
      return -1;
   }

   ao2_lock(control);

   /* Ensure the controlling application is subscribed early enough
    * to receive the ChannelEnteredBridge message. This works in concert
    * with the subscription handled in the Stasis application execution
    * loop */
   app_subscribe_bridge(control->app, bridge);

   /* Save off the channel's PBX */
   ast_assert(control->pbx == NULL);
   if (!control->pbx) {
      control->pbx = ast_channel_pbx(chan);
      ast_channel_pbx_set(chan, NULL);
   }

   /* Pull bridge features from the control */
   features = control->bridge_features;
   control->bridge_features = NULL;
   if (features && features->inhibit_colp) {
      flags |= AST_BRIDGE_IMPART_INHIBIT_JOIN_COLP;
   }

   ast_assert(stasis_app_get_bridge(control) == NULL);
   /* We need to set control->bridge here since bridge_after_cb may be run
    * before ast_bridge_impart returns.  bridge_after_cb gets a reason
    * code so it can tell if the bridge is actually valid or not.
    */
   control->bridge = bridge;

   /* We can't be holding the control lock while impart is running
    * or we could create a deadlock with bridge_after_cb which also
    * tries to lock control.
    */
   ao2_unlock(control);
   res = ast_bridge_impart(bridge,
      chan,
      swap,
      features, /* features */
      flags);
   if (res != 0) {
      /* ast_bridge_impart failed before it could spawn the depart
       * thread.  The callbacks aren't called in this case.
       * The impart could still fail even if ast_bridge_impart returned
       * ok but that's handled by bridge_after_cb.
       */
      ast_log(LOG_ERROR, "Error adding channel to bridge\n");
      ao2_lock(control);
      ast_channel_pbx_set(chan, control->pbx);
      control->pbx = NULL;
      control->bridge = NULL;
      ao2_unlock(control);
   } else {
      ast_channel_lock(chan);
      set_interval_hook(chan);
      ast_channel_unlock(chan);
   }

   return res;
}

control_wait()

void control_wait

(

struct stasis_app_control *

control

)

Blocks until control's command queue has a command available.

Parameters

control

Control to block on.

Definition at line 1515 of file control.c.

References ao2_container_count(), ao2_lock, ao2_object_get_lockaddr(), ao2_unlock, ast_assert, ast_cond_wait, ast_log, stasis_app_control::command_queue, LOG_ERROR, NULL, and stasis_app_control::wait_cond.

Referenced by stasis_app_exec().

{
   if (!control) {
      return;
   }

   ast_assert(control->command_queue != NULL);

   ao2_lock(control->command_queue);
   while (ao2_container_count(control->command_queue) == 0) {
      int res = ast_cond_wait(&control->wait_cond,
         ao2_object_get_lockaddr(control->command_queue));
      if (res < 0) {
         ast_log(LOG_ERROR, "Error waiting on command queue\n");
         break;
      }
   }
   ao2_unlock(control->command_queue);
}