include/wav_player.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
  19
  20 #ifndef __TIZEN_MEDIA_WAV_PLAYER_H__
  21 #define __TIZEN_MEDIA_WAV_PLAYER_H__
  22
  23 #include <tizen.h>
  24 #include <sound_manager.h>
  25
  26 #ifdef __cplusplus
  27 extern "C"
  28 {
  29 #endif
  30
  31 #define WAV_PLAYER_ERROR_CLASS          TIZEN_ERROR_MULTIMEDIA_CLASS | 0x50
  32
  33 /**
  34  * @file wav_player.h
  35  * @brief This file contains the WAV player API
  36  */
  37
  38 /**
  39  * @addtogroup CAPI_MEDIA_WAV_PLAYER_MODULE
  40  * @{
  41  */
  42
  43 /**
  44  * @brief Enumeration of error codes for WAV player.
  45  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  46  */
  47 typedef enum
  48 {
  49     WAV_PLAYER_ERROR_NONE                 = TIZEN_ERROR_NONE,                  /**< Successful */
  50     WAV_PLAYER_ERROR_INVALID_PARAMETER    = TIZEN_ERROR_INVALID_PARAMETER,     /**< Invalid parameter */
  51     WAV_PLAYER_ERROR_INVALID_OPERATION    = TIZEN_ERROR_INVALID_OPERATION,     /**< Invalid operation */
  52     WAV_PLAYER_ERROR_FORMAT_NOT_SUPPORTED = TIZEN_ERROR_WAV_PLAYER | 0x01,     /**< Format not supported */
  53     WAV_PLAYER_ERROR_NOT_SUPPORTED_TYPE   = TIZEN_ERROR_WAV_PLAYER | 0x02      /**< Not supported (Since 3.0) */
  54 } wav_player_error_e;
  55
  56 /**
  57  * @}
  58  */
  59
  60
  61 /**
  62  * @addtogroup CAPI_MEDIA_WAV_PLAYER_MODULE
  63  * @{
  64  */
  65
  66 /**
  67  * @brief Called when a WAV file has finished playing.
  68  * @details This callback is not invoked by calling wav_player_stop().
  69  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  70  * @param[in] id        The completed wav player ID
  71  * @param[in] user_data The user data passed from the callback registration function
  72  * @see wav_player_start()
  73  */
  74 typedef void (*wav_player_playback_completed_cb)(int id, void *user_data);
  75
  76
  77 /**
  78  * @deprecated Deprecated since 3.0. Use wav_player_start_with_stream_info() instead.
  79  * @brief Plays a WAV file.
  80  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  81  *
  82  * @remarks Sound can be mixed with other sounds if you don't control the sound session in sound-manager module since 3.0.\n
  83  *      You can refer to @ref CAPI_MEDIA_SUOND_MANAGER_MODULE.
  84  *
  85  * @param[in] path      The file path to play
  86  * @param[in] type      The sound type
  87  * @param[in] callback  The callback function to invoke when a WAV file is finished playing
  88  * @param[in] user_data The user data to be passed to the callback function
  89  * @param[out] id       The WAV player ID ( can be set to NULL )
  90  *
  91  * @return @c 0 on success,
  92  *         otherwise a negative error value
  93  * @retval #WAV_PLAYER_ERROR_NONE Successful
  94  * @retval #WAV_PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
  95  * @retval #WAV_PLAYER_ERROR_INVALID_OPERATION Invalid operation
  96  * @retval #WAV_PLAYER_ERROR_FORMAT_NOT_SUPPORTED Not supported format
  97  *
  98  * @post        It invokes wav_player_playback_completed_cb() when a WAV file has finished playing.
  99  * @see wav_player_stop()
 100  * @see wav_player_playback_completed_cb()
 101  */
 102 int wav_player_start(const char *path, sound_type_e type, wav_player_playback_completed_cb callback, void *user_data, int *id);
 103
 104 /**
 105  * @brief Plays a WAV file with stream information of sound-manager.
 106  * @since_tizen 3.0
 107  *
 108  * @remarks Voice Recognition and VOIP stream types are not supported in this API.
 109  *
 110  * @param[in] path      The file path to play
 111  * @param[in] stream_info       The sound stream information handle
 112  * @param[in] callback  The callback function to be invoked when a WAV file is no longer being played
 113  * @param[in] user_data The user data to be passed to the callback function
 114  * @param[out] id       The WAV player ID (can be set to @c NULL)
 115  *
 116  * @return @c 0 on success,
 117  *         otherwise a negative error value
 118  * @retval #WAV_PLAYER_ERROR_NONE Successful
 119  * @retval #WAV_PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 120  * @retval #WAV_PLAYER_ERROR_INVALID_OPERATION Invalid operation
 121  * @retval #WAV_PLAYER_ERROR_FORMAT_NOT_SUPPORTED Not supported format
 122  * @retval #WAV_PLAYER_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
 123  *
 124  * @post        It invokes wav_player_playback_completed_cb() when a WAV file is no longer being played.
 125  * @see wav_player_stop()
 126  * @see wav_player_playback_completed_cb()
 127  * @see sound_manager_create_stream_information()
 128  * @see sound_manager_destroy_stream_information()
 129  */
 130 int wav_player_start_with_stream_info(const char *path, sound_stream_info_h stream_info, wav_player_playback_completed_cb callback, void *user_data, int *id);
 131
 132 /**
 133  * @brief Stops playing the WAV file.
 134  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 135  * @param[in] id        The WAV player ID to stop
 136  *
 137  * @return 0 on success, otherwise a negative error value.
 138  * @retval #WAV_PLAYER_ERROR_NONE Successful
 139  * @retval #WAV_PLAYER_ERROR_INVALID_PARAMETER Invalid parameter
 140  * @retval #WAV_PLAYER_ERROR_INVALID_OPERATION Invalid operation
 141  *
 142  * @see wav_player_start()
 143  */
 144 int wav_player_stop(int id);
 145
 146 /**
 147  * @}
 148  */
 149
 150 #ifdef __cplusplus
 151 }
 152 #endif
 153
 154 #endif /* __TIZEN_MEDIA_WAV_PLAYER_H__ */