inc/FTextGsmEncoding.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                FTextGsmEncoding.h
  20  * @brief               This is the header file for the %GsmEncoding class.
  21  *
  22  * This header file contains the declarations of the %GsmEncoding class.
  23  * The %GsmEncoding class is derived from the Encoding class.
  24  */
  25 #ifndef _FTEXT_GSM_ENCODING_H_
  26 #define _FTEXT_GSM_ENCODING_H_
  27
  28 #include <FTextEncoding.h>
  29
  30
  31 namespace Tizen { namespace Text
  32 {
  33 /**
  34  * @class       GsmEncoding
  35  * @brief       This class is an implementation of the GSM character encoding.
  36  *
  37  * @since       2.0
  38  *
  39  * @final       This class is not intended for extension.
  40  *
  41  * The %GsmEncoding class is an implementation of the GSM character encoding.
  42  * The Global System for Mobile Communications (GSM) consists of 128 European characters. It supports a 7-bit
  43  * default alphabet extension table for encoding. It is a target-dependent encoding type.
  44  *
  45  * 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>.
  46  *
  47  * The following example demonstrates how to use the %GsmEncoding class.
  48  *
  49  *      @code
  50  *      #include <FBase.h>
  51  *      #include <FText.h>
  52  *
  53  *      using namespace Tizen::Base;
  54  *      using namespace Tizen::Text;
  55  *
  56  *      void
  57  *      MyClass::GsmEncodingSample(void)
  58  *      {
  59  *              GsmEncoding gsm;
  60  *
  61  *              String str(L"GSM Encoding test");
  62  *
  63  *              int byteCount;
  64  *              gsm.GetByteCount(str, byteCount);
  65  *
  66  *              // Encodes
  67  *              ByteBuffer* pBuffer = gsm.GetBytesN(str);
  68  *
  69  *              int charCount;
  70  *              gsm.GetCharCount(*pBuffer, charCount);
  71  *
  72  *              // Decodes
  73  *              String decodedStr;
  74  *              gsm.GetString(*pBuffer, decodedStr);
  75  *
  76  *              if (str.Equals(decodedStr))
  77  *              {
  78  *                      //....
  79  *              }
  80  *
  81  *              delete pBuffer;
  82  *      }
  83  *  @endcode
  84  */
  85
  86 class _OSP_EXPORT_ GsmEncoding
  87         : public Encoding
  88 {
  89 public:
  90         /**
  91          * This is the default constructor for this class.
  92          *
  93          * @since       2.0
  94          *
  95          */
  96         GsmEncoding(void);
  97
  98         /**
  99          * This is the destructor for this class. @n
 100          * This destructor overrides Tizen::Text::Encoding::~Encoding().
 101          *
 102          * @since       2.0
 103          */
 104         virtual ~GsmEncoding(void);
 105
 106         /**
 107          * Gets the total number of bytes that are required to encode a specified Tizen::Base::String instance.
 108          *
 109          * @since                       2.0
 110          *
 111          * @return              An error code
 112          * @param[in]   str                     A string to encode
 113          * @param[out]  byteCount               The total number of bytes required to encode the specified string
 114          * @exception   E_SUCCESS                The method is successful.
 115          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c str is empty.
 116          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 117          * @remarks     This method determines the total number of bytes
 118          *              that are generated when the specified string is encoded.
 119          * @see         GetMaxByteCount()
 120          */
 121         virtual result GetByteCount(const Tizen::Base::String& str, int& byteCount) const;
 122
 123         /**
 124          * Gets the total number of bytes that are required to encode a specified Tizen::Base::WcharBuffer instance.
 125          *
 126          * @since                       2.0
 127          *
 128          * @return              An error code
 129          * @param[in]   chars                 An instance of Tizen::Base::WcharBuffer to encode
 130          * @param[out]  byteCount             The total number of bytes required to encode the specified range of characters
 131          * @exception   E_SUCCESS                The method is successful.
 132          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c chars is empty.
 133          * @exception   E_INVALID_ENCODING_RANGE  The specified string contains code points that are outside the bounds of the character encoding scheme.
 134          * @remarks     This method determines the total number of bytes
 135          *              that are generated when the specified array of characters is encoded.
 136          * @see         GetMaxByteCount()
 137          */
 138         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int& byteCount) const;
 139
 140         /**
 141          * Gets the total number of bytes that are required to encode a range of characters in the specified Tizen::Base::WcharBuffer instance.
 142          *
 143          * @since                       2.0
 144          *
 145          * @return              An error code
 146          * @param[in]   chars          An instance of Tizen::Base::WcharBuffer to encode
 147          * @param[in]   charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 148          * @param[in]   charCount        The total number of characters to encode
 149          * @param[out]  byteCount      The total number of bytes required to encode the specified range of characters
 150          * @exception   E_SUCCESS                The method is successful.
 151          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c chars is empty.
 152          * @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.
 153          * @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.
 154          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 155          * @remarks     This method determines the total number of bytes
 156          *              that are generated when the specified array of characters is encoded.
 157          * @see                 GetMaxByteCount()
 158          */
 159         virtual result GetByteCount(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount, int& byteCount) const;
 160
 161         /**
 162          * Encodes an instance of the specified Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer.
 163          *
 164          * @since                       2.0
 165          *
 166          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 167          *                              else @c null if an exception occurs @n
 168          *                                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 169          * @param[in]   chars                An instance of Tizen::Base::WcharBuffer to encode
 170          * @exception   E_SUCCESS                The method is successful.
 171          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 172          * @exception   E_INVALID_ARG            The specified @c chars is invalid or empty.
 173          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 174          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 175          * @remarks              The pointer to the Tizen::Base::ByteBuffer instance is not terminated by a @c null character.
 176          * @see                 GetCharsN()
 177          */
 178         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::WcharBuffer& chars) const;
 179
 180         /**
 181          * Encodes an instance of the specified Tizen::Base::String into an instance of Tizen::Base::ByteBuffer.
 182          *
 183          * @since                       2.0
 184          *
 185          * @return              A pointer to the Tizen::Base::ByteBuffer instance where the resultant encoded string is stored, @n
 186          *                              else @c null if an exception occurs @n
 187          *                              The buffer limit is the position of the last encoded byte plus one and the starting position is zero.
 188          * @param[in]   str                  A string to encode
 189          * @exception   E_SUCCESS                The method is successful.
 190          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 191          * @exception   E_INVALID_ARG            The specified @c str is invalid or empty.
 192          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 193          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 194          * @remarks             The pointer to the Tizen::Base::ByteBuffer instance is not terminated by a @c null character.
 195          * @see                 GetString()
 196          */
 197         virtual Tizen::Base::ByteBuffer* GetBytesN(const Tizen::Base::String& str) const;
 198
 199         /**
 200          * Encodes an instance of Tizen::Base::WcharBuffer into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 201          * The position and limit of the %Tizen::Base::ByteBuffer instance is not changed.
 202          *
 203          * @since                       2.0
 204          *
 205          * @return              An error code
 206          * @param[in]   chars                An instance of Tizen::Base::WcharBuffer to encode
 207          * @param[in]   charIndex The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 208          * @param[in]   charCount                 The total number of characters to encode
 209          * @param[out]  bytes                     The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 210          * @param[in]   byteIndex                 The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 211          * @exception   E_SUCCESS                The method is successful.
 212          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 213          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c chars or @c bytes is empty.
 214          * @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.
 215          * @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.
 216          * @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.
 217          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 218          * @remarks     This method encodes a range of characters in Tizen::Base::WcharBuffer into a range of bytes in Tizen::Base::ByteBuffer.
 219          * @see                 GetChars()
 220          */
 221         virtual result GetBytes(const Tizen::Base::WcharBuffer& chars, int charIndex, int charCount,
 222                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
 223
 224         /**
 225          * Encodes an instance of Tizen::Base::String into an instance of Tizen::Base::ByteBuffer as per the specified range. @n
 226          * The position and limit of the %Tizen::Base::ByteBuffer instance is not changed.
 227          *
 228          * @since                       2.0
 229          *
 230          * @return              An error code
 231          * @param[in]   str                   A string to encode
 232          * @param[in]   charIndex             The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 233          * @param[in]   charCount               The total number of characters to encode
 234          * @param[out]  bytes                  The Tizen::Base::ByteBuffer instance where the resultant encoded string is stored
 235          * @param[in]   byteIndex               The starting index of the resultant encoding in the Tizen::Base::ByteBuffer instance
 236          * @exception   E_SUCCESS                The method is successful.
 237          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 238          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c str or @c bytes is empty.
 239          * @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.
 240          * @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.
 241          * @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.
 242          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 243          * @see                 GetString()
 244          */
 245         virtual result GetBytes(const Tizen::Base::String& str, int charIndex, int charCount,
 246                 Tizen::Base::ByteBuffer& bytes, int byteIndex = 0) const;
 247
 248         /**
 249          * Gets the total number of characters that are generated by decoding an instance of Tizen::Base::ByteBuffer.
 250          *
 251          * @since                       2.0
 252          *
 253          * @return              An error code
 254          * @param[in]   bytes              An instance of Tizen::Base::ByteBuffer to decode
 255          * @param[out]  charCount          The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
 256          * @exception   E_SUCCESS                The method is successful.
 257          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c bytes is empty.
 258          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 259          * @remarks     This method determines the total number of characters
 260          *              that are generated when the specified range of bytes are decoded.
 261          * @see                 GetMaxCharCount()
 262          */
 263         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int& charCount) const;
 264
 265         /**
 266          * Gets the total number of characters that are generated by decoding a range of elements specified in the Tizen::Base::ByteBuffer instance.
 267          *
 268          * @since                       2.0
 269          *
 270          * @return              An error code
 271          * @param[in]   bytes             An instance of Tizen::Base::ByteBuffer to decode
 272          * @param[in]   byteIndex          The index from where decoding begins
 273          * @param[in]   byteCount         The total number of bytes to decode
 274          * @param[out]  charCount         The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
 275          * @exception   E_SUCCESS                The method is successful.
 276          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c bytes is empty.
 277          * @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.
 278          * @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.
 279          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 280          * @remarks     This method determines the total number of characters
 281          *              that are generated when the specified range of bytes are decoded.
 282          * @see                 GetMaxCharCount()
 283          */
 284         virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount, int& charCount) const;
 285
 286         /**
 287          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
 288          *
 289          * @since                       2.0
 290          *
 291          * @return              A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
 292          *                              else @c null if an exception occurs @n
 293          *                                              The buffer limit is the position of the last decoded byte plus one and the starting position is zero.
 294          * @param[in]   bytes                An instance of Tizen::Base::ByteBuffer to decode
 295          * @exception   E_SUCCESS                The method is successful.
 296          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 297          * @exception   E_INVALID_ARG            The specified @c bytes is invalid or empty.
 298          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 299          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 300          * @see                 GetBytesN()
 301          */
 302         virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes) const;
 303
 304         /**
 305          * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range. @n
 306          * The position and limit of the %Tizen::Base::WcharBuffer instance is not changed.
 307          *
 308          * @since                       2.0
 309          *
 310          * @return              An error code
 311          * @param[in]   bytes                  An instance of Tizen::Base::ByteBuffer to decode
 312          * @param[in]   byteIndex              The index from where decoding begins
 313          * @param[in]   byteCount              The total number of bytes to decode
 314          * @param[out]  chars                  The Tizen::Base::WcharBuffer instance where the resultant decoded data is stored
 315          * @param[in]   charIndex              The index from where encoding begins in the Tizen::Base::WcharBuffer instance
 316          * @exception   E_SUCCESS                The method is successful.
 317          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 318          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c bytes or @c chars is empty.
 319          * @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.
 320          * @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.
 321          * @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.
 322          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 323          * @see                 GetBytes()
 324          */
 325         virtual result GetChars(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
 326                 Tizen::Base::WcharBuffer& chars, int charIndex = 0) const;
 327
 328         /**
 329          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 330          *
 331          * @since                       2.0
 332          *
 333          * @return              An error code
 334          * @param[in]   bytes               An instance of Tizen::Base::ByteBuffer to decode
 335          * @param[out]  str                 A Tizen::Base::String instance @n
 336          *                                  It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 337          * @exception   E_SUCCESS                The method is successful.
 338          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 339          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c bytes is empty.
 340          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 341          * @see                 GetBytesN()
 342          */
 343         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, Tizen::Base::String& str) const;
 344
 345         /**
 346          * Gets a string containing the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 347          *
 348          * @since                       2.0
 349          *
 350          * @return              An error code
 351          * @param[in]   bytes                      An instance of Tizen::Base::ByteBuffer to decode
 352          * @param[in]   index                      The index from where decoding begins
 353          * @param[in]   count                      The total number of bytes to decode
 354          * @param[out]  str                        A Tizen::Base::String instance @n
 355          *                                         It contains the decoded representation of the specified Tizen::Base::ByteBuffer instance.
 356          * @exception   E_SUCCESS                The method is successful.
 357          * @exception   E_OUT_OF_MEMORY          The memory is insufficient.
 358          * @exception   E_INVALID_ARG            A specified input parameter is invalid, or the specified @c bytes is empty.
 359          * @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.
 360          * @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.
 361          * @exception   E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
 362          * @see                 GetBytes()
 363          */
 364         virtual result GetString(const Tizen::Base::ByteBuffer& bytes, int index, int count, Tizen::Base::String& str) const;
 365
 366
 367         /**
 368          * Gets the maximum number of bytes required for encoding the specified number of characters.
 369          *
 370          * @since                       2.0
 371          *
 372          * @return              The maximum number of bytes required for encoding the specified number of characters
 373          * @param[in]   charCount    The total number of characters to encode
 374          * @remarks   This method determines an appropriate buffer size for the byte arrays passed to GetBytes() for encoding.
 375          * @see                 GetByteCount()
 376          */
 377         virtual int GetMaxByteCount(int charCount) const;
 378
 379
 380         /**
 381         * Gets the maximum number of characters that are generated by decoding the specified number of bytes.
 382         *
 383         * @since                        2.0
 384         *
 385         * @return               The maximum number of characters that are generated by decoding the specified number of bytes
 386         * @param[in]    byteCount The total number of bytes to encode
 387         * @remarks   This method determines an appropriate buffer size for character arrays passed to
 388         *                 GetChars() or a decoder for encoding.
 389         * @see                          GetByteCount()
 390         */
 391         virtual int GetMaxCharCount(int byteCount) const;
 392
 393
 394         /**
 395          * Gets an encoder for the current encoding.
 396          *
 397          * @since                               2.0
 398          *
 399          * @return                      A pointer to the Encoder instance for the current encoding
 400          * @remarks     Contrary to GetBytes(), an encoder can convert partial sequences of characters into
 401          *              partial sequences of bytes by maintaining the appropriate state between the conversions.
 402          *              Currently only UTF-8 encoding supports this method. The other classes return a value of @c null.
 403          * @see                 GetBytes()
 404          */
 405         virtual Encoder* GetEncoderN(void) const;
 406
 407         /**
 408          * Gets a decoder for the current encoding.
 409          *
 410          * @since                               2.0
 411          *
 412          * @return                      A pointer to the Decoder instance for the current encoding
 413          * @remarks     Contrary to GetChars(), a decoder can convert partial sequences of bytes
 414          *              into partial sequences of characters by maintaining the 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                 GetChars()
 417          */
 418         virtual Decoder* GetDecoderN(void) const;
 419
 420         /**
 421         * Gets the encoding type of the current instance.
 422         *
 423         * @since                        2.0
 424         *
 425         * @return               An encoding type
 426         */
 427         virtual Tizen::Base::String GetEncodingType(void) const;
 428
 429 private:
 430         /**
 431          * The implementation of this copy constructor is intentionally blank and declared as private to
 432          * prohibit copying of objects.
 433          */
 434         GsmEncoding(const GsmEncoding& gsmEncoding);
 435
 436         /**
 437          * The implementation of this copy assignment operator is intentionally blank and declared as private
 438          * to prohibit copying of objects.
 439          */
 440         GsmEncoding& operator =(const GsmEncoding& gsmEncoding);
 441
 442         friend class _GsmEncodingImpl;
 443         class _GsmEncodingImpl* __pGsmEncodingImpl;
 444 };
 445
 446 } } // Tizen::Text
 447 #endif //_FTEXT_GSM_ENCODING_H_