From: Jeongmo Yang Date: Mon, 23 Feb 2015 07:12:37 +0000 (+0900) Subject: Update header file and deprecate some APIs X-Git-Tag: accepted/tizen/common/20150225.131038^0 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6ddbf31d96f56bc211ad9777b05188eddab627f0;p=platform%2Fcore%2Fapi%2Frecorder.git Update header file and deprecate some APIs Change-Id: I965a7b3429763cc51b6f3757ad4d936e9de1dc75 Signed-off-by: Jeongmo Yang --- diff --git a/CMakeLists.txt b/CMakeLists.txt old mode 100755 new mode 100644 diff --git a/doc/images/capi_media_recorder_state_diagram.png b/doc/images/capi_media_recorder_state_diagram.png new file mode 100644 index 0000000..62f4088 Binary files /dev/null and b/doc/images/capi_media_recorder_state_diagram.png differ diff --git a/doc/recorder_doc.h b/doc/recorder_doc.h new file mode 100644 index 0000000..6681e82 --- /dev/null +++ b/doc/recorder_doc.h @@ -0,0 +1,232 @@ +/* + * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + +#ifndef __TIZEN_MEDIA_RECORDER_DOC_H__ +#define __TIZEN_MEDIA_RECORDER_DOC_H__ + + +/** + * @file recorder_doc.h + * @brief This file contains high level documentation of the recorder API. + */ + + +/** + * @ingroup CAPI_MEDIA_FRAMEWORK + * @defgroup CAPI_MEDIA_RECORDER_MODULE Recorder + * @brief The @ref CAPI_MEDIA_RECORDER_MODULE API provides functions for audio and video recording. + * + * @section CAPI_MEDIA_RECORDER_MODULE_HEADER Required Header + * \#include + * + * + * @section CAPI_MEDIA_RECORDER_MODULE_OVERVIEW Overview + * The Recorder API provides functions to control the recording of a multimedia content. Simple audio and audio/video are supported. + * Recording operations operate as a state machine, described below. + * + * In addition, the API contains functions to configure the recording process, or find details about it, such as getting/setting the filename + * for the recording, the file format and the video codec. Some of these interfaces are listed in the Recorder Attributes API. + * + * Additional functions allow registering notifications via callback functions for various state change events. + * + * @subsection CAPI_MEDIA_RECORDER_MODULE_LIFE_CYCLE_STATE_DIAGRAM State Diagram + * @image html capi_media_recorder_state_diagram.png + * + * @subsection CAPI_MEDIA_RECORDER_MODULE_LIFE_CYCLE_STATE_TRANSITIONS State Transitions + *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
FUNCTIONPRE-STATEPOST-STATESYNC TYPE
recorder_create_videorecorder()
recorder_create_audiorecorder() 		NONE CREATED ASYNC
recorder_destroy() CREATED NONE ASYNC
recorder_prepare() CREATED READY ASYNC
recorder_unprepare() READY CREATED ASYNC
recorder_start() READY / PAUSED RECORDING ASYNC
recorder_pause() RECORDING PAUSED ASYNC
recorder_cancel()
recorder_commit() 		RECORDING / PAUSED READY ASYNC
+ *
+ * + * @subsection CAPI_MEDIA_RECORDER_MODULE_LIFE_CYCLE_CALLBACK_OPERATIONS Callback(Event) Operations + * The callback mechanism is used to notify the application about significant recorder events. + *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
REGISTER UNREGISTER CALLBACK DESCRIPTION
recorder_set_recording_limit_reached_cb() recorder_unset_recording_limit_reached_cb() recorder_recording_limit_reached_cb() This callback is called when recording limitation error has occurred during recording.
recorder_set_recording_status_cb() recorder_unset_recording_status_cb() recorder_recording_status_cb() This callback is used to notify the recording status.
recorder_set_state_changed_cb() recorder_unset_state_changed_cb() recorder_state_changed_cb() This callback is used to notify the change of recorder's state.
+ * + * @subsection CAPI_MEDIA_RECORDER_MODULE_FOREACH_OPERATIONS Foreach Operations + *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
FOREACHCALLBACKDESCRIPTION
recorder_foreach_supported_file_format()recorder_supported_file_format_cb()Supported file format
recorder_foreach_supported_audio_encoder()recorder_supported_audio_encoder_cb()Supported audio encoder
recorder_foreach_supported_video_encoder()recorder_supported_video_encoder_cb()Supported video encoder
+ * + * @section CAPI_MEDIA_RECORDER_MODULE_FEATURE Related Features + * This API is related with the following features:\n + * - http://tizen.org/feature/camera\n + * - http://tizen.org/feature/microphone + * + * It is recommended to design feature related codes in your application for reliability.\n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * More details on featuring your application can be found from Feature Element. + * + */ + + +/** + * @ingroup CAPI_MEDIA_RECORDER_MODULE + * @defgroup CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE Attributes + * @brief The @ref CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE API provides functions for getting and setting recorder attributes. + * + * @section CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE_OVERVIEW Overview + * The Media Recorder API provides basic recorder attribute manipulators. + * + * The Recorder Attributes API provides functions to set and get basic recorder attributes: + *
    + *
  • File size limit
    • + *
  • Recording time limit
    • + *
  • Audio recording device
    • + *
  • Audio sample rate
    • + *
  • Audio encoder bit rate
    • + *
  • Video encoder bit rate
    • + *
+ * + * Each of these attributes have a get/set pair of functions. For example, recorder_attr_set_time_limit() and recorder_attr_get_time_limit(). + * For more detailed information and programming examples for this API, see the Multimedia Tutorial. + * + * @section CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE_FEATURE Related Features + * This API is related with the following features:\n + * - http://tizen.org/feature/camera\n + * - http://tizen.org/feature/microphone + * + * It is recommended to design feature related codes in your application for reliability.\n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * More details on featuring your application can be found from Feature Element. + * + */ + + /** + * @ingroup CAPI_MEDIA_RECORDER_MODULE + * @defgroup CAPI_MEDIA_RECORDER_CAPABILITY_MODULE Capability + * @brief It provides capability information of the media recorder. + * @section CAPI_MEDIA_RECORDER_CAPABILITY_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_MEDIA_RECORDER_CAPABILITY_MODULE_OVERVIEW Overview + * The Capability API allows you to retrieve the recorder capabilities mentioned below: + *
    + *
  • Supported file formats
    • + *
  • Supported audio and video encoders
    • + *
+ * To get all supported file formats, call recorder_foreach_supported_file_format(). + * This function will internally invoke recorder_supported_file_format_cb() for each file format. + * + * @section CAPI_MEDIA_RECORDER_CAPABILITY_MODULE_FEATURE Related Features + * This API is related with the following features:\n + * - http://tizen.org/feature/camera\n + * - http://tizen.org/feature/microphone + * + * It is recommended to design feature related codes in your application for reliability.\n + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n + * More details on featuring your application can be found from Feature Element. + * + */ + +#endif /* __TIZEN_MEDIA_RECORDER_DOC_H__ */ diff --git a/include/recorder.h b/include/recorder.h index 9caf672..2ba1392 100644 --- a/include/recorder.h +++ b/include/recorder.h @@ -14,10 +14,8 @@ * limitations under the License. */ - - #ifndef __TIZEN_MULTIMEDIA_RECORDER_H__ -#define __TIZEN_MULTIMEDIA_RECORDER_H__ +#define __TIZEN_MULTIMEDIA_RECORDER_H__ #include #include #include @@ -26,12 +24,12 @@ extern "C" { #endif -#define RECORDER_ERROR_CLASS TIZEN_ERROR_MULTIMEDIA_CLASS | 0x10 - +#define RECORDER_ERROR_CLASS TIZEN_ERROR_RECORDER | 0x10 /** * @file recorder.h * @brief This file contains the Recorder API. + * @since_tizen 2.3 */ /** @@ -40,12 +38,14 @@ extern "C" { */ /** - * @brief The handle to media recorder + * @brief The Media recorder handle. + * @since_tizen 2.3 */ typedef struct recorder_s *recorder_h; /** - * @brief Enumerations of error code for the media recorder. + * @brief Enumeration for error code of the media recorder. + * @since_tizen 2.3 */ typedef enum { @@ -66,66 +66,71 @@ typedef enum } recorder_error_e; /** - * @brief Enumerations for camera states. + * @brief Enumeration for recorder states. + * @since_tizen 2.3 */ typedef enum { - RECORDER_STATE_NONE, /**< Recorder is not created */ - RECORDER_STATE_CREATED, /**< Recorder is created, but not prepared*/ - RECORDER_STATE_READY, /**< Recorder is ready to record\n In case of video recorder, preview display will be shown */ - RECORDER_STATE_RECORDING, /**< Recorder is recording media*/ - RECORDER_STATE_PAUSED, /**< Recorder is paused while recording media*/ + RECORDER_STATE_NONE, /**< Recorder is not created */ + RECORDER_STATE_CREATED, /**< Recorder is created, but not prepared */ + RECORDER_STATE_READY, /**< Recorder is ready to record \n In case of video recorder, preview display will be shown */ + RECORDER_STATE_RECORDING, /**< Recorder is recording media */ + RECORDER_STATE_PAUSED, /**< Recorder is paused while recording media */ } recorder_state_e; /** - * @brief Enumerations of recording limitation. + * @brief Enumeration for the recording limit. + * @since_tizen 2.3 */ typedef enum { - RECORDER_RECORDING_LIMIT_TIME, /**< Time limit (second) of recording file */ - RECORDER_RECORDING_LIMIT_SIZE, /**< Size limit (kilo bytes [KB]) of recording file */ - RECORDER_RECORDING_LIMIT_FREE_SPACE, /**< No free space in storage */ + RECORDER_RECORDING_LIMIT_TIME, /**< Time limit (second) of recording file */ + RECORDER_RECORDING_LIMIT_SIZE, /**< Size limit (kilo bytes [KB]) of recording file */ + RECORDER_RECORDING_LIMIT_FREE_SPACE, /**< No free space in storage */ } recorder_recording_limit_type_e; /** - * @brief Enumerations of file container format. + * @brief Enumeration for the file container format. + * @since_tizen 2.3 */ typedef enum { - RECORDER_FILE_FORMAT_3GP, /**< 3GP file format */ - RECORDER_FILE_FORMAT_MP4, /**< MP4 file format */ - RECORDER_FILE_FORMAT_AMR, /**< AMR file format */ - RECORDER_FILE_FORMAT_ADTS, /**< ADTS file format */ - RECORDER_FILE_FORMAT_WAV, /**< WAV file format */ - RECORDER_FILE_FORMAT_OGG, /**< OGG file format */ + RECORDER_FILE_FORMAT_3GP, /**< 3GP file format */ + RECORDER_FILE_FORMAT_MP4, /**< MP4 file format */ + RECORDER_FILE_FORMAT_AMR, /**< AMR file format */ + RECORDER_FILE_FORMAT_ADTS, /**< ADTS file format */ + RECORDER_FILE_FORMAT_WAV, /**< WAV file format */ + RECORDER_FILE_FORMAT_OGG, /**< OGG file format */ } recorder_file_format_e; - /** - * @brief Enumerations of audio codec. + * @brief Enumeration for the audio codec. + * @since_tizen 2.3 */ typedef enum { RECORDER_AUDIO_CODEC_DISABLE = -1, /**< Disable audio track */ - RECORDER_AUDIO_CODEC_AMR = 0, /**< AMR codec */ - RECORDER_AUDIO_CODEC_AAC, /**< AAC codec */ - RECORDER_AUDIO_CODEC_VORBIS, /**< Vorbis codec */ - RECORDER_AUDIO_CODEC_PCM /**< PCM codec */ + RECORDER_AUDIO_CODEC_AMR = 0, /**< AMR codec */ + RECORDER_AUDIO_CODEC_AAC, /**< AAC codec */ + RECORDER_AUDIO_CODEC_VORBIS, /**< Vorbis codec */ + RECORDER_AUDIO_CODEC_PCM /**< PCM codec */ } recorder_audio_codec_e; /** - * @brief Enumerations of video codec. + * @brief Enumeration for the video codec. + * @since_tizen 2.3 */ typedef enum { - RECORDER_VIDEO_CODEC_H263, /**< H263 codec */ - RECORDER_VIDEO_CODEC_H264, /**< H264 codec */ - RECORDER_VIDEO_CODEC_MPEG4, /**< MPEG4 codec */ - RECORDER_VIDEO_CODEC_THEORA /**< Theora codec */ + RECORDER_VIDEO_CODEC_H263, /**< H263 codec */ + RECORDER_VIDEO_CODEC_H264, /**< H264 codec */ + RECORDER_VIDEO_CODEC_MPEG4, /**< MPEG4 codec */ + RECORDER_VIDEO_CODEC_THEORA /**< Theora codec */ } recorder_video_codec_e; /** - * @brief Enumerations of audio capture devices. + * @brief Enumeration for audio capture devices. + * @since_tizen 2.3 */ typedef enum { @@ -134,18 +139,19 @@ typedef enum } recorder_audio_device_e; /** - * @brief Enumerations of the recorder rotation type. + * @brief Enumeration for the recorder rotation type. + * @since_tizen 2.3 */ typedef enum { - RECORDER_ROTATION_NONE, /**< No rotation */ - RECORDER_ROTATION_90, /**< 90 degree rotation */ - RECORDER_ROTATION_180, /**< 180 degree rotation */ - RECORDER_ROTATION_270, /**< 270 degree rotation */ + RECORDER_ROTATION_NONE, /**< No rotation */ + RECORDER_ROTATION_90, /**< 90 degree rotation */ + RECORDER_ROTATION_180, /**< 180 degree rotation */ + RECORDER_ROTATION_270, /**< 270 degree rotation */ } recorder_rotation_e; /** - * @brief Enumerations of the recorder flip type. + * @brief Enumerations for the recorder flip type. */ typedef enum { @@ -157,7 +163,8 @@ typedef enum /** - * @brief Enumerations of the recorder policy. + * @brief Enumeration for the recorder policy. + * @since_tizen 2.3 */ typedef enum { @@ -178,40 +185,41 @@ typedef enum */ /** - * @brief The callback function called when limitation error occurs while recording. + * @brief Called when limitation error occurs while recording. * @details The callback function is possible to receive three types of limits: time, size and no-space. - * @remarks After called it, recording data is discarded and not written in recording file. Also the state of recorder is not changed. - * @param[in] type The limitation type + * @since_tizen 2.3 + * @remarks After being called, recording data is discarded and not written in the recording file. Also the state of recorder is not changed. + * @param[in] type The imitation type * @param[in] user_data The user data passed from the callback registration function - * @pre It is required to register a callback using recorder_set_recording_limit_reached_cb() + * @pre You have to register a callback using recorder_set_recording_limit_reached_cb(). * @see recorder_set_recording_status_cb() * @see recorder_set_recording_limit_reached_cb() * @see recorder_unset_recording_limit_reached_cb() */ typedef void (*recorder_recording_limit_reached_cb)(recorder_recording_limit_type_e type, void *user_data); - /** - * @brief Callback function to indicate recording status - * @remarks This callback function is repeatedly invoked during #RECORDER_STATE_RECORDING state - * @param[in] elapsed_time The time of recording (milliseconds) - * @param[in] file_size The size of recording file (KB) - * @param[in] user_data The user data passed from the callback registration function - * @pre recorder_start() will cause this callback if you register this callback using recorder_set_recording_status_cb() + * @brief Called to indicate the recording status. + * @since_tizen 2.3 + * @remarks This callback function is repeatedly invoked during the #RECORDER_STATE_RECORDING state. + * @param[in] elapsed_time The time of the recording (milliseconds) + * @param[in] file_size The size of the recording file (KB) + * @param[in] user_data The user data passed from the callback registration function + * @pre recorder_start() will invoke this callback if you register it using recorder_set_recording_status_cb(). * @see recorder_set_recording_status_cb() * @see recorder_unset_recording_status_cb() * @see recorder_start() */ typedef void (*recorder_recording_status_cb)(unsigned long long elapsed_time, unsigned long long file_size, void *user_data); - /** - * @brief Called when the record state has changed. - * @param[in] previous The previous state of recorder - * @param[in] current The current state of recorder - * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false + * @brief Called when the record state is changed. + * @since_tizen 2.3 + * @param[in] previous The previous state of the recorder + * @param[in] current The current state of the recorder + * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed * @param[in] user_data The user data passed from the callback registration function - * @pre This function is required to register a callback using recorder_set_state_changed_cb() + * @pre This function is required to register a callback using recorder_set_state_changed_cb(). * @see recorder_set_state_changed_cb() * @see recorder_prepare() * @see recorder_unprepare() @@ -223,9 +231,9 @@ typedef void (*recorder_recording_status_cb)(unsigned long long elapsed_time, un typedef void (*recorder_state_changed_cb)(recorder_state_e previous , recorder_state_e current , bool by_policy, void *user_data); /** - * @brief Called when the recorder interrupted by policy - * - * @param[in] policy The policy that interrupting the recorder + * @brief Called when the recorder is interrupted by a policy. + * @since_tizen 2.3 + * @param[in] policy The policy that is interrupting the recorder * @param[in] previous The previous state of the recorder * @param[in] current The current state of the recorder * @param[in] user_data The user data passed from the callback registration function @@ -234,19 +242,17 @@ typedef void (*recorder_state_changed_cb)(recorder_state_e previous , recorder_s typedef void (*recorder_interrupted_cb)(recorder_policy_e policy, recorder_state_e previous, recorder_state_e current, void *user_data); /** - * @brief Called when audio stream data was delivering just before storing in record file. - * @remarks - * The callback function holds the same buffer that will be recorded.\n - * So if an user change the buffer, the result file will has the buffer.\n - * The callback is called via internal thread of Frameworks. so don't be invoke UI API, recorder_unprepare(), recorder_commit() and recorder_cancel() in callback. - * + * @brief Called when audio stream data was being delivered just before storing in the recorded file. + * @since_tizen 2.3 + * @remarks The callback function holds the same buffer that will be recorded. \n + * So if the user changes the buffer, the result file will contain the buffer. + * @remarks The callback is called via internal thread of Frameworks, therefore do not invoke UI API, recorder_unprepare(), recorder_commit() and recorder_cancel() in callback. * @param[in] stream The audio stream data - * @param[in] size The size of stream data + * @param[in] size The size of the stream data * @param[in] format The audio format - * @param[in] channel The number of channel - * @param[in] timestamp The timestamp of stream buffer( in msec ) + * @param[in] channel The number of the channel + * @param[in] timestamp The timestamp of the stream buffer (in msec) * @param[in] user_data The user data passed from the callback registration function - * * @see recorder_set_audio_stream_cb() */ typedef void (*recorder_audio_stream_cb)(void* stream, int size, audio_sample_type_e format, int channel, unsigned int timestamp, void *user_data); @@ -264,27 +270,23 @@ typedef void (*recorder_audio_stream_cb)(void* stream, int size, audio_sample_ty typedef bool (*recorder_supported_video_resolution_cb)(int width, int height, void *user_data); /** - * @brief Called when the error occurred. - * - * @remarks - * This callback inform critical error situation.\n - * When invoked this callback, user should release the resource and terminate application.\n - * These error code will be occurred\n - * #RECORDER_ERROR_DEVICE\n - * #RECORDER_ERROR_INVALID_OPERATION\n - * #RECORDER_ERROR_OUT_OF_MEMORY\n - * - * @param[in] error The error code - * @param[in] current_state The current state of the recorder - * @param[in] user_data The user data passed from the callback registration function - * + * @brief Called when the error occurred. + * @since_tizen 2.3 + * @remarks This callback informs about the critical error situation. \n + * When being invoked, user should release the resource and terminate the application. \n + * This error code will be reported. + * #RECORDER_ERROR_DEVICE \n + * #RECORDER_ERROR_INVALID_OPERATION \n + * #RECORDER_ERROR_OUT_OF_MEMORY. + * @param[in] error The error code + * @param[in] current_state The current state of the recorder + * @param[in] user_data The user data passed from the callback registration function * @pre This callback function is invoked if you register this callback using recorder_set_error_cb(). * @see recorder_set_error_cb() * @see recorder_unset_error_cb() */ typedef void (*recorder_error_cb)(recorder_error_e error, recorder_state_e current_state, void *user_data); - /** * @} */ @@ -295,32 +297,33 @@ typedef void (*recorder_error_cb)(recorder_error_e error, recorder_state_e curre */ /** - * @brief Gets called iteratively to notify you of supported file formats. + * @brief Called iteratively to notify about the supported file formats. + * @since_tizen 2.3 * @param[in] format The format of recording files * @param[in] user_data The user data passed from the foreach function - * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop + * @return @c true to continue with the next iteration of the loop, \n otherwise @c false to break out of the loop * @pre recorder_foreach_supported_file_format() will invoke this callback. * @see recorder_foreach_supported_file_format() */ typedef bool (*recorder_supported_file_format_cb)(recorder_file_format_e format, void *user_data); - /** - * @brief Gets called iteratively to notify you of supported audio encoders. - * @param[in] codec The codec of audio encoder. + * @brief Called iteratively to notify about the supported audio encoders. + * @since_tizen 2.3 + * @param[in] codec The codec of audio encoder * @param[in] user_data The user data passed from the foreach function - * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop + * @return @c true to continue with the next iteration of the loop, \n otherwise @c false to break out of the loop * @pre recorder_foreach_supported_audio_encoder() will invoke this callback. * @see recorder_foreach_supported_audio_encoder() */ typedef bool (*recorder_supported_audio_encoder_cb)(recorder_audio_codec_e codec, void *user_data); - /** - * @brief Gets called iteratively to notify you of supported video encoders. - * @param[in] codec The codec of video encoder. + * @brief Called iteratively to notify about the supported video encoders. + * @since_tizen 2.3 + * @param[in] codec The codec of video encoder * @param[in] user_data The user data passed from the foreach function - * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop + * @return @c true to continue with the next iteration of the loop, \n otherwise @c false to break out of the loop * @pre recorder_foreach_supported_video_encoder() will invoke this callback. * @see recorder_foreach_supported_video_encoder() */ @@ -336,39 +339,48 @@ typedef bool (*recorder_supported_video_encoder_cb)(recorder_video_codec_e codec */ /** - * @brief Creates a recorder handle to record a video. - * @param[in] camera The handle to camera - * @param[out] recorder A handle to recorder - * @remarks @a recorder must be released with recorder_destroy() by you.\n - * The @a camera handle also could be used for capturing images.\n - * If camera state was CAMERA_STATE_CREATED, the preview format will be changed to the recommended preview format for recording.\n - * The created recorder state will be different according to camera state : \n - * CAMERA_STATE_CREATED -> RECORDER_STATE_CREATED\n - * CAMERA_STATE_PREVIEW -> RECORDER_STATE_READY\n - * CAMERA_STATE_CAPTURED -> RECORDER_STATE_READY\n - * @return 0 on success, otherwise a negative error value. + * @brief Creates a recorder handle to record a video. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * @remarks You must release @a recorder using recorder_destroy(). \n + * The @a camera handle also could be used for capturing images. \n + * If the camera state was #CAMERA_STATE_CREATED, the preview format will be changed to the recommended preview format for recording. + * @remarks The created recorder state will be different according to camera state : \n + * #CAMERA_STATE_CREATED -> #RECORDER_STATE_CREATED\n + * #CAMERA_STATE_PREVIEW -> #RECORDER_STATE_READY\n + * #CAMERA_STATE_CAPTURED -> #RECORDER_STATE_READY + * @param[in] camera The handle to the camera + * @param[out] recorder A handle to the recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_OUT_OF_MEMORY Out of memory * @retval #RECORDER_ERROR_SOUND_POLICY Sound policy error * @retval #RECORDER_ERROR_INVALID_OPERATION Invalid operation + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see camera_create() * @see camera_stop_preview() * @see recorder_destroy() */ int recorder_create_videorecorder(camera_h camera, recorder_h *recorder); - /** - * @brief Creates a recorder handle to record an audio. - * @remarks @a recorder must be released with recorder_destroy() by you - * @param[out] recorder A handle to recorder - * @return 0 on success, otherwise a negative error value. + * @brief Creates a recorder handle to record an audio. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * @remarks You must release @a recorder using recorder_destroy(). + * @param[out] recorder A handle to the recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_OUT_OF_MEMORY Out of memory * @retval #RECORDER_ERROR_SOUND_POLICY Sound policy error * @retval #RECORDER_ERROR_INVALID_OPERATION Invalid operation + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @post The recorder state will be #RECORDER_STATE_CREATED. * @see recorder_destroy() */ @@ -376,15 +388,20 @@ int recorder_create_audiorecorder(recorder_h *recorder); /** - * @brief Destroys the recorder handle - * @remarks Video recorder's camera handle is not release by this function. - * @param[in] recorder The handle to media recorder - * @return 0 on success, otherwise a negative error value. + * @brief Destroys the recorder handle. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * @remarks The video recorder's camera handle is not released by this function. + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_OPERATION Invalid operation * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state should be #RECORDER_STATE_CREATED + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state should be #RECORDER_STATE_CREATED. * @post The recorder state will be #RECORDER_STATE_NONE. * @see camera_destroy() * @see recorder_create_videorecorder() @@ -392,83 +409,105 @@ int recorder_create_audiorecorder(recorder_h *recorder); */ int recorder_destroy(recorder_h recorder); - /** - * @brief Prepares the media recorder for recording - * @remarks Before calling the function, it is required to set audio encoder (recorder_set_audio_encoder()), - * video encoder(recorder_set_video_encoder()), file format (recorder_set_file_format()) with proper value. - * @param[in] recorder The handle to media recorder - * @return 0 on success, otherwise a negative error value. + * @brief Prepares the media recorder for recording. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * @remarks Before calling the function, it is required to properly set audio encoder (recorder_set_audio_encoder()), + * video encoder(recorder_set_video_encoder()) and file format (recorder_set_file_format()). + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_SOUND_POLICY Sound policy error * @retval #RECORDER_ERROR_INVALID_OPERATION Invalid operation * @retval #RECORDER_ERROR_INVALID_STATE Invalid state + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @pre The recorder state should be #RECORDER_STATE_CREATED by recorder_create_videorecorder(), recorder_create_audiorecorder() or recorder_unprepare(). * @post The recorder state will be #RECORDER_STATE_READY. - * @post If recorder handle is created by recorder_create_videorecorder(), it's camera state will be changed to #CAMERA_STATE_PREVIEW. + * @post If recorder handle is created by recorder_create_videorecorder(), the camera state will be changed to #CAMERA_STATE_PREVIEW. * @see recorder_create_videorecorder() - * @see recorder_create_audiorecorder() + * @see recorder_create_audiorecorder() * @see recorder_unprepare() * @see recorder_set_audio_encoder() - * @see recorder_set_video_encoder() - * @see recorder_set_file_format() + * @see recorder_set_video_encoder() + * @see recorder_set_file_format() */ int recorder_prepare(recorder_h recorder); - /** - * @brief Reset the media recorder. - * @param[in] recorder The handle to media recorder - * @return 0 on success, otherwise a negative error value. + * @brief Resets the media recorder. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_OPERATION Invalid operation * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state should be #RECORDER_STATE_READY by recorder_prepare(), recorder_cancel(),or recorder_commit(). + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state should be #RECORDER_STATE_READY set by recorder_prepare(), recorder_cancel() or recorder_commit(). * @post The recorder state will be #RECORDER_STATE_CREATED. - * @post If recorder handle is created by recorder_create_videorecorder(), it's camera state will be changed to #CAMERA_STATE_CREATED. + * @post If the recorder handle is created by recorder_create_videorecorder(), camera state will be changed to #CAMERA_STATE_CREATED. * @see recorder_prepare() * @see recorder_cancel() * @see recorder_commit() */ int recorder_unprepare(recorder_h recorder); - /** - * @brief Starts recording - * @remarks If file path has been set to existing file, this file is removed automatically and updated by new one.\n - * In video recorder, some preview format is not supporting record mode. It will return #RECORDER_ERROR_INVALID_OPERATION error.\n - * You should use default preview format or #CAMERA_PIXEL_FORMAT_NV12 in record mode\n - * @param[in] recorder The handle to media recorder - * @return 0 on success, otherwise a negative error value. + * @brief Starts the recording. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * @remarks If file path has been set to an existing file, this file is removed automatically and updated by new one. \n + * In the video recorder, some preview format does not support record mode. It will return #RECORDER_ERROR_INVALID_OPERATION error. \n + * You should use default preview format or #CAMERA_PIXEL_FORMAT_NV12 in the record mode. \n + * When you want to record audio or video file, you need to add privilege according to rules below additionally. \n + * If you want to save contents to internal storage, you should add mediastorage privilege. \n + * If you want to save contents to external storage, you should add externalstorage privilege. \n + * The filename should be set before this function is invoked. + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_OPERATION Invalid operation * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_READY by recorder_prepare() or #RECORDER_STATE_PAUSED by recorder_pause() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_READY by recorder_prepare() or #RECORDER_STATE_PAUSED by recorder_pause(). \n + * The filename should be set by recorder_set_filename(). * @post The recorder state will be #RECORDER_STATE_RECORDING. * @see recorder_pause() - * @see recorder_commit() - * @see recorder_cancel() - * @see recorder_set_audio_encoder() - * @see recorder_set_filename() - * @see recorder_set_file_format() + * @see recorder_commit() + * @see recorder_cancel() + * @see recorder_set_audio_encoder() + * @see recorder_set_filename() + * @see recorder_set_file_format() * @see recorder_recording_status_cb() + * @see recorder_set_filename() */ int recorder_start(recorder_h recorder); - /** - * @brief Pauses recording - * @remarks Recording can be resumed with recorder_start(). - * @param[in] recorder The handle to media recorder - * @return 0 on success, otherwise a negative error value. + * @brief Pauses the recording. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * @remarks Recording can be resumed with recorder_start(). + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_OPERATION Invalid operation * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_RECORDING + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_RECORDING. * @post The recorder state will be #RECORDER_STATE_PAUSED. * @see recorder_pause() * @see recorder_commit() @@ -476,16 +515,23 @@ int recorder_start(recorder_h recorder); */ int recorder_pause(recorder_h recorder); - /** - * @brief Stops recording and saving the result - * @param [in] recorder The handle to media recorder - * @return 0 on success, otherwise a negative error value. + * @brief Stops recording and saves the result. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * @remarks When you want to record audio or video file, you need to add privilege according to rules below additionally. \n + * If you want to save contents to internal storage, you should add mediastorage privilege. \n + * If you want to save contents to external storage, you should add externalstorage privilege. + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_OPERATION Invalid operation * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_RECORDING by recorder_start() or #RECORDER_STATE_PAUSED by recorder_pause() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_RECORDING set by recorder_start() or #RECORDER_STATE_PAUSED by recorder_pause(). * @post The recorder state will be #RECORDER_STATE_READY. * @see recorder_pause() * @see recorder_cancel() @@ -494,17 +540,24 @@ int recorder_pause(recorder_h recorder); */ int recorder_commit(recorder_h recorder); - /** - * @brief Cancels recording. - * @detail The recording data is discarded and not written in recording file. - * @param[in] recorder The handle to media recorder - * @return 0 on success, otherwise a negative error value + * @brief Cancels the recording. + * @details The recording data is discarded and not written in the recording file. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * @remarks When you want to record audio or video file, you need to add privilege according to rules below additionally. \n + * If you want to save contents to internal storage, you should add mediastorage privilege. \n + * If you want to save contents to external storage, you should add externalstorage privilege. + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_OPERATION Invalid operation * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_RECORDING by recorder_start() or #RECORDER_STATE_PAUSED by recorder_pause() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_RECORDING set by recorder_start() or #RECORDER_STATE_PAUSED by recorder_pause(). * @post The recorder state will be #RECORDER_STATE_READY. * @see recorder_pause() * @see recorder_commit() @@ -513,68 +566,80 @@ int recorder_commit(recorder_h recorder); */ int recorder_cancel(recorder_h recorder); - /** * @brief Gets the recorder's current state. - * @param[in] recorder The handle to the recorder. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[out] state The current state of the recorder - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported */ int recorder_get_state(recorder_h recorder, recorder_state_e *state); /** * @brief Gets the peak audio input level that was sampled since the last call to this function. - * @remarks 0 dB indicates maximum input level, -300dB indicates minimum input level - * @param[in] recorder The handle to the recorder. - * @param[out] level The audio input level in dB - * @return 0 on success, otherwise a negative error value. + * @since_tizen 2.3 + * @remarks @c 0 dB indicates maximum input level, @c -300 dB indicates minimum input level. + * @param[in] recorder The handle to the media recorder + * @param[out] dB The audio input level in dB + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_RECORDING or #RECORDER_STATE_PAUSED + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_RECORDING or #RECORDER_STATE_PAUSED. */ int recorder_get_audio_level(recorder_h recorder, double *dB); /** - * @brief Sets the file path to record - * @details This function sets file path which defines where newly recorder data should be stored. - * @remarks If there is already exists same file in file system, then old file will be overwritten. - * @param[in] recorder The handle to media recorder + * @brief Sets the file path to record. + * @details This function sets file path which defines where newly recorded data should be stored. + * @since_tizen 2.3 + * @remarks If the same file already exists in the file system, then old file will be overwritten. + * @param[in] recorder The handle to the media recorder * @param[in] path The recording file path - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED by recorder_create() or recorder_unprepare() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED by recorder_create() or recorder_unprepare(). * @see recorder_get_filename() */ int recorder_set_filename(recorder_h recorder, const char *path); - /** - * @brief Gets the file path to record - * @remarks @a path must be released with @c free() by you. - * @param[in] recorder The handle to media recorder + * @brief Gets the file path to record. + * @since_tizen 2.3 + * @remarks You must release @a path using free(). + * @param[in] recorder The handle to the media recorder * @param[out] path The recording file path - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_set_filename() */ int recorder_get_filename(recorder_h recorder, char **path); - /** - * @brief Sets the file format for recording media stream - * @param[in] recorder The handle to media recorder + * @brief Sets the file format for recording media stream. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] format The media file format - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED. * @see recorder_get_file_format() * @see recorder_foreach_supported_file_format() */ @@ -582,12 +647,15 @@ int recorder_set_file_format(recorder_h recorder, recorder_file_format_e format) /** - * @brief Gets the file format for recording media stream - * @param [in] recorder The handle to media recorder - * @param [in] format The media file format - * @return 0 on success, otherwise a negative error value. + * @brief Gets the file format for recording media stream. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @param[out] format The media file format + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_set_file_format() * @see recorder_foreach_supported_file_format() */ @@ -604,14 +672,17 @@ int recorder_get_file_format(recorder_h recorder, recorder_file_format_e *format */ /** - * @brief Retrieves all supported file formats by invoking a specific callback for each supported file format - * @param[in] recorder The handle to media recorder + * @brief Retrieves all supported file formats by invoking a specific callback for each supported file format. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] callback The iteration callback * @param[in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * @post recorder_supported_file_format_cb() will be invoked + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @post recorder_supported_file_format_cb() will be invoked. * @see recorder_get_file_format() * @see recorder_set_file_format() * @see recorder_supported_file_format_cb() @@ -628,29 +699,34 @@ int recorder_foreach_supported_file_format(recorder_h recorder, recorder_support */ /** - * @brief Sets the audio codec for encoding audio stream - * @remarks You can get available audio encoders by using recorder_foreach_supported_audio_encoder().\n - * if set to RECORDER_AUDIO_CODEC_DISABLE, audio track is not created in recording files. - * @param[in] recorder The handle to media recorder + * @brief Sets the audio codec for encoding an audio stream. + * @since_tizen 2.3 + * @remarks You can get available audio encoders by using recorder_foreach_supported_audio_encoder(). \n + * If set to #RECORDER_AUDIO_CODEC_DISABLE, the audio track is not created in recording files. + * @param[in] recorder The handle to the media recorder * @param[in] codec The audio codec - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY. * @see recorder_get_audio_encoder() * @see recorder_foreach_supported_audio_encoder() */ int recorder_set_audio_encoder(recorder_h recorder, recorder_audio_codec_e codec); - /** - * @brief Gets the audio codec for encoding audio stream - * @param [in] recorder The handle to media recorder - * @param [out] codec The audio codec - * @return 0 on success, otherwise a negative error value. + * @brief Gets the audio codec for encoding an audio stream. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @param[out] codec The audio codec + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_set_audio_encoder() * @see recorder_foreach_supported_audio_encoder() */ @@ -666,14 +742,17 @@ int recorder_get_audio_encoder(recorder_h recorder, recorder_audio_codec_e *code */ /** - * @brief Retrieves all supported audio encoders by invoking a specific callback for each supported audio encoder. - * @param[in] recorder The handle to media recorder + * @brief Retrieves all supported audio encoders by invoking a specific callback for each supported audio encoder. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] callback The iteration callback * @param[in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * @post recorder_supported_audio_encoder_cb() will be invoked + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @post recorder_supported_audio_encoder_cb() will be invoked. * @see recorder_set_audio_encoder() * @see recorder_get_audio_encoder() * @see recorder_supported_audio_encoder_cb() @@ -726,28 +805,33 @@ int recorder_set_video_resolution(recorder_h recorder, int width, int height); int recorder_get_video_resolution(recorder_h recorder, int *width, int *height); /** - * @brief Sets the video codec for encoding video stream. + * @brief Sets the video codec for encoding video stream. + * @since_tizen 2.3 * @remarks You can get available video encoders by using recorder_foreach_supported_video_encoder(). - * @param[in] recorder The handle to media recorder + * @param[in] recorder The handle to the media recorder * @param[in] codec The video codec - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY. * @see recorder_get_video_encoder() * @see recorder_foreach_supported_video_encoder() */ int recorder_set_video_encoder(recorder_h recorder, recorder_video_codec_e codec); - /** - * @brief Gets the video codec for encoding video stream. - * @param[in] recorder The handle to media recorder + * @brief Gets the video codec for encoding video stream. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[out] codec The video codec - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_set_video_encoder() * @see recorder_foreach_supported_video_encoder() */ @@ -782,14 +866,17 @@ int recorder_foreach_supported_video_resolution(recorder_h recorder, recorder_supported_video_resolution_cb foreach_cb, void *user_data); /** - * @brief Retrieves all supported video encoders by invoking a specific callback for each supported video encoder. - * @param[in] recorder The handle to media recorder + * @brief Retrieves all supported video encoders by invoking a specific callback for each supported video encoder. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] callback The iteration callback * @param[in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * @post recorder_supported_video_encoder_cb() will be invoked + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @post recorder_supported_video_encoder_cb() will be invoked. * @see recorder_set_video_encoder() * @see recorder_get_video_encoder() * @see recorder_supported_video_encoder_cb() @@ -806,183 +893,196 @@ int recorder_foreach_supported_video_encoder(recorder_h recorder, recorder_suppo */ /** - * @brief Registers the callback function that will be invoked when the recorder state changes. - * @param[in] recorder The handle to the recorder. + * @brief Registers the callback function that will be invoked when the recorder state changes. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] callback The function pointer of user callback * @param[in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * @post recorder_state_changed_cb() will be invoked + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @post recorder_state_changed_cb() will be invoked. * @see recorder_unset_state_changed_cb() * @see recorder_state_changed_cb() */ int recorder_set_state_changed_cb(recorder_h recorder, recorder_state_changed_cb callback, void *user_data); - /** - * @brief Unregisters the callback function. - * @param[in] recorder The handle to the recorder. - * @return 0 on success, otherwise a negative error value. + * @brief Unregisters the callback function. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_set_state_changed_cb() */ int recorder_unset_state_changed_cb(recorder_h recorder); /** - * @brief Registers a callback function to be called when recorder interrupted by policy. - * - * @param[in] recorder The handle to the recorder + * @brief Registers a callback function to be called when the media recorder is interrupted according to a policy. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] callback The callback function to register * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #RECORDER_ERROR_NONE Successful - * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * - * @see recorder_unset_interrupted_cb() + * @return @c 0 on success, otherwise a negative error value + * @retval #RECORDER_ERROR_NONE Successful + * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @see recorder_unset_interrupted_cb() * @see recorder_interrupted_cb() */ int recorder_set_interrupted_cb(recorder_h recorder, recorder_interrupted_cb callback, void *user_data); /** - * @brief Unregisters the callback function. - * - * @param[in] recorder The handle to the recorder - * @return 0 on success, otherwise a negative error value. - * @retval #RECORDER_ERROR_NONE Successful - * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * - * @see recorder_set_interrupted_cb() + * @brief Unregisters the callback function. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value + * @retval #RECORDER_ERROR_NONE Successful + * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @see recorder_set_interrupted_cb() */ int recorder_unset_interrupted_cb(recorder_h recorder); /** - * @brief Registers a callback function to be called when audio stream data was delivering - * - * @remarks - * This callback function holds the same buffer that will be recorded.\n - * So if an user change the buffer, the result file will has the buffer.\n - * The callback is called via internal thread of Frameworks. so don't be invoke UI API, recorder_unprepare(), recorder_commit() and recorder_cancel() in callback.\n - * This callback function to be called in RECORDER_STATE_RECORDING and RECORDER_STATE_PAUSE state. + * @brief Registers a callback function to be called when audio stream data is being delivered. + * @since_tizen 2.3 + * @remarks This callback function holds the same buffer that will be recorded. \n + * Therefore if an user changes the buffer, the result file will have the buffer. \n + * @remarks The callback is called via internal thread of Frameworks. Therefore do not invoke UI API, recorder_unprepare(), recorder_commit() and recorder_cancel() in callback.\n + * This callback function to be called in #RECORDER_STATE_RECORDING and #RECORDER_STATE_PAUSED state. * - * @param[in] recorder The handle to the recorder - * @param[in] callback The callback function to register + * @param[in] recorder The handle to the recorder + * @param[in] callback The callback function to register * @param[in] user_data The user data to be passed to the callback function - * - * @return 0 on success, otherwise a negative error value. - * @retval #RECORDER_ERROR_NONE Successful - * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * @pre The recorder state should be #RECORDER_STATE_READY or #RECORDER_STATE_CREATED. - * - * @see recorder_unset_audio_stream_cb() - * @see recorder_audio_stream_cb() + * @return @c 0 on success, otherwise a negative error value + * @retval #RECORDER_ERROR_NONE Successful + * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state should be #RECORDER_STATE_READY or #RECORDER_STATE_CREATED. + * @see recorder_unset_audio_stream_cb() + * @see recorder_audio_stream_cb() */ int recorder_set_audio_stream_cb(recorder_h recorder, recorder_audio_stream_cb callback, void* user_data); /** - * @brief Unregisters the callback function. - * - * @param[in] recorder The handle to the recorder - * @return 0 on success, otherwise a negative error value. - * @retval #RECORDER_ERROR_NONE Successful - * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * - * @see recorder_set_audio_stream_cb() + * @brief Unregisters the callback function. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value + * @retval #RECORDER_ERROR_NONE Successful + * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @see recorder_set_audio_stream_cb() */ int recorder_unset_audio_stream_cb(recorder_h recorder); - /** - * @brief Registers a callback function to be invoked when the recording information changes. - * @param[in] recorder The handle to media recorder - * @param[in] callback The function pointer of user callback - * @param[in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. + * @brief Registers a callback function to be invoked when the recording information changes. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @param[in] callback The function pointer of user callback + * @param[in] user_data The user data to be passed to the callback function + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * @post recorder_recording_status_cb() will be invoked - * @see recorder_unset_recording_status_cb() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @post recorder_recording_status_cb() will be invoked. + * @see recorder_unset_recording_status_cb() * @see recorder_recording_status_cb() */ int recorder_set_recording_status_cb(recorder_h recorder, recorder_recording_status_cb callback, void *user_data); - /** * @brief Unregisters the callback function. - * @param[in] recorder The handle to media recorder - * @return 0 on success, otherwise a negative error value. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * @see recorder_set_recording_status_cb() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @see recorder_set_recording_status_cb() */ int recorder_unset_recording_status_cb(recorder_h recorder); - /** - * @brief Registers the callback function to run when reached recording limit. + * @brief Registers the callback function to be run when reached the recording limit. + * @since_tizen 2.3 * @param[in] recorder The handle to media recorder * @param[in] callback The function pointer of user callback * @param[in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * @post recorder_recording_limit_reached_cb() will be invoked - * @see recorder_unset_recording_limit_reached_cb() - * @see recorder_attr_set_size_limit() - * @see recorder_attr_set_time_limit() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @post recorder_recording_limit_reached_cb() will be invoked. + * @see recorder_unset_recording_limit_reached_cb() + * @see recorder_attr_set_size_limit() + * @see recorder_attr_set_time_limit() * @see recorder_recording_limit_reached_cb() */ int recorder_set_recording_limit_reached_cb(recorder_h recorder, recorder_recording_limit_reached_cb callback, void *user_data); - /** - * @brief Unregisters the callback function. - * @param[in] recorder The handle to media recorder - * @return 0 on success, otherwise a negative error value. + * @brief Unregisters the callback function. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_set_recording_limit_reached_cb() */ int recorder_unset_recording_limit_reached_cb(recorder_h recorder); - /** - * @brief Registers a callback function to be called when an asynchronous operation error occurred. - * - * @remarks - * This callback inform critical error situation.\n - * When invoked this callback, user should release the resource and terminate application.\n - * These error code will be occurred\n - * #RECORDER_ERROR_DEVICE\n - * #RECORDER_ERROR_INVALID_OPERATION\n - * #RECORDER_ERROR_OUT_OF_MEMORY\n - * + * @brief Registers a callback function to be called when an asynchronous operation error occurred. + * @since_tizen 2.3 + * @remarks This callback informs critical error situation.\n + * When this callback is invoked, user should release the resource and terminate the application. \n + * These error codes will occur. \n + * #RECORDER_ERROR_DEVICE \n + * #RECORDER_ERROR_INVALID_OPERATION \n + * #RECORDER_ERROR_OUT_OF_MEMORY * @param[in] recorder The handle to the recorder * @param[in] callback The callback function to register * @param[in] user_data The user data to be passed to the callback function - * @return 0 on success, otherwise a negative error value. - * @retval #RECORDER_ERROR_NONE Successful - * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @return @c 0 on success, otherwise a negative error value + * @retval #RECORDER_ERROR_NONE Successful + * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @post This function will invoke recorder_error_cb() when an asynchronous operation error occur. - * - * @see recorder_unset_error_cb() - * @see recorder_error_cb() + * @see recorder_unset_error_cb() + * @see recorder_error_cb() */ int recorder_set_error_cb(recorder_h recorder, recorder_error_cb callback, void *user_data); /** - * @brief Unregisters the callback function. - * + * @brief Unregisters the callback function. + * @since_tizen 2.3 * @param[in] recorder The handle to the recorder - * @return 0 on success, otherwise a negative error value. + * @return @c on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * - * @see recorder_set_error_cb() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @see recorder_set_error_cb() */ int recorder_unset_error_cb(recorder_h recorder); @@ -998,218 +1098,262 @@ int recorder_unset_error_cb(recorder_h recorder); /** - * @brief Sets maximum size of recording file. - * @remarks After reached limitation, recording data is discarded and not written in recording file. - * @param[in] recorder The handle to media recorder - * @param[in] kbyte The maximum size of recording file(KB)\n @c 0 means unlimited recording size. - * @return 0 on success, otherwise a negative error value. + * @brief Sets the maximum size of a recording file. + * @since_tizen 2.3 + * @remarks After reaching the limitation, the recording data is discarded and not written in the recording file. + * @param[in] recorder The handle to the media recorder + * @param[in] kbyte The maximum size of the recording file(KB) \n + * @c 0 means unlimited recording size. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY - * @see recorder_attr_get_size_limit() - * @see recorder_attr_set_time_limit() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY. + * @see recorder_attr_get_size_limit() + * @see recorder_attr_set_time_limit() */ int recorder_attr_set_size_limit(recorder_h recorder, int kbyte); - /** - * @brief Gets the maximum size of recording file. - * @param[in] recorder The handle to media recorder - * @param[out] kbyte The maximum size of recording file (KB)\n @c 0 means unlimited recording size - * @return 0 on success, otherwise a negative error value. + * @brief Gets the maximum size of a recording file. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @param[out] kbyte The maximum size of recording file (KB) \n + * @c 0 means unlimited recording size. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter - * @see recorder_attr_set_size_limit() - * @see recorder_attr_get_time_limit() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @see recorder_attr_set_size_limit() + * @see recorder_attr_get_time_limit() */ int recorder_attr_get_size_limit(recorder_h recorder, int *kbyte); - /** - * @brief Sets time limit of recording file. - * @remarks After reached limitation, recording data is discarded and not written in recording file. - * @param[in] recorder The handle to media recorder - * @param[in] second The time limit of recording file (in seconds) \n @c 0 means unlimited recording size - * @return 0 on success, otherwise a negative error value. + * @brief Sets the time limit of a recording file. + * @since_tizen 2.3 + * @remarks After reaching the limitation, the recording data is discarded and not written in the recording file. + * @param[in] recorder The handle to the media recorder + * @param[in] second The time limit of the recording file (in seconds) \n + * @c 0 means unlimited recording size. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY - * @see recorder_attr_get_time_limit() - * @see recorder_attr_set_size_limit() + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY. + * @see recorder_attr_get_time_limit() + * @see recorder_attr_set_size_limit() */ int recorder_attr_set_time_limit(recorder_h recorder, int second); /** - * @brief Gets the time limit of recording file - * @param[in] recorder The handle to media recorder - * @param[out] second The time limit of recording file (in seconds)\n @c 0 means unlimited recording time. - * @return 0 on success, otherwise a negative error value. + * @brief Gets the time limit of a recording file. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @param[out] second The time limit of the recording file (in seconds) \n + * @c 0 means unlimited recording time. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_attr_set_time_limit() * @see recorder_attr_get_size_limit() */ int recorder_attr_get_time_limit(recorder_h recorder, int *second); - /** - * @brief Sets audio device for recording. - * @param[in] recorder The handle to media recorder - * @param[in] device The type of audio device - * @return 0 on success, otherwise a negative error value. + * @brief Sets the audio device for recording. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @param[in] device The type of an audio device + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED. * @see recorder_attr_get_audio_device() */ int recorder_attr_set_audio_device(recorder_h recorder, recorder_audio_device_e device); - /** * @brief Gets the audio device for recording. - * @param[in] recorder The handle to media recorder - * @param[out] device The type of audio device - * @return 0 on success, otherwise a negative error value. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @param[out] device The type of an audio device + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_attr_set_audio_device() */ int recorder_attr_get_audio_device(recorder_h recorder, recorder_audio_device_e *device); - /** - * @brief Sets sampling rate of audio stream. - * @param[in] recorder The handle to media recorder + * @brief Sets the sampling rate of an audio stream. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] samplerate The sample rate in Hertz - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED. * @see recorder_attr_get_audio_samplerate() */ int recorder_attr_set_audio_samplerate(recorder_h recorder, int samplerate); - /** - * @brief Gets the sampling rate of audio stream. - * @param[in] recorder The handle to media recorder + * @brief Gets the sampling rate of an audio stream. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[out] samplerate The sample rate in Hertz - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_attr_set_audio_samplerate() */ int recorder_attr_get_audio_samplerate(recorder_h recorder, int *samplerate); - /** - * @brief Sets the bitrate of audio encoder. - * @param[in] recorder The handle to media recorder + * @brief Sets the bitrate of an audio encoder. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] bitrate The bitrate (for mms : 12200[bps], normal : 288000[bps]) - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY. * @see recorder_attr_get_audio_encoder_bitrate() */ int recorder_attr_set_audio_encoder_bitrate(recorder_h recorder, int bitrate); - /** - * @brief Sets bitrate of video encoder. - * @param[in] recorder The handle to media recorder + * @brief Sets the bitrate of a video encoder. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] bitrate The bitrate in bits per second - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter * @retval #RECORDER_ERROR_INVALID_STATE Invalid state - * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported + * @pre The recorder state must be #RECORDER_STATE_CREATED or #RECORDER_STATE_READY. * @see recorder_attr_get_video_encoder_bitrate() */ int recorder_attr_set_video_encoder_bitrate(recorder_h recorder, int bitrate); - /** - * @brief Gets the bitrate of audio encoder. - * @param[in] recorder The handle to media recorder - * @param[out] bitrate The bitrate in bits per second - * @return 0 on success, otherwise a negative error value. + * @brief Gets the bitrate of an audio encoder. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @param[out] bitrate The bitrate in bits per second + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_attr_set_audio_encoder_bitrate() */ int recorder_attr_get_audio_encoder_bitrate(recorder_h recorder, int *bitrate); - /** - * @brief Gets the bitrate of video encoder. - * @param[in] recorder The handle to media recorder - * @param[out] bitrate The bitrate in bits per second - * @return 0 on success, otherwise a negative error value. + * @brief Gets the bitrate of a video encoder. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @param[out] bitrate The bitrate in bits per second + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_attr_set_audio_encoder_bitrate() */ int recorder_attr_get_video_encoder_bitrate(recorder_h recorder, int *bitrate); - - /** - * @brief Sets the mute state of recorder - * @param[in] recorder The handle to media recorder + * @brief Sets the mute state of a recorder. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder * @param[in] enable The mute state - * @return 0 on success, otherwise a negative error value. + * @return @c 0 on success, otherwise a negative error value * @retval #RECORDER_ERROR_NONE Successful * @retval #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @retval #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_attr_is_muted() */ int recorder_attr_set_mute(recorder_h recorder, bool enable); /** - * @brief Gets the mute state of recorder - * @param[in] recorder The handle to media recorder - * @return true if the recorder is not recording any sound,\nelse false + * @brief Gets the mute state of a recorder. + * @since_tizen 2.3 + * @param[in] recorder The handle to the media recorder + * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section. + * @return @c true if the recorder is not recording any sound, + * otherwise @c false if the recorder is recording + * @exception #RECORDER_ERROR_NONE Successful + * @exception #RECORDER_ERROR_INVALID_PARAMETER Invalid parameter + * @exception #RECORDER_ERROR_PERMISSION_DENIED The access to the resources can not be granted + * @exception #RECORDER_ERROR_NOT_SUPPORTED The feature is not supported * @see recorder_attr_set_mute() */ bool recorder_attr_is_muted(recorder_h recorder); /** - * @brief Sets recording motion rate - * @remarks - * This attribute is valid only in video recorder.\n - * If the rate bigger than 0 and smaller than 1, video is recorded slow motion mode.\n - * If the rate bigger than 1, video is recorded fast motion mode(time lapse recording). - * Audio data is not recorded.\n - * To reset slow motion recording, setting rate to 1. - * @param[in] recorder The handle to media recorder - * @param[in] rate The recording motion rate. it is computed with fps. (0