2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FTextDecoder.h
19 * @brief This is the header file for the %Decoder class.
21 * This header file contains the declarations of the %Decoder class.
24 #ifndef _FTEXT_DECODER_H_
25 #define _FTEXT_DECODER_H_
27 #include <FBaseObject.h>
28 #include <FBaseTypes.h>
29 #include <FBaseBuffer.h>
31 namespace Tizen { namespace Text
35 * @brief This class is an implementation of the character decoder.
39 * The %Decoder class converts blocks of encoded bytes into blocks of Unicode characters
40 * through successive calls to the GetCharsN() method. This class maintains state consistency information between
41 * successive calls to %GetCharsN(), enabling it to decode a sequence of bytes that span adjacent blocks.
43 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/text/converting_text_data_separate_blocks.htm">Converting Text Data in Separate Blocks</a>.
47 class _OSP_EXPORT_ Decoder
48 : public Tizen::Base::Object
52 * This is the destructor for this class. @n
53 * This destructor overrides Tizen::Base::Object::~Object().
57 virtual ~Decoder(void) { };
60 * Gets the total number of characters that are generated by decoding a range of elements specified in the Tizen::Base::ByteBuffer instance.
64 * @return An error code
65 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
66 * @param[in] byteIndex The index from where decoding begins
67 * @param[in] byteCount The total number of bytes to decode
68 * @param[in] flush Set to @c true to allow this instance to flush its state at the end of the conversion, @n
70 * @param[out] charCount The total number of characters that are generated by decoding the specified Tizen::Base::ByteBuffer instance
71 * @exception E_SUCCESS The method is successful.
72 * @exception E_INVALID_ARG A specified input parameter is invalid, or
73 * the specified @c bytes is empty.
74 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
75 * the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
76 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
77 * the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
78 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
79 * @see Encoder::GetByteCount()
81 virtual result GetCharCount(const Tizen::Base::ByteBuffer& bytes,
82 int byteIndex, int byteCount, int& charCount, bool flush = false) const = 0;
85 * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer.
89 * @return A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
90 * else @c null if an exception occurs @n
91 * The buffer limit is the position of the last decoded byte plus one in the buffer and the starting position is zero.
92 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
93 * @param[in] flush Set to @c true to allow this instance to flush its state at the end of the conversion, @n
95 * @exception E_SUCCESS The method is successful.
96 * @exception E_OUT_OF_MEMORY The memory is insufficient.
97 * @exception E_INVALID_ARG A specified input parameter is invalid, or
98 * the specified @c bytes is empty.
99 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
100 * @remarks The specific error code can be accessed using the GetLastResult() method.
101 * @see Encoder::GetBytesN()
103 virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes, bool flush = false) const = 0;
106 * Decodes an instance of Tizen::Base::ByteBuffer into an instance of Tizen::Base::WcharBuffer as per the specified range.
110 * @return A pointer to the Tizen::Base::WcharBuffer instance where the resultant decoded data is stored, @n
111 * else @c null if an exception occurs @n
112 * The buffer limit is the position of the last decoded byte in the buffer and the starting position is zero.
113 * @param[in] bytes An instance of Tizen::Base::ByteBuffer to decode
114 * @param[in] byteIndex The index from where decoding begins
115 * @param[in] byteCount The total number of bytes to decode
116 * @param[in] flush Set to @c true to allow this instance to flush its state at the end of the conversion, @n
118 * @exception E_SUCCESS The method is successful.
119 * @exception E_OUT_OF_MEMORY The memory is insufficient.
120 * @exception E_INVALID_ARG A specified input parameter is invalid, or
121 * the specified @c bytes is empty.
122 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method, or
123 * the length of the specified @c byteIndex or @c byteCount is greater than the length of the specified @c bytes.
124 * @exception E_UNDERFLOW This operation has caused the memory to underflow, or
125 * the sum of the length of the specified @c byteIndex and @c byteCount is greater than the length of the specified @c bytes.
126 * @exception E_INVALID_ENCODING_RANGE The specified string contains code points that are outside the bounds of the character encoding scheme.
127 * @remarks This method maintains state consistency between conversions.
128 * @remarks The specific error code can be accessed using the GetLastResult() method.
129 * @remarks The pointer to the Tizen::Base::WcharBuffer instance is not terminated by a @c null character.
130 * @see Encoder::GetBytesN()
132 virtual Tizen::Base::WcharBuffer* GetCharsN(const Tizen::Base::ByteBuffer& bytes, int byteIndex, int byteCount,
133 bool flush = false) const = 0;
137 : _pDecoderImpl(null){};
138 friend class _DecoderImpl;
139 class _DecoderImpl* _pDecoderImpl;
143 * The implementation of this copy constructor is intentionally blank and declared as private to
144 * prohibit copying of objects.
146 Decoder(const Decoder& decoder);
149 * The implementation of this copy assignment operator is intentionally blank and declared as private
150 * to prohibit copying of objects.
152 Decoder& operator =(const Decoder& decoder);
157 #endif //_FTEXT_DECODER_H_