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         */
  60         Tone(void);
  61
  62         /**
  63         *       This destructor overrides Tizen::Base::Object::~Object(). @n
  64         *       The resources are deallocated by this method.
  65         *       This method must be called in the same thread as the Construct() method.
  66         *
  67         *   @since              2.0
  68         *
  69         *       @see            Construct()
  70         */
  71         virtual ~Tone(void);
  72
  73 public:
  74         /**
  75         * @if OSPDEPREC
  76          *      Initializes this instance of %Tone with the values of the specified tone.
  77         *
  78         *     @brief    <i> [Deprecated] </i>
  79         *     @deprecated     This method is deprecated because this method is not used as 2-phase constructor.
  80         *     @since            2.0
  81         *
  82         *       @return         An error code
  83         *       @param[in]      firstFrequency                                  The first frequency of the dual tone in Hertz (Hz) @n
  84         *                                               The range of this parameter is @c 0 Hz to @c 15000 Hz.
  85         *       @param[in]      secondFrequency                                 The second frequency of the dual tone in Hertz (Hz) @n
  86         *                                               The range of this parameter is @c 0 Hz to @c 15000 Hz.
  87         *       @param[in]      duration                                                The duration of the tone in milliseconds @n
  88         *                                               The value of this parameter must be greater than @c 0.
  89         *       @exception      E_SUCCESS                                               The method is successful.
  90         *       @exception      E_OUT_OF_RANGE                                  A specified input parameter is out of range.
  91         *       @remarks If both the input frequencies are @c 0 Hz, the tone is set as a silent tone.
  92         * @endif
  93         */
  94         result Construct(int firstFrequency, int secondFrequency, long duration);
  95
  96
  97         /**
  98         * @if OSPDEPREC
  99         *       Initializes this instance of %Tone with the values of the specified DTMF preset tone.
 100         *
 101         *     @brief    <i> [Deprecated] </i>
 102         *       @deprecated     This method is deprecated because this method is not used as 2-phase constructor.
 103         *     @since            2.0
 104         *
 105         *       @return         An error code
 106         *       @param[in]      preset                                                  The preset of the DTMF tone
 107         *       @param[in]      duration                                                The duration of the tone in milliseconds @n
 108         *                                               The value of this parameter must be greater than @c 0.
 109         *       @exception      E_SUCCESS                                               The method is successful.
 110         *       @exception      E_OUT_OF_RANGE                                  A specified input parameter is out of range.
 111         * @endif
 112         */
 113         result Construct(DtmfPreset preset, long duration);
 114
 115
 116         /**
 117         *       Gets the current frequency.
 118         *
 119         *   @since              2.0
 120         *
 121         *       @return         An error code
 122         *       @param[out]     firstFrequency                                  The first frequency of the dual tone in Hertz (Hz)
 123         *       @param[out]     secondFrequency                                 The second frequency of the dual tone in Hertz (Hz)
 124         *       @exception      E_SUCCESS                                               The method is successful.
 125         *       @remarks The specified input parameters of this method are @c -1 when an exception occurs.
 126         */
 127         result GetFrequency(int& firstFrequency, int& secondFrequency) const;
 128
 129         /**
 130         *       Gets the current duration.
 131         *
 132         *   @since              2.0
 133         *
 134         *       @return         The duration of the tone
 135         *       @remarks This method returns @c 0 before the Construct() method is called.
 136         */
 137         long GetDuration(void) const;
 138
 139         /**
 140         * 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. @n
 141         *
 142         *   Initializes this instance of %Tone with the values of the specified tone.
 143         *
 144         *   @since              2.0
 145         *
 146         *   @param[in]       firstFrequency    The first frequency of the dual tone in Hertz (Hz) @n
 147         *                                          The range of this parameter is @c 0 Hz to @c 15000 Hz.
 148         *   @param[in]       secondFrequency   The second frequency of the dual tone in Hertz (Hz) @n
 149         *                                      The range of this parameter is @c 0 Hz to @c 15000 Hz.
 150         *   @param[in]       duration          The duration of the tone in milliseconds @n
 151         *                                          The value of this parameter must be greater than @c 0.
 152         *   @remarks If both the input frequencies are @c 0 Hz, the tone is set as a silent tone.
 153         */
 154         Tone(int firstFrequency, int secondFrequency, long duration);
 155
 156         /**
 157          * 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. @n
 158         * Initializes this instance of %Tone with the values of the specified DTMF preset tone.
 159         *
 160         * @since                2.0
 161         *
 162         * @param[in]       preset              The preset of the DTMF tone
 163         * @param[in]       duration            The duration of the tone in milliseconds @n
 164         *                                          The value of this parameter must be greater than @c 0.
 165         */
 166         Tone(DtmfPreset preset, long duration);
 167
 168         /**
 169         * Compares the specified instance of %Tone with the calling instance.
 170         *
 171         * @since                2.0
 172         *
 173         * @return             @c true if the values match, @n
 174         *                     else @c false
 175         * @param[in]    rhs   The other Tizen::Base::Object to compare
 176         * @see                Tizen::Base::Object::Equals()
 177         */
 178         virtual bool Equals(const Object& rhs) const;
 179
 180         /**
 181         * Gets the hash value of the current instance.
 182         *
 183         * @since                2.0
 184         *
 185         * @return            The hash value of the current instance
 186         */
 187         virtual int GetHashCode(void) const;
 188
 189         /**
 190         * Copying of objects using this copy constructor is allowed.
 191         *
 192         * @since                2.0
 193         *
 194         * @return               The copy of this instance
 195         * @param[in]    rhs     An instance of %Tone
 196         */
 197         Tone(const Tone& rhs);
 198
 199         /**
 200          * Copying of objects using this copy assignment operator is allowed.
 201          *
 202          * @since               2.0
 203          *
 204          * @return              The reference of this instance
 205          * @param[in]   rhs     An instance of %Tone
 206          */
 207         Tone& operator =(const Tone& rhs);
 208
 209 private:
 210         int __firstFrequency;
 211         int __secondFrequency;
 212         long __duration;
 213         bool __isConstructed;
 214 };
 215
 216 }} // Tizen::Media
 217
 218 #endif