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_FAILED , 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 59 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_FAILED	The media has stopped because of an error playing the file
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 media has stopped because of an error playing the file */
    STASIS_PLAYBACK_STATE_FAILED,
    /*! 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 76 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 147 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.

Return values

NULL

on error.

Definition at line 488 of file res_stasis_playback.c.

{
    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;
}

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, stasis_app_playback::control, language, LOG_ERROR, stasis_app_playback::media, stasis_app_playback::medias, NULL, stasis_app_playback::offsetms, play_uri(), playback_create(), PLAYBACK_DEFAULT_SKIPMS, playback_publish(), playbacks, remove_from_playbacks(), set_target_uri(), skipms, stasis_app_playback::skipms, stasis_app_control_get_channel_id(), stasis_app_send_command_async(), STASIS_PLAYBACK_STATE_QUEUED, and stasis_app_playback::state.

Referenced by ari_bridges_play_helper(), and ari_channels_handle_play().

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.

Return values

NULL	if id not found.

Definition at line 567 of file res_stasis_playback.c.

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

References ao2_find, OBJ_KEY, and playbacks.

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

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.

Return values

NULL	if playback ic NULL

Definition at line 560 of file res_stasis_playback.c.

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

References stasis_app_playback::control.

Referenced by ari_bridges_play_helper(), and ari_channels_handle_play().

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 553 of file res_stasis_playback.c.

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

References stasis_app_playback::control, lock, and SCOPED_AO2LOCK.

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.
operation	Media control operation.

Return values

STASIS_PLAYBACK_OPER_OK

on success.

Returns

stasis_playback_oper_results indicating failure.

Definition at line 726 of file res_stasis_playback.c.

{
    playback_operation_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;
}

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, STASIS_PLAYBACK_STATE_PLAYING, and stasis_app_playback::state.

Referenced by ast_ari_playbacks_control(), and ast_ari_playbacks_stop().

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(), 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

NULL

on error

Returns

A JSON object on success

Definition at line 572 of file res_stasis_playback.c.

{
    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);
}

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, stasis_app_playback::media_index, stasis_app_playback::medias, NULL, RAII_VAR, stasis_app_playback::state, 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().