diff options
Diffstat (limited to 'include/asterisk/stasis_app_recording.h')
| -rw-r--r-- | include/asterisk/stasis_app_recording.h | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/include/asterisk/stasis_app_recording.h b/include/asterisk/stasis_app_recording.h new file mode 100644 index 000000000..9c9930406 --- /dev/null +++ b/include/asterisk/stasis_app_recording.h @@ -0,0 +1,203 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2013, Digium, Inc. + * + * David M. Lee, II <dlee@digium.com> + * + * 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 <dlee@digium.com> + * \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 */ |