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