stasis_app_impl.h File Reference

Backend API for implementing components of res_stasis. More...

#include "asterisk/stasis_app.h"

Include dependency graph for stasis_app_impl.h:

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

Go to the source code of this file.

Typedefs
typedef void(*	command_data_destructor_fn) (void *data)
	Typedef for data destructor for stasis app commands. More...
typedef int(*	stasis_app_command_cb) (struct stasis_app_control *control, struct ast_channel *chan, void *data)

Functions
int	stasis_app_exec (struct ast_channel *chan, const char *app_name, int argc, char *argv[])
	Control a channel using stasis_app. More...
int	stasis_app_send_command (struct stasis_app_control *control, stasis_app_command_cb command, void *data, command_data_destructor_fn data_destructor)
	Invokes a command on a control's channel. More...
int	stasis_app_send_command_async (struct stasis_app_control *control, stasis_app_command_cb command, void *data, command_data_destructor_fn data_destructor)
	Asynchronous version of stasis_app_send_command(). More...

Detailed Description

Backend API for implementing components of res_stasis.

Author

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

Since

12

This file defines functions useful for defining new commands to execute on channels while they are in Stasis.

Definition in file stasis_app_impl.h.

Typedef Documentation

command_data_destructor_fn

typedef void(* command_data_destructor_fn) (void *data)

Typedef for data destructor for stasis app commands.

Parameters

data	Data to destroy.

This is called during destruction of the command or if we fail to schedule a command. It is passed a pointer to the user-defined data of the command.

Returns

Nothing

Definition at line 62 of file stasis_app_impl.h.

stasis_app_command_cb

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

Callback type for stasis app commands

Definition at line 65 of file stasis_app_impl.h.

Function Documentation

stasis_app_exec()

int stasis_app_exec	(	struct ast_channel *	chan,
		const char *	app_name,
		int	argc,
		char *	argv[]
	)

Control a channel using stasis_app.

Since

12 This function blocks until the channel hangs up, or stasis_app_control_continue() is called on the channel's stasis_app_control struct.

Parameters

chan	Channel to control with Stasis.
app_name	Application controlling the channel.
argc	Number of arguments for the application.
argv	Arguments for the application.

/brief Stasis dialplan application callback

Definition at line 1324 of file res_stasis.c.

References add_masquerade_store(), ao2_bump, ao2_cleanup, ao2_find, ao2_link, ao2_ref, app, app_is_active(), app_send(), app_send_end_msg(), app_subscribe_bridge(), app_unsubscribe_bridge(), ast_assert, ast_bridge_depart(), ast_channel_clear_softhangup(), ast_channel_fdno(), ast_channel_internal_bridge_channel(), ast_channel_lock, ast_channel_name(), ast_channel_pbx(), ast_channel_snapshot_get_latest(), ast_channel_snapshot_to_json(), ast_channel_uniqueid(), ast_channel_unlock, ast_check_hangup(), ast_check_hangup_locked(), AST_CONTROL_HANGUP, ast_debug, AST_FRAME_CONTROL, ast_frame_dtor(), ast_free, ast_json_array_append(), ast_json_object_get(), ast_json_pack(), ast_json_string_create(), ast_json_timeval(), ast_json_unref(), ast_log, ast_pbx_run_args(), ast_read(), AST_SOFTHANGUP_ASYNCGOTO, ast_tvnow(), ast_waitfor(), cleanup(), control_app(), control_create(), control_dispatch_all(), control_flush_queue(), control_is_done(), control_mark_done(), control_move_cleanup(), control_next_app(), control_next_app_args(), control_next_app_args_size(), control_prestart_dispatch_all(), control_set_app(), control_silence_stop_now(), control_unlink(), control_wait(), has_masquerade_store(), LOG_ERROR, MAX_WAIT_MS, ast_pbx_args::no_hangup_chan, NULL, OBJ_SEARCH_KEY, RAII_VAR, remove_masquerade_store(), remove_stasis_end_published(), send_start_msg(), stasis_app_channel_is_stasis_end_published(), stasis_app_get_bridge(), and stasis_app_name().

Referenced by app_exec().

{
   RAII_VAR(struct stasis_app *, app, NULL, ao2_cleanup);
   RAII_VAR(struct stasis_app_control *, control, NULL, control_unlink);
   struct ast_bridge *bridge = NULL;
   int res = 0;
   int needs_depart;

   ast_assert(chan != NULL);

   /* Just in case there's a lingering indication that the channel has had a stasis
    * end published on it, remove that now.
    */
   remove_stasis_end_published(chan);

   if (!apps_registry) {
      return -1;
   }

   app = ao2_find(apps_registry, app_name, OBJ_SEARCH_KEY);
   if (!app) {
      ast_log(LOG_ERROR,
         "Stasis app '%s' not registered\n", app_name);
      return -1;
   }
   if (!app_is_active(app)) {
      ast_log(LOG_ERROR,
         "Stasis app '%s' not active\n", app_name);
      return -1;
   }

   control = control_create(chan, app);
   if (!control) {
      ast_log(LOG_ERROR, "Control allocation failed or Stasis app '%s' not registered\n", app_name);
      return -1;
   }

   if (!control_app(control)) {
      ast_log(LOG_ERROR, "Stasis app '%s' not registered\n", app_name);
      return -1;
   }

   if (!app_is_active(control_app(control))) {
      ast_log(LOG_ERROR, "Stasis app '%s' not active\n", app_name);
      return -1;
   }
   ao2_link(app_controls, control);

   if (add_masquerade_store(chan)) {
      ast_log(LOG_ERROR, "Failed to attach masquerade detector\n");
      return -1;
   }

   res = send_start_msg(control_app(control), chan, argc, argv);
   if (res != 0) {
      ast_log(LOG_ERROR,
         "Error sending start message to '%s'\n", app_name);
      remove_masquerade_store(chan);
      return -1;
   }

   /* Pull queued prestart commands and execute */
   control_prestart_dispatch_all(control, chan);

   while (!control_is_done(control)) {
      RAII_VAR(struct ast_frame *, f, NULL, ast_frame_dtor);
      int r;
      int command_count;
      RAII_VAR(struct ast_bridge *, last_bridge, NULL, ao2_cleanup);

      /* Check to see if a bridge absorbed our hangup frame */
      if (ast_check_hangup_locked(chan)) {
         control_mark_done(control);
         break;
      }

      /* control->next_app is only modified within the control thread, so this is safe */
      if (control_next_app(control)) {
         struct stasis_app *next_app = ao2_find(apps_registry, control_next_app(control), OBJ_SEARCH_KEY);

         if (next_app && app_is_active(next_app)) {
            int idx;
            int next_argc;
            char **next_argv;

            /* If something goes wrong in this conditional, res will need to be non-zero
             * so that the code below the exec loop knows something went wrong during a move.
             */
            if (!stasis_app_channel_is_stasis_end_published(chan)) {
               res = has_masquerade_store(chan) && app_send_end_msg(control_app(control), chan);
               if (res != 0) {
                  ast_log(LOG_ERROR,
                     "Error sending end message to %s\n", stasis_app_name(control_app(control)));
                  control_mark_done(control);
                  ao2_ref(next_app, -1);
                  break;
               }
            } else {
               remove_stasis_end_published(chan);
            }

            /* This will ao2_bump next_app, and unref the previous app by 1 */
            control_set_app(control, next_app);

            /* There's a chance that the previous application is ready for clean up, so go ahead
             * and do that now.
             */
            cleanup();

            /* We need to add another masquerade store, otherwise the leave message will
             * not show up for the correct application.
             */
            if (add_masquerade_store(chan)) {
               ast_log(LOG_ERROR, "Failed to attach masquerade detector\n");
               res = -1;
               control_mark_done(control);
               ao2_ref(next_app, -1);
               break;
            }

            /* We MUST get the size before the list, as control_next_app_args steals the elements
             * from the string vector.
             */
            next_argc = control_next_app_args_size(control);
            next_argv = control_next_app_args(control);

            res = send_start_msg(control_app(control), chan, next_argc, next_argv);

            /* Even if res != 0, we still need to free the memory we got from control_argv */
            if (next_argv) {
               for (idx = 0; idx < next_argc; idx++) {
                  ast_free(next_argv[idx]);
               }
               ast_free(next_argv);
            }

            if (res != 0) {
               ast_log(LOG_ERROR,
                  "Error sending start message to '%s'\n", stasis_app_name(control_app(control)));
               remove_masquerade_store(chan);
               control_mark_done(control);
               ao2_ref(next_app, -1);
               break;
            }

            /* Done switching applications, free memory and clean up */
            control_move_cleanup(control);
         } else {
            /* If we can't switch applications, do nothing */
            struct ast_json *msg;
            RAII_VAR(struct ast_channel_snapshot *, snapshot, NULL, ao2_cleanup);

            if (!next_app) {
               ast_log(LOG_ERROR, "Could not move to Stasis app '%s' - not registered\n",
                  control_next_app(control));
            } else {
               ast_log(LOG_ERROR, "Could not move to Stasis app '%s' - not active\n",
                  control_next_app(control));
            }

            snapshot = ast_channel_snapshot_get_latest(ast_channel_uniqueid(chan));
            if (!snapshot) {
               ast_log(LOG_ERROR, "Could not get channel shapshot for '%s'\n",
                  ast_channel_name(chan));
            } else {
               struct ast_json *json_args;
               int next_argc = control_next_app_args_size(control);
               char **next_argv = control_next_app_args(control);

               msg = ast_json_pack("{s: s, s: o, s: o, s: s, s: []}",
                  "type", "ApplicationMoveFailed",
                  "timestamp", ast_json_timeval(ast_tvnow(), NULL),
                  "channel", ast_channel_snapshot_to_json(snapshot, NULL),
                  "destination", control_next_app(control),
                  "args");
               if (!msg) {
                  ast_log(LOG_ERROR, "Failed to pack JSON for ApplicationMoveFailed message\n");
               } else {
                  json_args = ast_json_object_get(msg, "args");
                  if (!json_args) {
                     ast_log(LOG_ERROR, "Could not get args json array");
                  } else {
                     int r = 0;
                     int idx;
                     for (idx = 0; idx < next_argc; ++idx) {
                        r = ast_json_array_append(json_args,
                           ast_json_string_create(next_argv[idx]));
                        if (r != 0) {
                           ast_log(LOG_ERROR, "Error appending to ApplicationMoveFailed message\n");
                           break;
                        }
                     }
                     if (r == 0) {
                        app_send(control_app(control), msg);
                     }
                  }
                  ast_json_unref(msg);
               }
            }
         }
         control_move_cleanup(control);
         ao2_cleanup(next_app);
      }

      last_bridge = bridge;
      bridge = ao2_bump(stasis_app_get_bridge(control));

      if (bridge != last_bridge) {
         if (last_bridge) {
            app_unsubscribe_bridge(control_app(control), last_bridge);
         }
         if (bridge) {
            app_subscribe_bridge(control_app(control), bridge);
         }
      }

      if (bridge) {
         /* Bridge/dial is handling channel frames */
         control_wait(control);
         control_dispatch_all(control, chan);
         continue;
      }

      r = ast_waitfor(chan, MAX_WAIT_MS);

      if (r < 0) {
         ast_debug(3, "%s: Poll error\n",
              ast_channel_uniqueid(chan));
         control_mark_done(control);
         break;
      }

      command_count = control_dispatch_all(control, chan);

      if (command_count > 0 && ast_channel_fdno(chan) == -1) {
         /* Command drained the channel; wait for next frame */
         continue;
      }

      if (r == 0) {
         /* Timeout */
         continue;
      }

      f = ast_read(chan);
      if (!f) {
         /* Continue on in the dialplan */
         ast_debug(3, "%s: Hangup (no more frames)\n",
            ast_channel_uniqueid(chan));
         control_mark_done(control);
         break;
      }

      if (f->frametype == AST_FRAME_CONTROL) {
         if (f->subclass.integer == AST_CONTROL_HANGUP) {
            /* Continue on in the dialplan */
            ast_debug(3, "%s: Hangup\n",
               ast_channel_uniqueid(chan));
            control_mark_done(control);
            break;
         }
      }
   }

   ast_channel_lock(chan);
   needs_depart = (ast_channel_internal_bridge_channel(chan) != NULL);
   ast_channel_unlock(chan);
   if (needs_depart) {
      ast_bridge_depart(chan);
   }

   if (stasis_app_get_bridge(control)) {
      app_unsubscribe_bridge(control_app(control), stasis_app_get_bridge(control));
   }
   ao2_cleanup(bridge);

   /* Only publish a stasis_end event if it hasn't already been published */
   if (!res && !stasis_app_channel_is_stasis_end_published(chan)) {
      /* A masquerade has occurred and this message will be wrong so it
       * has already been sent elsewhere. */
      res = has_masquerade_store(chan) && app_send_end_msg(control_app(control), chan);
      if (res != 0) {
         ast_log(LOG_ERROR,
            "Error sending end message to %s\n", stasis_app_name(control_app(control)));
         return res;
      }
   } else {
      remove_stasis_end_published(chan);
   }

   control_flush_queue(control);

   /* Stop any lingering silence generator */
   control_silence_stop_now(control);

   /* There's an off chance that app is ready for cleanup. Go ahead
    * and clean up, just in case
    */
   cleanup();

   /* The control needs to be removed from the controls container in
    * case a new PBX is started and ends up coming back into Stasis.
    */
   control_unlink(control);
   control = NULL;

   if (!res && !ast_channel_pbx(chan)) {
      int chan_hungup;

      /* The ASYNCGOTO softhangup flag may have broken the channel out of
       * its bridge to run dialplan, so if there's no pbx on the channel
       * let it run dialplan here. Otherwise, it will run when this
       * application exits. */
      ast_channel_lock(chan);
      ast_channel_clear_softhangup(chan, AST_SOFTHANGUP_ASYNCGOTO);
      chan_hungup = ast_check_hangup(chan);
      ast_channel_unlock(chan);

      if (!chan_hungup) {
         struct ast_pbx_args pbx_args;

         memset(&pbx_args, 0, sizeof(pbx_args));
         pbx_args.no_hangup_chan = 1;

         res = ast_pbx_run_args(chan, &pbx_args);
      }
   }

   return res;
}

stasis_app_send_command()

int stasis_app_send_command	(	struct stasis_app_control *	control,
		stasis_app_command_cb	command,
		void *	data,
		command_data_destructor_fn	data_destructor
	)

Invokes a command on a control's channel.

Since

12 This function dispatches the command to be executed in the context of stasis_app_exec(), so this command will block waiting for the results of the command.

Parameters

control	Control object for the channel to send the command to.
command	Command function to execute.
data	Optional data to pass along with the control function.
data_destructor	Optional function which will be called on the data in either the event of command completion or failure to schedule or complete the command

Returns

zero on success.

error code otherwise.

Definition at line 898 of file control.c.

References app_send_command_on_condition(), and NULL.

Referenced by ast_ari_bridges_set_video_source(), and stasis_app_control_answer().

{
   return app_send_command_on_condition(control, command_fn, data, data_destructor, NULL);
}

stasis_app_send_command_async()

int stasis_app_send_command_async	(	struct stasis_app_control *	control,
		stasis_app_command_cb	command,
		void *	data,
		command_data_destructor_fn	data_destructor
	)

Asynchronous version of stasis_app_send_command().

Since

12 This function enqueues a command for execution, but returns immediately without waiting for the response.

Parameters

control	Control object for the channel to send the command to.
command	Command function to execute.
data	Optional data to pass along with the control function.
data_destructor	Optional function which will be called on the data in either the event of command completion or failure to schedule or complete the command

Returns

0 on success.

Non-zero on error.

Definition at line 904 of file control.c.

References ao2_ref, stasis_app_command::data_destructor, exec_command(), and NULL.

Referenced by bridge_timeout(), dial_bridge_after_cb(), internal_bridge_after_cb(), stasis_app_control_add_role(), stasis_app_control_clear_roles(), stasis_app_control_continue(), stasis_app_control_dial(), stasis_app_control_dtmf(), stasis_app_control_hold(), stasis_app_control_moh_start(), stasis_app_control_moh_stop(), stasis_app_control_move(), stasis_app_control_mute(), stasis_app_control_play_uri(), stasis_app_control_record(), stasis_app_control_redirect(), stasis_app_control_ring(), stasis_app_control_ring_stop(), stasis_app_control_set_channel_var(), stasis_app_control_silence_start(), stasis_app_control_silence_stop(), stasis_app_control_unhold(), and stasis_app_control_unmute().

{
   struct stasis_app_command *command;

   if (control == NULL || control->is_done) {
      /* If exec_command fails, it calls the data_destructor. In order to
       * provide consistent behavior, we'll also call the data_destructor
       * on this error path. This way, callers never have to call the
       * data_destructor themselves.
       */
      if (data_destructor) {
         data_destructor(data);
      }
      return -1;
   }

   command = exec_command(control, command_fn, data, data_destructor);
   if (!command) {
      return -1;
   }
   ao2_ref(command, -1);

   return 0;
}