Asterisk - The Open Source Telephony Project  18.5.0
Enumerations | Functions
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_playbackstasis_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_playbackstasis_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_typestasis_app_playback_snapshot_type (void)
 Message type for playback updates. The data is an ast_channel_blob. More...
 
struct ast_jsonstasis_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 [email protected][email protected]digi[email protected]um.co[email protected]m
Since
12

Definition in file stasis_app_playback.h.

Enumeration Type Documentation

◆ 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.

57  {
58  /*! Stop the playback operation. */
60  /*! Restart the media from the beginning. */
62  /*! Pause playback. */
64  /*! Resume paused playback. */
66  /*! Rewind playback. */
68  /*! Fast forward playback. */
70  /*! Enum end sentinel. */
72 };

◆ 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.

37  {
38  /*! The playback has not started yet */
40  /*! The media is currently playing */
42  /*! The media is currently playing */
44  /*! The media is transitioning to the next in the list */
46  /*! The media has stopped playing */
48  /*! The playback was canceled. */
50  /*! The playback was stopped. */
52  /*! Enum end sentinel. */
54 };

◆ 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.

74  {
75  /*! The target is a channel */
77  /*! The target is a bridge */
79 };

◆ 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.

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
controlControl for res_stasis.
mediaArray of const char * media files to play.
media_countThe number of media files in media.
languageSelects the file based on language.
target_idID of the target bridge or channel.
target_typeWhat the target type is
skipmsNumber of milliseconds to skip for forward/reverse operations.
offsetmsNumber of milliseconds to skip before playing.
idID 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().

476 {
477  struct stasis_app_playback *playback;
478  size_t i;
479 
480  if (skipms < 0 || offsetms < 0 || media_count == 0) {
481  return NULL;
482  }
483 
484  playback = playback_create(control, id);
485  if (!playback) {
486  return NULL;
487  }
488 
489  for (i = 0; i < media_count; i++) {
490  char *media_uri;
491 
492  if (ast_strlen_zero(media[i])) {
493  ast_log(LOG_ERROR, "Attempted to play media on channel '%s' but no media URI was provided.\n",
495  ao2_ref(playback, -1);
496  return NULL;
497  }
498 
499  media_uri = ast_malloc(strlen(media[i]) + 1);
500  if (!media_uri) {
501  ao2_ref(playback, -1);
502  return NULL;
503  }
504 
505  ast_debug(3, "%s: Sending play(%s) command\n",
507 
508  /* safe */
509  strcpy(media_uri, media[i]);
510  if (AST_VECTOR_APPEND(&playback->medias, media_uri)) {
511  ao2_ref(playback, -1);
512  ast_free(media_uri);
513  return NULL;
514  }
515  }
516 
517  if (skipms == 0) {
519  }
520 
521  ast_string_field_set(playback, media, AST_VECTOR_GET(&playback->medias, 0));
523  set_target_uri(playback, target_type, target_id);
524  playback->skipms = skipms;
525  playback->offsetms = offsetms;
526  ao2_link(playbacks, playback);
527 
528  playback->state = STASIS_PLAYBACK_STATE_QUEUED;
529  playback_publish(playback);
530 
532 
533  return playback;
534 }
static void set_target_uri(struct stasis_app_playback *playback, enum stasis_app_playback_target_type target_type, const char *target_id)
static struct ao2_container * playbacks
#define AST_VECTOR_APPEND(vec, elem)
Append an element to a vector, growing the vector if needed.
Definition: vector.h:256
#define NULL
Definition: resample.c:96
#define PLAYBACK_DEFAULT_SKIPMS
#define ast_strlen_zero(foo)
Definition: strings.h:52
#define ao2_bump(obj)
Definition: astobj2.h:491
const ast_string_field media
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:452
#define ast_log
Definition: astobj2.c:42
#define ao2_ref(o, delta)
Definition: astobj2.h:464
static char language[MAX_LANGUAGE]
Definition: chan_alsa.c:117
#define ast_malloc(len)
A wrapper for malloc()
Definition: astmm.h:193
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().
Definition: control.c:904
static int skipms
static void remove_from_playbacks(void *data)
RAII_VAR function to remove a playback from the global list when leaving scope.
#define LOG_ERROR
Definition: logger.h:285
const char * stasis_app_control_get_channel_id(const struct stasis_app_control *control)
Returns the uniqueid of the channel associated with this control.
Definition: control.c:1430
#define ast_free(a)
Definition: astmm.h:182
static int play_uri(struct stasis_app_control *control, struct ast_channel *chan, void *data)
static struct stasis_app_playback * playback_create(struct stasis_app_control *control, const char *id)
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:682
static void playback_publish(struct stasis_app_playback *playback)
#define ast_string_field_set(x, field, data)
Set a field to a simple string value.
Definition: stringfields.h:514
#define ao2_link(container, obj)
Definition: astobj2.h:1549

◆ 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
idId 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().

551 {
552  return ao2_find(playbacks, id, OBJ_KEY);
553 }
#define OBJ_KEY
Definition: astobj2.h:1155
static struct ao2_container * playbacks
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1756

◆ 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
playbackPlayback 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().

545 {
546  /* id is immutable; no lock needed */
547  return control->id;
548 }

◆ 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
playbackPlayback control object.
Returns
The state of the playback object.

Definition at line 536 of file res_stasis_playback.c.

References lock, and SCOPED_AO2LOCK.

538 {
539  SCOPED_AO2LOCK(lock, control);
540  return control->state;
541 }
ast_mutex_t lock
Definition: app_meetme.c:1091
#define SCOPED_AO2LOCK(varname, obj)
scoped lock specialization for ao2 mutexes.
Definition: lock.h:602

◆ 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
playbackPlayback control object.
controlMedia 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().

711 {
713  SCOPED_AO2LOCK(lock, playback);
714 
715  ast_assert((unsigned int)playback->state < STASIS_PLAYBACK_STATE_MAX);
716 
717  if (operation >= STASIS_PLAYBACK_MEDIA_OP_MAX) {
718  ast_log(LOG_ERROR, "Invalid playback operation %u\n", operation);
719  return -1;
720  }
721 
722  cb = operations[playback->state][operation];
723 
724  if (!cb) {
725  if (playback->state != STASIS_PLAYBACK_STATE_PLAYING) {
726  /* So we can be specific in our error message. */
728  } else {
729  /* And, really, all operations should be valid during
730  * playback */
732  "Unhandled operation during playback: %u\n",
733  operation);
735  }
736  }
737 
738  return cb(playback) ?
740 }
#define ast_assert(a)
Definition: utils.h:695
#define ast_log
Definition: astobj2.c:42
ast_mutex_t lock
Definition: app_meetme.c:1091
playback_opreation_cb operations[STASIS_PLAYBACK_STATE_MAX][STASIS_PLAYBACK_MEDIA_OP_MAX]
A sparse array detailing how commands should be handled in the various playback states. Unset entries imply invalid operations.
#define LOG_ERROR
Definition: logger.h:285
int(* playback_opreation_cb)(struct stasis_app_playback *playback)
#define SCOPED_AO2LOCK(varname, obj)
scoped lock specialization for ao2 mutexes.
Definition: lock.h:602

◆ 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
playbackThe 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().

557 {
558  RAII_VAR(struct ast_json *, json, NULL, ast_json_unref);
559 
560  if (playback == NULL) {
561  return NULL;
562  }
563 
564  if (playback->media_index == AST_VECTOR_SIZE(&playback->medias) - 1) {
565  json = ast_json_pack("{s: s, s: s, s: s, s: s, s: s}",
566  "id", playback->id,
567  "media_uri", playback->media,
568  "target_uri", playback->target,
569  "language", playback->language,
570  "state", state_to_string(playback->state));
571  } else {
572  json = ast_json_pack("{s: s, s: s, s: s, s: s, s: s, s: s}",
573  "id", playback->id,
574  "media_uri", playback->media,
575  "next_media_uri", AST_VECTOR_GET(&playback->medias, playback->media_index + 1),
576  "target_uri", playback->target,
577  "language", playback->language,
578  "state", state_to_string(playback->state));
579  }
580 
581  return ast_json_ref(json);
582 }
struct ast_json * ast_json_ref(struct ast_json *value)
Increase refcount on value.
Definition: json.c:67
struct ast_json * ast_json_pack(char const *format,...)
Helper for creating complex JSON values.
Definition: json.c:591
void ast_json_unref(struct ast_json *value)
Decrease refcount on value. If refcount reaches zero, value is freed.
Definition: json.c:73
#define NULL
Definition: resample.c:96
const ast_string_field target
const ast_string_field id
const ast_string_field media
static const char * state_to_string(enum stasis_app_playback_state state)
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:911
#define AST_VECTOR_GET(vec, idx)
Get an element from a vector.
Definition: vector.h:682
Abstract JSON element (object, array, string, int, ...).
const ast_string_field language
#define AST_VECTOR_SIZE(vec)
Get the number of elements in a vector.
Definition: vector.h:611