inc/FTextEncoding.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   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  * @file                FTextEncoding.h
  19  * @brief               This is the header file for the %Encoding class.
  20  *
  21  * This header file contains the declarations of the %Encoding class. @n
  22  * This class is the base class for all character encoding classes.
  23  */
  24 #ifndef _FTEXT_ENCODING_H_
  25 #define _FTEXT_ENCODING_H_
  26
  27 // Include
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseBuffer.h>
  31 #include <FBaseColIList.h>
  32 #include <FBaseString.h>
  33 #include <FTextEncoder.h>
  34 #include <FTextDecoder.h>
  35
  36
  37 namespace Tizen { namespace Text
  38 {
  39
  40 /**
  41  * @class       Encoding
  42  * @brief       This class implements character encoding.
  43  *
  44  * @since       2.0
  45  *
  46  * The %Encoding class is the base class for all classes that implement character encoding.
  47  *
  48  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/text/converting_all_text_data.htm">Converting All Text Data at Once</a>.
  49  *
  50  * For more information on the supported encoding types, see <a href="../org.tizen.native.appprogramming/html/guide/text/text.htm">Encoding standards in %Tizen</a>.
  51  *
  52  * The following example demonstrates how to use the %Encoding class.
  53  *
  54  *      @code
  55  *      #include <FBase.h>
  56  *      #include <FText.h>
  57  *
  58  *      using namespace Tizen::Base;
  59  *      using namespace Tizen::Text;
  60  *
  61  *      void
  62  *      MyClass::EncodingSample(void)
  63  *      {
  64  *              Encoding* pEnc = Encoding::GetEncodingN(L"ISO-8859-2");
  65  *
  66  *              String str(L"Encoding Test \u0104\u02D8");
  67  *
  68  *              int byteCount;
  69  *              pEnc->GetByteCount(str, byteCount);
  70  *
  71  *              // Encodes
  72  *              ByteBuffer* pBuffer = pEnc->GetBytesN(str);
  73  *
  74  *              int charCount;
  75  *              pEnc->GetCharCount(*pBuffer, charCount);
  76  *
  77  *              // Decodes
  78  *              String decodedStr;
  79  *              pEnc->GetString(*pBuffer, decodedStr);
  80  *
  81  *              if (str.Equals(decodedStr))
  82  *              {
  83  *                      //....
  84  *              }
  85  *
  86  *              delete pBuffer;
  87  *
  88  *              delete pEnc;
  89  *      }
  90  *  @endcode
  91  */
  92
  93 class AsciiEncoding;
  94 class Utf8Encoding;
  95 class Ucs2Encoding;
  96 class Latin1Encoding;
  97 class GsmEncoding;
  98
  99 class _OSP_EXPORT_ Encoding
 100         : public Tizen::Base::Object
 101 {
 102 public:
 103         /**
 104          * This is the destructor for this class. @n
 105          * This destructor overrides Tizen::Base::Object::~Object().
 106          *
 107          * @since       2.0
 108          */
 109         virtual ~Encoding(void);
 110
 111         /**
 112          * Gets the total number of bytes that are required to encode the specified string.
 113          *
 114          * @since                       2.0
 115          *
 116          * @return              An error code
 117          * @param[in]   str                      The string to encode
 118          * @param[out]  byteCount                The total number of bytes that are required to encode the specified string
 119          * @exception   E_SUCCESS                The method is successful.
 120          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c str is an empty string.
 121          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 122          * @remarks     This method determines the total number of bytes
 123          *              that are generated when the specified string is encoded.
 124          * @see         GetMaxByteCount()
 125          */
 126         virtual result GetByteCount(const Tizen::Base::String& str, int& byteCount) const;
 127
 128         /**
 129          * Gets the total number of bytes that are required to encode the specified characters.
 130          *
 131          * @since                       2.0
 132          *
 133          * @return              An error code
 134          * @param[in]   chars                    An instance of Tizen::Base::WcharBuffer to encode
 135          * @param[out]  byteCount                The total number of bytes required to encode the specified range of characters
 136          * @exception   E_SUCCESS                The method is successful.
 137          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c chars is empty.
 138          * @exception   E_INVALID_ENCODING_RANGE    The specified string contains code points that are outside the bounds of the character encoding scheme.
 139          * @remarks     This method determines the total number of bytes
 140          *              that are generated when the specified array of characters are encoded.
 141          * @see         GetMaxByteCount()
 142          * @see         GetByteCount()
 143          */
 144         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int& byteCount) const;
 145
 146         /**
 147          * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
 148          *
 149          * @since                       2.0
 150          *
 151          * @return              An error code
 152          * @param[in]   chars                An instance of Tizen::Base::WcharBuffer to encode
 153          * @param[in]   charIndex            The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 154          * @param[in]   charCount              The total number of characters to encode
 155          * @param[out]  byteCount            The total number of bytes that are required to encode the specified range of characters
 156          * @exception   E_SUCCESS            The method is successful.
 157          * @exception   E_INVALID_ARG        A specified input parameter is invalid, or the specified @c chars is empty.
 158          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 159          * @exception   E_UNDERFLOW          This operation has caused the memory to underflow, or the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 160          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 161          * @remarks     This method determines the total number of bytes
 162          *              that are generated when the specified array of characters are encoded.
 163          * @see                 GetMaxByteCount()
 164          * @see                 GetByteCount()
 165          */
 166         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 167                 int& byteCount) const;
 168
 169         /**
 170          * Encodes an instance of specified Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
 171          *
 172          * @since                       2.0
 173          *
 174          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 175          *                              else @c null if an exception occurs @n
 176          *                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 177          * @param[in]   chars                An instance of Tizen::Base::WcharBuffer to encode
 178          * @exception   E_SUCCESS                The method is successful.
 179          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 180          * @exception   E_INVALID_ARG            The specified @c chars is invalid or empty.
 181          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 182          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 183          * @see                 GetCharsN()
 184          * @see                 GetBytesN()
 185          */
 186         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const = 0;
 187
 188         /**
 189          * Encodes the specified string of type Tizen::Base::String to Tizen::Base::ByteBuffer.
 190          *
 191          * @since                       2.0
 192          *
 193          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 194          *                              else @c null if an exception occurs @n
 195          *                              The buffer limit is the position of the last encoded byte plus one and the position is zero.
 196          * @param[in]   str                  The string to encode
 197          * @exception   E_SUCCESS                The method is successful.
 198          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 199          * @exception   E_INVALID_ARG            The specified @c str is invalid or is an empty string.
 200          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 201          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 202          * @see                 GetString()
 203          */
 204         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const = 0;
 205
 206         /**
 207          * Encodes an instance of the specified Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 208          * The position and limit of the %Tizen::Base::ByteBuffer instance is not changed.
 209          *
 210          * @since                       2.0
 211          *
 212          * @return              An error code
 213      * @param[in]       chars                                                   The buffer containing the character array to encode
 214          * @param[in]   charIndex                                       The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 215          * @param[in]   charCount                                       The total number of characters to encode
 216          * @param[out]  bytes                                           The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 217          * @param[in]   byteIndex                                       The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 218          * @exception   E_SUCCESS                                       The method is successful.
 219          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 220          * @exception   E_INVALID_ARG                           A specified input parameter is invalid, or the specified @c chars or @c bytes is empty.
 221          * @exception   E_OUT_OF_RANGE                          The value of an argument is outside the valid range defined by the method, or the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c chars.
 222          * @exception   E_UNDERFLOW                                     This operation has caused the memory to underflow, or the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c chars.
 223          * @exception   E_OVERFLOW                                      This operation has caused the memory to overflow, or the specified @c bytes does not contain sufficient space to store the encoded characters.
 224          * @exception   E_INVALID_ENCODING_RANGE        The specified string contains code points that are outside the bounds of the character encoding scheme.
 225          * @remarks             This method encodes a range of characters in Tizen::Base::WcharBuffer into a range of bytes in Tizen::Base::ByteBuffer.
 226          * @see                 GetChars()
 227          */
 228         virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 229                 Tizen::Base::ByteBuffer& bytes, int byteIndex) const = 0;
 230
 231         /**
 232          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 233          * The position and limit of the %Tizen::Base::ByteBuffer instance is not changed.
 234          *
 235          * @since                       2.0
 236          *
 237          * @return              An error code
 238          * @param[in]   str                     The string to encode
 239          * @param[in]   charIndex               The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 240          * @param[in]   charCount                 The total number of characters to encode
 241          * @param[out]  bytes                   The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 242          * @param[in]   byteIndex                 The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 243          * @exception   E_SUCCESS                The method is successful.
 244          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 245          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c str or @c bytes is empty.
 246          * @exception   E_OUT_OF_RANGE                   The value of an argument is outside the valid range defined by the method, or the length of the specified @c charIndex or @c charCount is greater than the length of the specified @c str.
 247          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or the sum of the length of the specified @c charIndex and @c charCount is greater than the length of the specified @c str.
 248          * @exception   E_OVERFLOW               This operation has caused the memory to overflow, or the specified @c bytes does not contain sufficient space to store the encoded characters.
 249          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 250          * @see                 GetString()
 251          */
 252         virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
 253                 Tizen::Base::ByteBuffer& bytes, int byteIndex) const = 0;
 254
 255         /**
 256          * Gets the total number of characters that are generated by decoding an instance of Tizen::Base::ByteBuffer.
 257          *
 258          * @since                       2.0
 259          *
 260          * @return              An error code
 261          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 262          * @param[out]  charCount                The total number of characters that are generated by decoding a range of bytes in the specified Tizen::Base::ByteBuffer instance
 263          * @exception   E_SUCCESS                The method is successful.
 264          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 265          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c bytes is empty.
 266          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 267          * @remarks     This method determines the total number of characters
 268          *              that are generated when the specified range of bytes are encoded.
 269          * @see                 GetMaxCharCount()
 270          * @see                 GetCharCount()
 271          */
 272         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int& charCount) const;
 273
 274         /**
 275          * Gets the total number of characters that are generated by decoding a range of elements specified in the Tizen::Base::ByteBuffer instance.
 276          *
 277          * @since                       2.0
 278          *
 279          * @return              An error code
 280          * @param[in]   bytes                 An instance of Tizen::Base::ByteBuffer to decode
 281          * @param[in]   byteIndex             The index from where decoding begins
 282          * @param[in]   byteCount             The total number of bytes to decode
 283          * @param[out]  charCount             The total number of characters that are generated by decoding a range of bytes in the specified Tizen::Base::ByteBuffer instance
 284          * @exception   E_SUCCESS             The method is successful.
 285          * @exception   E_OUT_OF_MEMORY       The memory is insufficient.
 286          * @exception   E_INVALID_ARG         A specified input parameter is invalid, or the specified @c bytes is empty.
 287          * @exception   E_OUT_OF_RANGE        The value of an argument is outside the valid range defined by the method, or the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
 288          * @exception   E_UNDERFLOW           This operation has caused the memory to underflow, or the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
 289          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 290          * @remarks     This method determines the total number of characters
 291          *              that are generated when the specified range of bytes are encoded.
 292          * @see                 GetMaxCharCount()
 293          * @see                 GetCharCount()
 294          */
 295         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, int& charCount) const;
 296
 297         /**
 298          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
 299          *
 300          * @since                       2.0
 301          *
 302          * @return              A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
 303          *                              else @c null if an exception occurs @n
 304          *                              The buffer limit is the position of the last decoded byte plus one and the starting position is zero.
 305          * @param[in]   bytes               An instance of Tizen::Base::ByteBuffer to decode
 306          * @exception   E_SUCCESS                The method is successful.
 307          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 308          * @exception   E_INVALID_ARG            The specified @c bytes is invalid or empty.
 309          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 310          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 311          * @see                 GetBytesN()
 312          */
 313         virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const = 0;
 314
 315         /**
 316          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
 317          * The position and limit of the %Tizen::Base::WcharBuffer instance is not changed.
 318          *
 319          * @since                       2.0
 320          *
 321          * @return              An error code
 322          * @param[in]   bytes                 An instance of Tizen::Base::ByteBuffer to decode
 323          * @param[in]   byteIndex             The index from where decoding begins
 324          * @param[in]   byteCount             The total number of bytes to decode
 325          * @param[out]  chars                 The Tizen::Base::WcharBuffer instance where the resultant decoded data is stored
 326          * @param[in]   charIndex             The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 327          * @exception   E_SUCCESS                The method is successful.
 328          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 329          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c bytes is empty.
 330          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
 331          * @exception   E_UNDERFLOW                  This operation has caused the memory to underflow, or the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
 332          * @exception   E_OVERFLOW                   This operation has caused the memory to overflow, or the specified @c chars does not contain sufficient space to store the decoded bytes.
 333          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 334          * @see                 GetBytes()
 335          */
 336         virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
 337                 Tizen::Base::WcharBuffer& chars, int charIndex) const = 0;
 338
 339         /**
 340          * Gets a string that contains the decoded representation of a range of bytes in the specified Tizen::Base::ByteBuffer instance.
 341          *
 342          * @since                       2.0
 343          *
 344          * @return              An error code
 345          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 346          * @param[out]  str                      A Tizen::Base::String instance @n
 347          *                                       It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 348          * @exception   E_SUCCESS                The method is successful.
 349          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 350          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c bytes is empty.
 351          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 352          *
 353          * @see                 GetBytesN()
 354          * @see                 GetString()
 355          */
 356         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const = 0;
 357
 358         /**
 359          * Gets a string that contains the decoded representation of a range of bytes in the specified Tizen::Base::ByteBuffer instance.
 360          *
 361          * @since                       2.0
 362          *
 363          * @return              An error code
 364          * @param[in]   bytes                    An instance of Tizen::Base::ByteBuffer to decode
 365          * @param[in]   index                    The index from where decoding begins
 366          * @param[in]   count                    The total number of bytes to decode
 367          * @param[out]  str                     A Tizen::Base::String instance @n
 368          *                                      It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 369          * @exception   E_SUCCESS                The method is successful.
 370          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 371          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c bytes is empty.
 372          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 373          * @exception   E_UNDERFLOW                              This operation has caused the memory to underflow, or the sum of the length of the specified @c index and @c count is greater than the length of the specified @c bytes.
 374          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 375          * @see                 GetBytes()
 376          * @see                 GetString()
 377          */
 378         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const = 0;
 379
 380         /**
 381          * Gets the maximum number of bytes that are required to encode the specified number of characters.
 382          *
 383          * @since                       2.0
 384          *
 385          * @return              The maximum number of bytes that are required to encode the specified number of characters
 386          * @param[in]   charCount     The total number of characters to encode
 387          * @remarks     This method determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
 388          * @see                 GetByteCount()
 389          * @see                 GetBytes()
 390          */
 391         virtual int GetMaxByteCount(int charCount) const = 0;
 392
 393         /**
 394          * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
 395          *
 396          * @since               2.0
 397          *
 398          * @return              The maximum number of characters that are generated by decoding the specified number of bytes
 399          * @param[in]   byteCount The total number of bytes to encode
 400          * @remarks      This method determines an appropriate buffer size for character arrays passed to
 401          *                  GetChars() or a decoder for encoding.
 402          * @see                 GetCharCount()
 403          * @see                 GetChars()
 404          */
 405         virtual int GetMaxCharCount(int byteCount) const = 0;
 406
 407         /**
 408          * Gets the encoder for the current encoding.
 409          *
 410          * @since                       2.0
 411          *
 412          * @return              A pointer to the Encoder instance for the current encoding
 413          * @remarks     Contrary to GetBytes(), an encoder can convert partial sequences of characters into
 414          *              partial sequences of bytes by maintaining an appropriate state between the conversions.
 415          *              Currently, only UTF-8 encoding supports this method. The other classes return a value of @c null.
 416          * @see                 GetBytes()
 417          */
 418         virtual Encoder* GetEncoderN(void) const = 0;
 419
 420         /**
 421          * Gets the decoder for the current encoding.
 422          *
 423          * @since                       2.0
 424          *
 425          * @return              A pointer to the Decoder instance for the current encoding
 426          * @remarks     Contrary to GetChars(), a decoder can convert partial sequences of bytes
 427          *              into partial sequences of characters by maintaining an appropriate state between the conversions.
 428          *              Currently, only UTF-8 encoding supports this method. The other classes return a value of @c null.
 429          * @see                 GetChars()
 430          */
 431         virtual Decoder* GetDecoderN(void) const = 0;
 432
 433         /**
 434          * Gets the encoding type of the current instance.
 435          *
 436          * @since                       2.0
 437          *
 438          * @return              An encoding type
 439          */
 440         virtual Tizen::Base::String GetEncodingType(void) const = 0;
 441
 442         /**
 443         * Gets an encoding for the UTF-8 format.
 444         *
 445         * @since                        2.0
 446         *
 447         * @return               An encoding for the UTF-8 format
 448         *
 449         * @see                          Tizen::Text::Utf8Encoding
 450         */
 451         static Utf8Encoding& GetUtf8Encoding(void);
 452
 453         /**
 454         * Gets an encoding for the UCS-2 format.
 455         *
 456         * @since                        2.0
 457         *
 458         * @return               An encoding for the UCS-2 format
 459         -*
 460         * @see                          Tizen::Text::Ucs2Encoding
 461         */
 462         static Ucs2Encoding& GetUcs2Encoding(void);
 463
 464         /**
 465         * Gets an encoding for the GSM format.
 466         *
 467         * @since                        2.0
 468         *
 469         * @return               An encoding for the GSM format
 470         *
 471         * @see                          Tizen::Text::GsmEncoding
 472         */
 473         static GsmEncoding& GetGsmEncoding(void);
 474
 475         /**
 476         * Gets an encoding for the Latin1 format.
 477         *
 478         * @since                        2.0
 479         *
 480         * @return               An encoding for the Latin1 format
 481         *
 482         * @see                          Tizen::Text::Latin1Encoding
 483         */
 484         static Latin1Encoding& GetLatin1Encoding(void);
 485
 486         /**
 487         * Gets an encoding for the ASCII format.
 488         *
 489         * @since                        2.0
 490         *
 491         * @return               An encoding for the ASCII format
 492         *
 493         * @see                          Tizen::Text::AsciiEncoding
 494         */
 495         static AsciiEncoding& GetAsciiEncoding(void);
 496
 497         /**
 498          * Gets an %Encoding instance from the specified encoding type.
 499          *
 500          * @since                       2.0
 501          *
 502          * @return    An instance of %Encoding, @n
 503          *                else @c null if the method fails
 504          * @param[in]   encodingType    An encoding type
 505          * @exception   E_SUCCESS                               The method is successful.
 506          * @exception   E_UNSUPPORTED_TYPE      The specified encoding type is not supported.
 507          * @remarks             The specific error code can be accessed using the GetLastResult() method. @n
 508          *                      The supported encoding types are ASCII, GSM, UCS-2, UCS-2LE, UCS-2BE, UCS-4, UCS-4LE, UCS-4BE, UTF-8, UTF-16, UTF-16LE, UTF-16BE, @n
 509          *                              UTF-32, UTF-32LE, UTF-32BE, ISO-8859-1~16 (except ISO-8859-12), Windows-874, Windows-1250 ~ Windows-1258, @n
 510          *                              KSC5601, BIG5, GB2312, Shift-JIS and ISO-2022-JP. @n
 511          *                              For more information on the supported encoding types, see <a href="../org.tizen.native.appprogramming/html/guide/text/text.htm">Encoding standards in %Tizen</a>.
 512          * @see                 Tizen::Text::Encoding::GetAvailableEncodingsN()
 513          */
 514         static Encoding* GetEncodingN(const Tizen::Base::String& encodingType);
 515
 516         /**
 517         * Gets the encoding type of the specified %Encoding instance.
 518         *
 519         * @since                        2.0
 520         *
 521         * @return               An encoding type
 522         * @param[in] encoding An instance of %Encoding
 523         */
 524         static Tizen::Base::String GetEncodingType(const Encoding& encoding);
 525
 526         /**
 527          * Gets a list of all the available encodings.
 528          *
 529          * @since                       2.0
 530          *
 531          * @return              A list of Tizen::Base::String instances (ASCII, UTF-8, ISO-8859-1, ISO-8859-2, Windows-1254, and so on), @n
 532          *              else @c null if the method fails
 533          * @exception   E_SUCCESS                               The method is successful.
 534          * @exception   E_SYSTEM                                A system error has occurred.
 535          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 536          */
 537         static Tizen::Base::Collection::IList* GetAvailableEncodingsN(void);
 538
 539         /**
 540          * Converts an instance of Tizen::Base::ByteBuffer from one encoding format to another.
 541          *
 542          * @since                       2.0
 543          *
 544          * @return              A new buffer for storing the result of the conversion, @n
 545          *                              else @c null if an exception occurs @n
 546          *                                  The buffer limit is the position of the last converted byte plus one and the starting position is zero.
 547          * @param[in]   src                      The source of the encoding
 548          * @param[in]   dst                      The destination of the encoding
 549          * @param[in]   srcBytes                 The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 550          * @exception   E_SUCCESS                The method is successful.
 551          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 552          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c srcBytes is empty.
 553          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 554          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 555          * @see                 GetBytes()
 556          * @see                 GetChars()
 557          */
 558         static Tizen::Base::ByteBuffer* ConvertN(const Encoding& src, const Encoding& dst,
 559                 const Tizen::Base::ByteBuffer& srcBytes);
 560
 561         /**
 562          * Converts a range of bytes in the Tizen::Base::ByteBuffer instance from one encoding format to another.
 563          *
 564          * @since                       2.0
 565          *
 566          * @return              A new buffer for storing result of the conversion, @n
 567          *                              else @c null if an exception occurs @n
 568          *                                              The buffer limit is the position of the last converted byte plus one and the starting position is zero.
 569          * @param[in]   src                      The source of the encoding
 570          * @param[in]   dst                      The destination of the encoding
 571          * @param[in]   srcBytes                 The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 572          * @param[in]   index                    The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 573          * @param[in]   count                    The total number of bytes to convert
 574          * @exception   E_SUCCESS                The method is successful.
 575          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 576          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c srcBytes is empty.
 577          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method, or the specified @c index or @c count is greater than the length of the specified @c srcBytes.
 578          * @exception   E_UNDERFLOW              This operation has caused the memory to underflow, or the sum of the length of the specified @c index and @c count is greater than the length of the specified @c srcBytes.
 579          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 580          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 581          * @see                 GetBytes()
 582          * @see                 GetChars()
 583          */
 584         static Tizen::Base::ByteBuffer* ConvertN(const Encoding& src, const Encoding& dst, const Tizen::Base::ByteBuffer& srcBytes,
 585                 int index, int count);
 586
 587 protected:
 588         Encoding(void);
 589
 590         //
 591         // This method is for internal use only. Using this method can cause behavioral, security-related,
 592         // and consistency-related issues in the application.
 593         //
 594         // This method is reserved and may change its name at any time without prior notice.
 595         //
 596         // @since       2.0
 597         //
 598         virtual void Encoding_Reserved1(void) { }
 599
 600         //
 601         // This method is for internal use only. Using this method can cause behavioral, security-related,
 602         // and consistency-related issues in the application.
 603         //
 604         // This method is reserved and may change its name at any time without prior notice.
 605         //
 606         // @since       2.0
 607         //
 608         virtual void Encoding_Reserved2(void) { }
 609
 610         //
 611         // This method is for internal use only. Using this method can cause behavioral, security-related,
 612         // and consistency-related issues in the application.
 613         //
 614         // This method is reserved and may change its name at any time without prior notice.
 615         //
 616         // @since       2.0
 617         //
 618         virtual void Encoding_Reserved3(void) { }
 619
 620         //
 621         // This method is for internal use only. Using this method can cause behavioral, security-related,
 622         // and consistency-related issues in the application.
 623         //
 624         // This method is reserved and may change its name at any time without prior notice.
 625         //
 626         // @since       2.0
 627         //
 628         virtual void Encoding_Reserved4(void) { }
 629
 630         //
 631         // This method is for internal use only. Using this method can cause behavioral, security-related,
 632         // and consistency-related issues in the application.
 633         //
 634         // This method is reserved and may change its name at any time without prior notice.
 635         //
 636         // @since       2.0
 637         //
 638         virtual void Encoding_Reserved5(void) { }
 639
 640         friend class _EncodingImpl;
 641         class _EncodingImpl* _pEncodingImpl;
 642
 643 private:
 644         /**
 645          * The implementation of this copy constructor is intentionally blank and declared as private to
 646          * prohibit copying of objects.
 647          */
 648         Encoding(const Encoding& encoding);
 649
 650         /**
 651          * The implementation of this copy assignment operator is intentionally blank and declared as private
 652          * to prohibit copying of objects.
 653          */
 654         Encoding& operator =(const Encoding& encoding);
 655
 656 }; // Encoding
 657
 658 } } // Tizen::Text
 659
 660 #endif //_FTEXT_ENCODING_H_