inc/FTextEncoder.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                FTextEncoder.h
  20  * @brief               This is the header file for the %Encoder class.
  21  *
  22  * This header file contains the declarations of the %Encoder class.
  23  *
  24  */
  25 #ifndef _FTEXT_ENCODER_H_
  26 #define _FTEXT_ENCODER_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseBuffer.h>
  31
  32 namespace Tizen { namespace Text
  33 {
  34 /**
  35  * @class       Encoder
  36  * @brief       This class is an implementation of the character encoder.
  37  *
  38  * @since       2.0
  39  *
  40  * The %Encoder class converts blocks of characters to blocks of encoded bytes
  41  * through successive calls to the GetBytesN() method. This class maintains the state consistency information between
  42  * successive calls to %GetBytesN(), enabling it to encode a character into a sequence of bytes,
  43  * such as surrogate pairs, that span adjacent blocks.
  44  *
  45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/text/converting_text_data_separate_blocks.htm">Converting Text Data in Separate Blocks</a>.
  46  */
  47
  48 class _OSP_EXPORT_ Encoder
  49         : public Tizen::Base::Object
  50 {
  51 public:
  52         /**
  53          * This is the destructor for this class. @n
  54          * This destructor overrides Tizen::Base::Object::~Object().
  55          *
  56          * @since       2.0
  57          */
  58         virtual ~Encoder(void) { };
  59
  60         /**
  61          * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
  62          *
  63          * @since                       2.0
  64          *
  65          * @return              An error code
  66          * @param[in]   chars An instance of Tizen::Base::WcharBuffer to encode
  67          * @param[in]   charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
  68          * @param[in] charCount The total number of characters to encode
  69          * @param[in] flush Set to @c true to allow this instance to flush its state at the end of the conversion, @n
  70          *                                              else @c false
  71          * @param[out]  byteCount The total number of bytes required to encode the specified range of characters
  72          * @exception   E_SUCCESS                The method is successful.
  73          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
  74          *                                         the specified @c chars is empty.
  75          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or
  76          *                                                                                 the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
  77          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or
  78          *                                                                                 the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
  79          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
  80          * @see                         Decoder::GetCharCount()
  81          */
  82         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars,
  83                 int charIndex, int charCount, int& byteCount, bool flush = false) const = 0;
  84
  85         /**
  86          * Encodes an instance of the specified Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
  87          *
  88          * @since                       2.0
  89          *
  90          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
  91          *                                              else @c null if an exception occurs @n
  92          *                                              The buffer limit is the position of the last encoded byte plus one in the buffer and the starting position is zero.
  93          * @param[in]   chars An instance of Tizen::Base::WcharBuffer to encode
  94          * @param[in]   flush Set to @c true to allow this instance to flush its state at the end of the conversion, @n
  95          *                              else @c false
  96          * @exception   E_SUCCESS                The method is successful.
  97          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
  98          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
  99          *                                         the specified @c chars is empty.
 100          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 101          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 102          * @see       Decoder::GetCharsN()
 103          */
 104         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars, bool flush = false) const = 0;
 105
 106         /**
 107          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range.
 108          *
 109          * @since                       2.0
 110          *
 111          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 112          *                                      else @c null if an exception occurs @n
 113          *                                              The buffer limit is the position of the last encoded byte in the buffer and the starting position is zero.
 114          * @param[in]   chars An instance of Tizen::Base::WcharBuffer to encode
 115          * @param[in]   charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 116          * @param[in]   charCount The total number of characters to encode
 117          * @param[in] flush Set to @c true to allow this instance to flush its state at the end of the conversion, @n
 118          *                                              else @c false
 119          * @exception   E_SUCCESS                The method is successful.
 120          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 121          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or
 122          *                                         the specified @c chars is empty.
 123          * @exception   E_OUT_OF_RANGE       The value of an argument is outside the valid range defined by the method, or
 124          *                                         the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 125          * @exception   E_UNDERFLOW                  This operation has caused the memory to underflow, or
 126          *                                         the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 127          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 128          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 129          * @remarks             The pointer to the Tizen::Base::ByteBuffer instance is not terminated by a @c null character.
 130          * @see         Decoder::GetCharsN()
 131          */
 132         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 133                 bool flush = false) const = 0;
 134
 135 protected:
 136         Encoder(void)
 137                 : _pEncoderImpl(null){};
 138         friend class _EncoderImpl;
 139         class _EncoderImpl* _pEncoderImpl;
 140
 141 private:
 142         /**
 143          * The implementation of this copy constructor is intentionally blank and declared as private to
 144          * prohibit copying of objects.
 145          */
 146         Encoder(const Encoder& encoder);
 147
 148         /**
 149          * The implementation of this copy assignment operator is intentionally blank and declared as private
 150          * to prohibit copying of objects.
 151          */
 152         Encoder& operator =(const Encoder& encoder);
 153 };
 154
 155 } } // Tizen::Text
 156 #endif //_FTEXT_ENCODER_H_