doc/recorder_doc.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_MEDIA_RECORDER_DOC_H__
  19 #define __TIZEN_MEDIA_RECORDER_DOC_H__
  20
  21
  22 /**
  23  * @file recorder_doc.h
  24  * @brief This file contains high level documentation of the recorder API.
  25  */
  26
  27
  28 /**
  29  * @ingroup CAPI_MEDIA_FRAMEWORK
  30  * @defgroup CAPI_MEDIA_RECORDER_MODULE Recorder
  31  * @brief The @ref CAPI_MEDIA_RECORDER_MODULE API provides functions for audio and video recording.
  32  *
  33  * @section CAPI_MEDIA_RECORDER_MODULE_HEADER Required Header
  34  *   \#include <recorder.h>
  35  *
  36  *
  37  * @section CAPI_MEDIA_RECORDER_MODULE_OVERVIEW Overview
  38  * The Recorder API provides functions to control the recording of a multimedia content. Simple audio and audio/video are supported.
  39  * Recording operations operate as a state machine, described below.
  40  *
  41  * In addition, the API contains functions to configure the recording process, or find details about it, such as getting/setting the filename
  42  * for the recording, the file format and the video codec. Some of these interfaces are listed in the Recorder Attributes API.
  43  *
  44  * Additional functions allow registering notifications via callback functions for various state change events.
  45  *
  46  * @subsection CAPI_MEDIA_RECORDER_MODULE_LIFE_CYCLE_STATE_DIAGRAM State Diagram
  47  * @image html capi_media_recorder_state_diagram.png
  48  *
  49  * @subsection CAPI_MEDIA_RECORDER_MODULE_LIFE_CYCLE_STATE_TRANSITIONS State Transitions
  50  * <div><table class="doxtable" >
  51  * <tr>
  52  *    <th><B>FUNCTION</B></th>
  53  *    <th><B>PRE-STATE</B></th>
  54  *    <th><B>POST-STATE</B></th>
  55  *    <th><B>SYNC TYPE</B></th>
  56  * </tr>
  57  * <tr>
  58  *    <td> recorder_create_videorecorder()<br>recorder_create_audiorecorder() </td>
  59  *    <td> NONE </td>
  60  *    <td> CREATED </td>
  61  *    <td> ASYNC </td>
  62  * </tr>
  63  * <tr>
  64  *    <td> recorder_destroy() </td>
  65  *    <td> CREATED </td>
  66  *    <td> NONE </td>
  67  *    <td> ASYNC </td>
  68  * </tr>
  69  * <tr>
  70  *    <td> recorder_prepare() </td>
  71  *    <td> CREATED </td>
  72  *    <td> READY</td>
  73  *    <td> ASYNC </td>
  74  * </tr>
  75  * <tr>
  76  *    <td> recorder_unprepare() </td>
  77  *    <td> READY </td>
  78  *    <td> CREATED </td>
  79  *    <td> ASYNC </td>
  80  * </tr>
  81  * <tr>
  82  *    <td> recorder_start() </td>
  83  *    <td> READY / PAUSED </td>
  84  *    <td> RECORDING </td>
  85  *    <td> ASYNC </td>
  86  * </tr>
  87  * <tr>
  88  *    <td> recorder_pause() </td>
  89  *    <td> RECORDING </td>
  90  *    <td> PAUSED </td>
  91  *    <td> ASYNC </td>
  92  * </tr>
  93  * <tr>
  94  *    <td> recorder_cancel() <br>recorder_commit() </td>
  95  *    <td> RECORDING / PAUSED </td>
  96  *    <td> READY </td>
  97  *    <td> ASYNC </td>
  98  * </tr>
  99  * </table>
 100  * </div>
 101  *
 102  * @subsection CAPI_MEDIA_RECORDER_MODULE_LIFE_CYCLE_CALLBACK_OPERATIONS  Callback(Event) Operations
 103  * The callback mechanism is used to notify the application about significant recorder events.
 104  * <div><table class="doxtable" >
 105  *     <tr>
 106  *        <th><b> REGISTER</b></th>
 107  *        <th><b> UNREGISTER</b></th>
 108  *        <th><b> CALLBACK</b></th>
 109  *        <th><b> DESCRIPTION</b></th>
 110  *     </tr>
 111  *     <tr>
 112  *        <td> recorder_set_recording_limit_reached_cb()</td>
 113  *        <td> recorder_unset_recording_limit_reached_cb()</td>
 114  *        <td> recorder_recording_limit_reached_cb()</td>
 115  *        <td> This callback is called when recording limitation error has occurred during recording.</td>
 116  *     </tr>
 117  *     <tr>
 118  *        <td> recorder_set_recording_status_cb()</td>
 119  *        <td> recorder_unset_recording_status_cb()</td>
 120  *        <td> recorder_recording_status_cb()</td>
 121  *        <td> This callback is used to notify the recording status.</td>
 122  *     </tr>
 123  *     <tr>
 124  *        <td> recorder_set_state_changed_cb()</td>
 125  *        <td> recorder_unset_state_changed_cb()</td>
 126  *        <td> recorder_state_changed_cb()</td>
 127  *        <td> This callback is used to notify the change of recorder's state.</td>
 128  *     </tr>
 129  * </table></div>
 130  *
 131  * @subsection CAPI_MEDIA_RECORDER_MODULE_FOREACH_OPERATIONS Foreach Operations
 132  * <div><table class="doxtable" >
 133  *     <tr>
 134  *        <th><b>FOREACH</b></th>
 135  *        <th><b>CALLBACK</b></th>
 136  *        <th><b>DESCRIPTION</b></th>
 137  *     </tr>
 138  *     <tr>
 139  *        <td>recorder_foreach_supported_file_format()</td>
 140  *        <td>recorder_supported_file_format_cb()</td>
 141  *        <td>Supported file format </td>
 142  *     </tr>
 143  *     <tr>
 144  *        <td>recorder_foreach_supported_audio_encoder()</td>
 145  *        <td>recorder_supported_audio_encoder_cb()</td>
 146  *        <td>Supported audio encoder</td>
 147  *     </tr>
 148  *     <tr>
 149  *        <td>recorder_foreach_supported_video_encoder()</td>
 150  *        <td>recorder_supported_video_encoder_cb()</td>
 151  *        <td>Supported video encoder</td>
 152  *     </tr>
 153  *</table></div>
 154  *
 155  * @section CAPI_MEDIA_RECORDER_MODULE_FEATURE Related Features
 156  * This API is related with the following features:\n
 157  *  - http://tizen.org/feature/camera\n
 158  *  - http://tizen.org/feature/microphone
 159  *
 160  * It is recommended to design feature related codes in your application for reliability.\n
 161  * 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
 162  * 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
 163  * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
 164  *
 165  */
 166
 167
 168 /**
 169  * @ingroup CAPI_MEDIA_RECORDER_MODULE
 170  * @defgroup CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE Attributes
 171  * @brief The @ref CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE API provides functions for getting and setting recorder attributes.
 172  *
 173  * @section CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE_HEADER Required Header
 174  *   \#include <recorder.h>
 175  *
 176  * @section CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE_OVERVIEW Overview
 177  * The Media Recorder API provides basic recorder attribute manipulators.
 178  *
 179  * The Recorder Attributes API provides functions to set and get basic recorder attributes:
 180  * <ul>
 181  *   <li>File size limit</li>
 182  *   <li>Recording time limit</li>
 183  *   <li>Audio recording device</li>
 184  *   <li>Audio sample rate</li>
 185  *   <li>Audio encoder bit rate</li>
 186  *   <li>Video encoder bit rate</li>
 187  * </ul>
 188  *
 189  * Each of these attributes have a get/set pair of functions. For example, recorder_attr_set_time_limit() and recorder_attr_get_time_limit().
 190  * For more detailed information and programming examples for this API, see the Multimedia Tutorial.
 191  *
 192  * @section CAPI_MEDIA_RECORDER_ATTRIBUTES_MODULE_FEATURE Related Features
 193  * This API is related with the following features:\n
 194  *  - http://tizen.org/feature/camera\n
 195  *  - http://tizen.org/feature/microphone
 196  *
 197  * It is recommended to design feature related codes in your application for reliability.\n
 198  * 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
 199  * 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
 200  * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
 201  *
 202  */
 203
 204  /**
 205  * @ingroup CAPI_MEDIA_RECORDER_MODULE
 206  * @defgroup CAPI_MEDIA_RECORDER_CAPABILITY_MODULE Capability
 207  * @brief It provides capability information of the media recorder.
 208  * @section CAPI_MEDIA_RECORDER_CAPABILITY_MODULE_HEADER Required Header
 209  *   \#include <recorder.h>
 210  *
 211  * @section CAPI_MEDIA_RECORDER_CAPABILITY_MODULE_OVERVIEW  Overview
 212  * The Capability API allows you to retrieve the recorder capabilities mentioned below:
 213  * <ul>
 214  *   <li>Supported file formats</li>
 215  *   <li>Supported audio and video encoders</li>
 216  * </ul>
 217  * To get all supported file formats, call recorder_foreach_supported_file_format().
 218  * This function will internally invoke recorder_supported_file_format_cb() for each file format.
 219  *
 220  * @section CAPI_MEDIA_RECORDER_CAPABILITY_MODULE_FEATURE Related Features
 221  * This API is related with the following features:\n
 222  *  - http://tizen.org/feature/camera\n
 223  *  - http://tizen.org/feature/microphone
 224  *
 225  * It is recommended to design feature related codes in your application for reliability.\n
 226  * 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
 227  * 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
 228  * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
 229  *
 230  */
 231
 232 #endif /* __TIZEN_MEDIA_RECORDER_DOC_H__ */