Merge "remove unnecessary implementations" into tizen_2.1
[platform/framework/native/appfw.git] / 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_