inc/FMediaTone.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                        FMediaTone.h
  20  * @brief                       This is the header file for the %Tone class.
  21  *
  22  * This header file contains the declarations of the %Tone class.
  23  */
  24
  25 #ifndef _FMEDIA_TONE_H_
  26 #define _FMEDIA_TONE_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FMediaToneTypes.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33
  34 /**
  35  * @class               Tone
  36  * @brief               This class generates a tone.
  37  *
  38  * @since               2.0
  39  *
  40  * @remarks
  41  * The instance of the %Tone class can be played using TonePlayer.
  42  *
  43  * The %Tone class generates a tone and provides methods for:
  44  * - Generating a single tone.
  45  * - Generating dual tones with two different values of frequencies.
  46  * - Generating a silent tone for a specified period of interval.
  47  *
  48  */
  49 class _OSP_EXPORT_ Tone
  50         : public Tizen::Base::Object
  51 {
  52 public:
  53         /**
  54         *       The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
  55         *
  56         *   @since              2.0
  57         *
  58         *       @remarks        After creating an instance of this class, one of the Construct() methods must be called explicitly to initialize this instance.
  59         *       @see            Construct()
  60         */
  61         Tone(void);
  62
  63         /**
  64         *       This destructor overrides Tizen::Base::Object::~Object().
  65         *       The resources are deallocated by this method.
  66         *       This method must be called in the same thread as the Construct() method.
  67         *
  68         *   @since              2.0
  69         *
  70         *       @see            Construct()
  71         */
  72         virtual ~Tone(void);
  73
  74 public:
  75         /**
  76         * @if OSPDEPREC
  77         *       Initializes this instance of %Tone with the values of the specified tone.
  78         *
  79         *     @brief    <i> [Deprecated] </i>
  80         *     @deprecated     This method is deprecated because this method is not used as 2-phase constructor.
  81         *     @since            2.0
  82         *
  83         *       @return         An error code
  84         *       @param[in]      firstFrequency                                  The first frequency of the dual tone in hertz (Hz) @n
  85         *                                               The range of this parameter is @c 0 Hz ~ @c 15000 Hz.
  86         *       @param[in]      secondFrequency                                 The second frequency of the dual tone in hertz (Hz) @n
  87         *                                               The range of this parameter is @c 0 Hz ~ @c 15000 Hz.
  88         *       @param[in]      duration                                                The duration of the tone in milliseconds @n
  89         *                                               The value of this parameter must be greater than @c 0.
  90         *       @exception      E_SUCCESS                                               The method is successful.
  91         *       @exception      E_OUT_OF_RANGE                                  A specified input parameter is out of range.
  92         *       @remarks If both the input frequencies are @c 0 Hz, the tone is set as a silent tone.
  93         * @endif
  94         */
  95         result Construct(int firstFrequency, int secondFrequency, long duration);
  96
  97
  98         /**
  99         * @if OSPDEPREC
 100         *       Initializes this instance of %Tone with the values of the specified DTMF preset tone.
 101         *
 102         *     @brief    <i> [Deprecated] </i>
 103         *       @deprecated     This method is deprecated because this method is not used as 2-phase constructor.
 104         *     @since            2.0
 105         *
 106         *       @return         An error code
 107         *       @param[in]      preset                                                  The preset of the DTMF tone
 108         *       @param[in]      duration                                                The duration of the tone in milliseconds @n
 109         *                                               The value of this parameter must be greater than @c 0.
 110         *       @exception      E_SUCCESS                                               The method is successful.
 111         *       @exception      E_OUT_OF_RANGE                                  A specified input parameter is out of range.
 112         * @endif
 113         */
 114         result Construct(DtmfPreset preset, long duration);
 115
 116
 117         /**
 118         *       Gets the current frequency.
 119         *
 120         *   @since              2.0
 121         *
 122         *       @return         An error code
 123         *       @param[out]     firstFrequency                                  The first frequency of the dual tone in hertz (Hz)
 124         *       @param[out]     secondFrequency                                 The second frequency of the dual tone in hertz (Hz)
 125         *       @exception      E_SUCCESS                                               The method is successful.
 126         *       @remarks The specified input parameters of this method are @c -1 when an exception occurs.
 127         */
 128         result GetFrequency(int& firstFrequency, int& secondFrequency) const;
 129
 130         /**
 131         *       Gets the current duration.
 132         *
 133         *   @since              2.0
 134         *
 135         *       @return         The duration of the tone
 136         *       @remarks This method returns @c 0 before the Construct() method is called.
 137         */
 138         long GetDuration(void) const;
 139
 140         /**
 141  * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 142          *
 143         *   Initializes this instance of %Tone with the values of the specified tone.
 144         *
 145         *   @since              2.0
 146         *
 147         *   @param[in]       firstFrequency    The first frequency of the dual tone in hertz (Hz) @n
 148         *                                          The range of this parameter is @c 0 Hz ~ @c 15000 Hz.
 149         *   @param[in]       secondFrequency   The second frequency of the dual tone in hertz (Hz) @n
 150         *                                      The range of this parameter is @c 0 Hz ~ @c 15000 Hz.
 151         *   @param[in]       duration          The duration of the tone in milliseconds @n
 152         *                                          The value of this parameter must be greater than @c 0.
 153         *   @remarks If both the input frequencies are @c 0 Hz, the tone is set as a silent tone.
 154         */
 155         Tone(int firstFrequency, int secondFrequency, long duration);
 156
 157         /**
 158          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 159         * Initializes this instance of %Tone with the values of the specified DTMF preset tone.
 160         *
 161         * @since                2.0
 162         *
 163         * @param[in]       preset              The preset of the DTMF tone
 164         * @param[in]       duration            The duration of the tone in milliseconds @n
 165         *                                          The value of this parameter must be greater than @c 0.
 166         */
 167         Tone(DtmfPreset preset, long duration);
 168
 169         /**
 170         * Compares the specified instance of %Tone with the calling instance.
 171         *
 172         * @since                2.0
 173         *
 174         * @return             @c true if the values match, @n
 175         *                     else @c false
 176         * @param[in]    rhs   The other Object to be compared
 177         * @see                Object::Equals()
 178         */
 179         virtual bool Equals(const Object& rhs) const;
 180
 181         /**
 182         * Gets the hash value of the current instance.
 183         *
 184         * @since                2.0
 185         *
 186         * @return            The current instance's hash value
 187         */
 188         virtual int GetHashCode(void) const;
 189
 190         /**
 191         * Copying of objects using this copy constructor is allowed.
 192         *
 193         * @since                2.0
 194         *
 195         * @return               The copy of this instance
 196         * @param[in]    rhs     An instance of %Tone
 197         */
 198         Tone(const Tone& rhs);
 199
 200         /**
 201          * Copying of objects using this copy assignment operator is allowed.
 202          *
 203          * @since               2.0
 204          *
 205          * @return              The reference of this instance
 206          * @param[in]   rhs     An instance of %Tone
 207          */
 208         Tone& operator =(const Tone& rhs);
 209
 210 private:
 211         int __firstFrequency;
 212         int __secondFrequency;
 213         long __duration;
 214         bool __isConstructed;
 215 };
 216
 217 }} // Tizen::Media
 218
 219 #endif