stasis_app_playback.h File Reference

Stasis Application Playback API. See StasisApplication API" for detailed documentation. More...

#include "asterisk/stasis_app.h"

Include dependency graph for stasis_app_playback.h:

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

Go to the source code of this file.

Enumerations
enum	stasis_app_playback_media_operation {   STASIS_PLAYBACK_STOP, STASIS_PLAYBACK_RESTART, STASIS_PLAYBACK_PAUSE, STASIS_PLAYBACK_UNPAUSE,   STASIS_PLAYBACK_REVERSE, STASIS_PLAYBACK_FORWARD, STASIS_PLAYBACK_MEDIA_OP_MAX }
enum	stasis_app_playback_state {   STASIS_PLAYBACK_STATE_QUEUED, STASIS_PLAYBACK_STATE_PLAYING, STASIS_PLAYBACK_STATE_PAUSED, STASIS_PLAYBACK_STATE_CONTINUING,   STASIS_PLAYBACK_STATE_COMPLETE, STASIS_PLAYBACK_STATE_CANCELED, STASIS_PLAYBACK_STATE_STOPPED, STASIS_PLAYBACK_STATE_MAX }
enum	stasis_app_playback_target_type { STASIS_PLAYBACK_TARGET_CHANNEL = 0, STASIS_PLAYBACK_TARGET_BRIDGE }
enum	stasis_playback_oper_results { STASIS_PLAYBACK_OPER_OK, STASIS_PLAYBACK_OPER_FAILED, STASIS_PLAYBACK_OPER_NOT_PLAYING }

Functions
struct stasis_app_playback *	stasis_app_control_play_uri (struct stasis_app_control *control, const char **media, size_t media_count, const char *language, const char *target_id, enum stasis_app_playback_target_type target_type, int skipms, long offsetms, const char *id)
	Play a file to the control's channel. More...
struct stasis_app_playback *	stasis_app_playback_find_by_id (const char *id)
	Finds the playback object with the given id. More...
const char *	stasis_app_playback_get_id (struct stasis_app_playback *playback)
	Gets the unique id of a playback object. More...
enum stasis_app_playback_state	stasis_app_playback_get_state (struct stasis_app_playback *playback)
	Gets the current state of a playback operation. More...
enum stasis_playback_oper_results	stasis_app_playback_operation (struct stasis_app_playback *playback, enum stasis_app_playback_media_operation operation)
	Controls the media for a given playback operation. More...
struct stasis_message_type *	stasis_app_playback_snapshot_type (void)
	Message type for playback updates. The data is an ast_channel_blob. More...
struct ast_json *	stasis_app_playback_to_json (const struct stasis_app_playback *playback)
	Convert a playback to its JSON representation. More...

Detailed Description

Stasis Application Playback API. See StasisApplication API" for detailed documentation.

Author

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

Since

12

Definition in file stasis_app_playback.h.

Enumeration Type Documentation

stasis_app_playback_media_operation

enum stasis_app_playback_media_operation

Valid operation for controlling a playback.

Enumerator
STASIS_PLAYBACK_STOP	Stop the playback operation.
STASIS_PLAYBACK_RESTART	Restart the media from the beginning.
STASIS_PLAYBACK_PAUSE	Pause playback.
STASIS_PLAYBACK_UNPAUSE	Resume paused playback.
STASIS_PLAYBACK_REVERSE	Rewind playback.
STASIS_PLAYBACK_FORWARD	Fast forward playback.
STASIS_PLAYBACK_MEDIA_OP_MAX	Enum end sentinel.

Definition at line 57 of file stasis_app_playback.h.

                                         {
   /*! Stop the playback operation. */
   STASIS_PLAYBACK_STOP,
   /*! Restart the media from the beginning. */
   STASIS_PLAYBACK_RESTART,
   /*! Pause playback. */
   STASIS_PLAYBACK_PAUSE,
   /*! Resume paused playback. */
   STASIS_PLAYBACK_UNPAUSE,
   /*! Rewind playback. */
   STASIS_PLAYBACK_REVERSE,
   /*! Fast forward playback. */
   STASIS_PLAYBACK_FORWARD,
   /*! Enum end sentinel. */
   STASIS_PLAYBACK_MEDIA_OP_MAX,
};

stasis_app_playback_state

enum stasis_app_playback_state

State of a playback operation

Enumerator
STASIS_PLAYBACK_STATE_QUEUED	The playback has not started yet
STASIS_PLAYBACK_STATE_PLAYING	The media is currently playing
STASIS_PLAYBACK_STATE_PAUSED	The media is currently playing
STASIS_PLAYBACK_STATE_CONTINUING	The media is transitioning to the next in the list
STASIS_PLAYBACK_STATE_COMPLETE	The media has stopped playing
STASIS_PLAYBACK_STATE_CANCELED	The playback was canceled.
STASIS_PLAYBACK_STATE_STOPPED	The playback was stopped.
STASIS_PLAYBACK_STATE_MAX	Enum end sentinel.

Definition at line 37 of file stasis_app_playback.h.

                               {
   /*! The playback has not started yet */
   STASIS_PLAYBACK_STATE_QUEUED,
   /*! The media is currently playing */
   STASIS_PLAYBACK_STATE_PLAYING,
   /*! The media is currently playing */
   STASIS_PLAYBACK_STATE_PAUSED,
   /*! The media is transitioning to the next in the list */
   STASIS_PLAYBACK_STATE_CONTINUING,
   /*! The media has stopped playing */
   STASIS_PLAYBACK_STATE_COMPLETE,
   /*! The playback was canceled. */
   STASIS_PLAYBACK_STATE_CANCELED,
   /*! The playback was stopped. */
   STASIS_PLAYBACK_STATE_STOPPED,
   /*! Enum end sentinel. */
   STASIS_PLAYBACK_STATE_MAX,
};

stasis_app_playback_target_type

enum stasis_app_playback_target_type

Enumerator
STASIS_PLAYBACK_TARGET_CHANNEL	The target is a channel
STASIS_PLAYBACK_TARGET_BRIDGE	The target is a bridge

Definition at line 74 of file stasis_app_playback.h.

                                     {
   /*! The target is a channel */
   STASIS_PLAYBACK_TARGET_CHANNEL = 0,
   /*! The target is a bridge */
   STASIS_PLAYBACK_TARGET_BRIDGE,
};

stasis_playback_oper_results

enum stasis_playback_oper_results

Enumerator
STASIS_PLAYBACK_OPER_OK
STASIS_PLAYBACK_OPER_FAILED
STASIS_PLAYBACK_OPER_NOT_PLAYING

Definition at line 145 of file stasis_app_playback.h.

                                  {
   STASIS_PLAYBACK_OPER_OK,
   STASIS_PLAYBACK_OPER_FAILED,
   STASIS_PLAYBACK_OPER_NOT_PLAYING,
};

Function Documentation

stasis_app_control_play_uri()

struct stasis_app_playback* stasis_app_control_play_uri	(	struct stasis_app_control *	control,
		const char **	media,
		size_t	media_count,
		const char *	language,
		const char *	target_id,
		enum stasis_app_playback_target_type	target_type,
		int	skipms,
		long	offsetms,
		const char *	id
	)

Play a file to the control's channel.

Note that the file isn't the full path to the file. Asterisk's internal playback mechanism will automagically select the best format based on the available codecs for the channel.

Parameters

control	Control for res_stasis.
media	Array of const char * media files to play.
media_count	The number of media files in media.
language	Selects the file based on language.
target_id	ID of the target bridge or channel.
target_type	What the target type is
skipms	Number of milliseconds to skip for forward/reverse operations.
offsetms	Number of milliseconds to skip before playing.
id	ID to assign the new playback or NULL for default.

Returns

Playback control object.

NULL on error.

Definition at line 471 of file res_stasis_playback.c.

References ao2_bump, ao2_link, ao2_ref, ast_debug, ast_free, ast_log, ast_malloc, ast_string_field_set, ast_strlen_zero, AST_VECTOR_APPEND, AST_VECTOR_GET, LOG_ERROR, NULL, play_uri(), playback_create(), PLAYBACK_DEFAULT_SKIPMS, playback_publish(), remove_from_playbacks(), set_target_uri(), skipms, stasis_app_control_get_channel_id(), stasis_app_send_command_async(), and STASIS_PLAYBACK_STATE_QUEUED.

Referenced by ari_bridges_play_helper(), and ari_channels_handle_play().

{
   struct stasis_app_playback *playback;
   size_t i;

   if (skipms < 0 || offsetms < 0 || media_count == 0) {
      return NULL;
   }

   playback = playback_create(control, id);
   if (!playback) {
      return NULL;
   }

   for (i = 0; i < media_count; i++) {
      char *media_uri;

      if (ast_strlen_zero(media[i])) {
         ast_log(LOG_ERROR, "Attempted to play media on channel '%s' but no media URI was provided.\n",
            stasis_app_control_get_channel_id(control));
         ao2_ref(playback, -1);
         return NULL;
      }

      media_uri = ast_malloc(strlen(media[i]) + 1);
      if (!media_uri) {
         ao2_ref(playback, -1);
         return NULL;
      }

      ast_debug(3, "%s: Sending play(%s) command\n",
         stasis_app_control_get_channel_id(control), media[i]);

       /* safe */
      strcpy(media_uri, media[i]);
      if (AST_VECTOR_APPEND(&playback->medias, media_uri)) {
         ao2_ref(playback, -1);
         ast_free(media_uri);
         return NULL;
      }
   }

   if (skipms == 0) {
      skipms = PLAYBACK_DEFAULT_SKIPMS;
   }

   ast_string_field_set(playback, media, AST_VECTOR_GET(&playback->medias, 0));
   ast_string_field_set(playback, language, language);
   set_target_uri(playback, target_type, target_id);
   playback->skipms = skipms;
   playback->offsetms = offsetms;
   ao2_link(playbacks, playback);

   playback->state = STASIS_PLAYBACK_STATE_QUEUED;
   playback_publish(playback);

   stasis_app_send_command_async(control, play_uri, ao2_bump(playback), remove_from_playbacks);

   return playback;
}

stasis_app_playback_find_by_id()

struct stasis_app_playback* stasis_app_playback_find_by_id

(

const char *

id

)

Finds the playback object with the given id.

Parameters

id	Id of the playback object to find.

Returns

Associated stasis_app_playback object.

NULL if id not found.

Definition at line 550 of file res_stasis_playback.c.

References ao2_find, and OBJ_KEY.

Referenced by ast_ari_playbacks_control(), ast_ari_playbacks_get(), ast_ari_playbacks_stop(), and play_on_channel_in_bridge().

{
   return ao2_find(playbacks, id, OBJ_KEY);
}

stasis_app_playback_get_id()

const char* stasis_app_playback_get_id

(

struct stasis_app_playback *

playback

)

Gets the unique id of a playback object.

Parameters

playback

Playback control object.

Returns

playback's id.

NULL if playback ic NULL

Definition at line 543 of file res_stasis_playback.c.

References stasis_app_playback::id.

Referenced by ari_bridges_play_helper(), and ari_channels_handle_play().

{
   /* id is immutable; no lock needed */
   return control->id;
}

stasis_app_playback_get_state()

enum stasis_app_playback_state stasis_app_playback_get_state

(

struct stasis_app_playback *

playback

)

Gets the current state of a playback operation.

Parameters

playback

Playback control object.

Returns

The state of the playback object.

Definition at line 536 of file res_stasis_playback.c.

References lock, and SCOPED_AO2LOCK.

{
   SCOPED_AO2LOCK(lock, control);
   return control->state;
}

stasis_app_playback_operation()

enum stasis_playback_oper_results stasis_app_playback_operation	(	struct stasis_app_playback *	playback,
		enum stasis_app_playback_media_operation	operation
	)

Controls the media for a given playback operation.

Parameters

playback	Playback control object.
control	Media control operation.

Returns

STASIS_PLAYBACK_OPER_OK on success.

stasis_playback_oper_results indicating failure.

Definition at line 708 of file res_stasis_playback.c.

References ast_assert, ast_log, lock, LOG_ERROR, operations, SCOPED_AO2LOCK, STASIS_PLAYBACK_MEDIA_OP_MAX, STASIS_PLAYBACK_OPER_FAILED, STASIS_PLAYBACK_OPER_NOT_PLAYING, STASIS_PLAYBACK_OPER_OK, STASIS_PLAYBACK_STATE_MAX, and STASIS_PLAYBACK_STATE_PLAYING.

Referenced by ast_ari_playbacks_control(), and ast_ari_playbacks_stop().

{
   playback_opreation_cb cb;
   SCOPED_AO2LOCK(lock, playback);

   ast_assert((unsigned int)playback->state < STASIS_PLAYBACK_STATE_MAX);

   if (operation >= STASIS_PLAYBACK_MEDIA_OP_MAX) {
      ast_log(LOG_ERROR, "Invalid playback operation %u\n", operation);
      return -1;
   }

   cb = operations[playback->state][operation];

   if (!cb) {
      if (playback->state != STASIS_PLAYBACK_STATE_PLAYING) {
         /* So we can be specific in our error message. */
         return STASIS_PLAYBACK_OPER_NOT_PLAYING;
      } else {
         /* And, really, all operations should be valid during
          * playback */
         ast_log(LOG_ERROR,
            "Unhandled operation during playback: %u\n",
            operation);
         return STASIS_PLAYBACK_OPER_FAILED;
      }
   }

   return cb(playback) ?
      STASIS_PLAYBACK_OPER_FAILED : STASIS_PLAYBACK_OPER_OK;
}

stasis_app_playback_snapshot_type()

struct stasis_message_type* stasis_app_playback_snapshot_type

(

void

)

Message type for playback updates. The data is an ast_channel_blob.

Referenced by load_module(), playback_publish(), playback_to_json(), and unload_module().

stasis_app_playback_to_json()

struct ast_json* stasis_app_playback_to_json

(

const struct stasis_app_playback *

playback

)

Convert a playback to its JSON representation.

Parameters

playback

The playback object to convert to JSON

Return values

Definition at line 555 of file res_stasis_playback.c.

References ast_json_pack(), ast_json_ref(), ast_json_unref(), AST_VECTOR_GET, AST_VECTOR_SIZE, stasis_app_playback::id, stasis_app_playback::language, stasis_app_playback::media, NULL, RAII_VAR, state_to_string(), and stasis_app_playback::target.

Referenced by ari_bridges_play_helper(), ari_channels_handle_play(), ast_ari_playbacks_get(), and playback_publish().

{
   RAII_VAR(struct ast_json *, json, NULL, ast_json_unref);

   if (playback == NULL) {
      return NULL;
   }

   if (playback->media_index == AST_VECTOR_SIZE(&playback->medias) - 1) {
      json = ast_json_pack("{s: s, s: s, s: s, s: s, s: s}",
         "id", playback->id,
         "media_uri", playback->media,
         "target_uri", playback->target,
         "language", playback->language,
         "state", state_to_string(playback->state));
   } else {
      json = ast_json_pack("{s: s, s: s, s: s, s: s, s: s, s: s}",
         "id", playback->id,
         "media_uri", playback->media,
         "next_media_uri", AST_VECTOR_GET(&playback->medias, playback->media_index + 1),
         "target_uri", playback->target,
         "language", playback->language,
         "state", state_to_string(playback->state));
   }

   return ast_json_ref(json);
}