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