/* * Asterisk -- An open source telephony toolkit. * * Copyright (C) 2013, Digium, Inc. * * David M. Lee, II * * See http://www.asterisk.org for more information about * the Asterisk project. Please do not directly contact * any of the maintainers of this project for assistance; * the project provides a web site, mailing lists and IRC * channels for your use. * * This program is free software, distributed under the terms of * the GNU General Public License Version 2. See the LICENSE file * at the top of the source tree. */ #ifndef _ASTERISK_STASIS_APP_RECORDING_H #define _ASTERISK_STASIS_APP_RECORDING_H /*! \file * * \brief Stasis Application Recording API. See \ref res_stasis "Stasis * Application API" for detailed documentation. * * \author David M. Lee, II * \since 12 */ #include "asterisk/app.h" #include "asterisk/stasis_app.h" /*! Opaque struct for handling the recording of media to a file. */ struct stasis_app_recording; /*! State of a recording operation */ enum stasis_app_recording_state { /*! The recording has not started yet */ STASIS_APP_RECORDING_STATE_QUEUED, /*! The media is currently recording */ STASIS_APP_RECORDING_STATE_RECORDING, /*! The media is currently paused */ STASIS_APP_RECORDING_STATE_PAUSED, /*! The media has stopped recording */ STASIS_APP_RECORDING_STATE_COMPLETE, /*! The media has stopped playing */ STASIS_APP_RECORDING_STATE_FAILED, }; /*! Valid operation for controlling a recording. */ enum stasis_app_recording_media_operation { /*! Stop the recording operation. */ STASIS_APP_RECORDING_STOP, }; #define STASIS_APP_RECORDING_TERMINATE_INVALID 0 #define STASIS_APP_RECORDING_TERMINATE_NONE -1 #define STASIS_APP_RECORDING_TERMINATE_ANY -2 struct stasis_app_recording_options { AST_DECLARE_STRING_FIELDS( AST_STRING_FIELD(name); /*!< name Name of the recording. */ AST_STRING_FIELD(format); /*!< Format to be recorded (wav, gsm, etc.) */ ); /*! Number of seconds of silence before ending the recording. */ int max_silence_seconds; /*! Maximum recording duration. 0 for no maximum. */ int max_duration_seconds; /*! Which DTMF to use to terminate the recording * \c STASIS_APP_RECORDING_TERMINATE_NONE to terminate only on hangup * \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF */ char terminate_on; /*! How to handle recording when a file already exists */ enum ast_record_if_exists if_exists; /*! If true, a beep is played at the start of recording */ int beep:1; }; /*! * \brief Allocate a recording options object. * * Clean up with ao2_cleanup(). * * \param name Name of the recording. * \param format Format to record in. * \return Newly allocated options object. * \return \c NULL on error. */ struct stasis_app_recording_options *stasis_app_recording_options_create( const char *name, const char *format); /*! * \brief Parse a string into the recording termination enum. * * \param str String to parse. * \return DTMF value to terminate on. * \return \c STASIS_APP_RECORDING_TERMINATE_NONE to not terminate on DTMF. * \return \c STASIS_APP_RECORDING_TERMINATE_ANY to terminate on any DTMF. * \return \c STASIS_APP_RECORDING_TERMINATE_INVALID if input was invalid. */ char stasis_app_recording_termination_parse(const char *str); /*! * \brief Parse a string into the if_exists enum. * * \param str String to parse. * \return How to handle an existing file. * \return -1 on error. */ enum ast_record_if_exists stasis_app_recording_if_exists_parse( const char *str); /*! * \brief Record media from a channel. * * A reference to the \a options object may be kept, so it MUST NOT be modified * after calling this function. * * On error, \c errno is set to indicate the failure reason. * - \c EINVAL: Invalid input. * - \c EEXIST: A recording with that name is in session. * - \c ENOMEM: Out of memory. * * \param control Control for \c res_stasis. * \param options Recording options. * \return Recording control object. * \return \c NULL on error. */ struct stasis_app_recording *stasis_app_control_record( struct stasis_app_control *control, struct stasis_app_recording_options *options); /*! * \brief Gets the current state of a recording operation. * * \param recording Recording control object. * \return The state of the \a recording object. */ enum stasis_app_recording_state stasis_app_recording_get_state( struct stasis_app_recording *recording); /*! * \brief Gets the unique name of a recording object. * * \param recording Recording control object. * \return \a recording's name. * \return \c NULL if \a recording ic \c NULL */ const char *stasis_app_recording_get_name( struct stasis_app_recording *recording); /*! * \brief Finds the recording object with the given name. * * \param name Name of the recording object to find. * \return Associated \ref stasis_app_recording object. * \return \c NULL if \a name not found. */ struct stasis_app_recording *stasis_app_recording_find_by_name(const char *name); /*! * \brief Construct a JSON model of a recording. * * \param recording Recording to conver. * \return JSON model. * \return \c NULL on error. */ struct ast_json *stasis_app_recording_to_json( const struct stasis_app_recording *recording); /*! * \brief Possible results from a recording operation. */ enum stasis_app_recording_oper_results { /*! Operation completed successfully. */ STASIS_APP_RECORDING_OPER_OK, /*! Operation failed. */ STASIS_APP_RECORDING_OPER_FAILED, /*! Operation failed b/c recording is not in session. */ STASIS_APP_RECORDING_OPER_NOT_RECORDING, }; /*! * \brief Controls the media for a given recording operation. * * \param recording Recording control object. * \param control Media control operation. * \return \c STASIS_APP_RECORDING_OPER_OK on success. * \return \ref stasis_app_recording_oper_results indicating failure. */ enum stasis_app_recording_oper_results stasis_app_recording_operation( struct stasis_app_recording *recording, enum stasis_app_recording_media_operation operation); /*! * \brief Message type for recording updates. The data is an * \ref ast_channel_blob. */ struct stasis_message_type *stasis_app_recording_snapshot_type(void); #endif /* _ASTERISK_STASIS_APP_RECORDING_H */