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 FBaseBufferBase.h
19 * @brief This is the header file for the %BufferBase class.
21 * This header file contains the declarations of the %BufferBase class.
24 #ifndef _FBASE_BUFFER_BASE_H_
25 #define _FBASE_BUFFER_BASE_H_
27 #include <FBaseObject.h>
28 #include <FBaseTypes.h>
29 #include <FBaseRtMutex.h>
31 namespace Tizen { namespace Base
43 POSITION_TO_ZERO = 0, /**< The position is set to zero */
44 POSITION_TO_MARK = 1, /**< The position is set to the mark */
50 * @brief This class is the abstract base class of all buffer classes.
54 * The %BufferBase class is the abstract base class of all buffer classes.
56 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/buffer.htm">Buffer</a>.
58 * @see Tizen::Base::ByteBuffer
59 * @see Tizen::Base::Buffer< Type >
62 class _OSP_EXPORT_ BufferBase
66 // Forward declaration
72 * This destructor overrides Tizen::Base::Object::~Object().
76 virtual ~BufferBase(void);
79 * Clears the calling %BufferBase object. @n
80 * The buffer's position is set to @c 0, the limit is set to the capacity, and the mark is discarded.
87 * Copies the elements between the current position and limit (that are also known as remaining
88 * elements), to the beginning of the calling %BufferBase instance.
92 * @remarks After copying, the position is set to the number of elements copied rather than to @c 0,
93 * so that an invocation of this method can be followed immediately by an invocation
94 * of another relative set method. The limit is set to the capacity, and the mark is discarded.
99 * Flips the calling %BufferBase instance. @n
100 * It sets the limit to the current position
101 * and sets the position to either @c 0 or the mark, depending on the input value.
105 * @param[in] to The value to set the buffer position @n
106 * The parameter may contain @c POSITION_TO_ZERO or @c POSITION_TO_MARK.
107 * @remarks If @c to is POSITION_TO_ZERO (or unspecified), the position is set to @c 0 after setting a limit to
108 * the current position, and the mark is discarded.
109 * Otherwise, if @c to is POSITION_TO_MARK, the position is set to the mark and
110 * the mark is not discarded. If the mark is undefined, the position is set to @c 0.
112 * The following example demonstrates how to use the %Flip() method.
117 * buf.Construct(10); // buf's position is zero, limit is 10, and mark is undefined.
119 * buf.SetPosition(7); // Now, buf's position is 7 (limit and mark is unchanged).
121 * buf.Flip(); // equal to "buf.Flip(POSITION_TO_ZERO)"
122 * // buf's position : 0, limit : 7, mark is still undefined.
124 * buf.SetPosition(3);
125 * buf.SetMark(); // Both buf's position and mark are 3.
127 * buf.SetPosition(5); // buf's position is 5, limit is 7, and mark is 3.
129 * buf.Flip(POSITION_TO_MARK); // Now, buf's position is 3, and limit and mark are unchanged.
133 void Flip(PositionTo to = POSITION_TO_ZERO);
136 * Gets the hash value of the calling object.
140 * @return The hash value of the calling object
141 * @remarks The hash code of a buffer depends only upon its remaining elements.
142 * @see Tizen::Base::Object::Equals()
144 virtual int GetHashCode(void) const;
147 * Invalidates the mark of the calling instance of %BufferBase (set to @c -1).
153 void InvalidateMark(void);
156 * Resets the position of the calling %BufferBase object to the previously marked position.
160 * @return An error code
161 * @exception E_SUCCESS The method is successful.
162 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
163 * The mark has not been set.
164 * @remarks Invoking this method neither changes nor discards the mark's value.
169 * Rewinds the current instance of %BufferBase. @n
170 * It sets the position to
171 * @c 0, discards the mark, and leaves the limit unchanged.
178 * Shifts the limit of the current instance of %BufferBase. @n
179 * The new limit is the current limit plus the given amount.
183 * @return An error code
184 * @param[in] amount The quantity of shift needed
185 * @exception E_SUCCESS The method is successful.
186 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method. @n
187 * The @c amount is larger than the capacity or smaller than @c 0 starting from the current limit.
188 * @remarks If the position is larger than the new limit, it is set to the new limit.
189 * If the mark is defined and larger than the new limit, it is discarded.
192 result ShiftLimit(int amount);
195 * Gets the capacity of the calling %BufferBase instance.
199 * @return The capacity of the calling object
201 int GetCapacity(void) const;
205 * Gets the limit of the calling %BufferBase instance.
209 * @return The limit of the calling object
212 int GetLimit(void) const;
216 * Gets the mark of the calling %BufferBase instance. @n
217 * If the mark has not been set, it returns @c -1.
221 * @return The mark of the calling %BufferBase instance
224 int GetMark(void) const;
228 * Gets the current position of the calling %BufferBase instance.
232 * @return The current position of the calling %BufferBase instance
235 int GetPosition(void) const;
239 * Gets the number of elements between the current position and the limit
240 * of the calling %BufferBase instance.
244 * @return The number of elements between the current position and the limit
245 * @see HasRemaining()
247 int GetRemaining(void) const;
251 * Sets the limit of the calling %BufferBase instance.
255 * @return An error code
256 * @param[in] limit The new limit
257 * @exception E_SUCCESS The method is successful.
258 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method. @n
259 * The @c limit is larger than the capacity or less than @c 0.
260 * @remarks If the position is larger than the new limit, it is set to the new limit.
261 * If the mark is defined and larger than the new limit, it is discarded.
264 result SetLimit(int limit);
268 * Sets the mark of the current instance of %BufferBase at the current position. @n
269 * If this method is called after InvalidateMark(), the mark is set to @c -1.
279 * Sets the position of the calling %BufferBase instance.
283 * @return An error code
284 * @param[in] position The new position
285 * @exception E_SUCCESS The method is successful.
286 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method. @n
287 * The @c position is larger than the current limit or less than @c 0.
288 * @remarks If the mark is defined and larger than the new position then it is discarded.
291 result SetPosition(int position);
294 * Returns @c true if there is at least one element between the current position and
295 * the limit of the current instance of %BufferBase. Otherwise, it returns @c false.
299 * @return @c true if there is at least one element between the current position and the limit of the current instance of %BufferBase, @n
301 * @see GetRemaining()
303 bool HasRemaining(void) const;
306 * Expands the capacity and the limit of the internal buffer with the specified capacity.
310 * @return An error code
311 * @param[in] newCapacity The new capacity of this instance
312 * @exception E_SUCCESS The method is successful.
313 * @exception E_INVALID_ARG The specified @c capacity is less than the current capacity.
314 * @remarks After calling this method, the address of the internal buffer may be either the same or a new location.
316 result ExpandCapacity(int newCapacity);
320 * The object is not fully constructed after this constructor is called. For full construction,
321 * the Construct() method must be called right after calling this constructor.
328 * Initializes this instance of %BufferBase with the specified @c capacity.
332 * @return An error code
333 * @param[in] capacity The number of elements
334 * @exception E_SUCCESS The method is successful.
335 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
336 * The @c capacity is negative.
338 result Construct(int capacity);
341 * Increments the reference count by one.
345 long AddRef(void) const;
349 * Decrements the reference count by one.
353 * @return The reference count after decrement
355 long Release(void) const;
358 * Decreases the reference count. @n
359 * After that, it frees the resource (memory allocation) if the reference count is zero.
363 virtual void Dispose(void);
367 * @brief This class encapsulates the @c byte array used by the buffer classes.
376 // This is the default constructor for this class.
383 // This is the destructor for this class.
387 virtual ~_BufferData(void);
390 // Gets the pointer to the byte array.
393 // @return Pointer to the @c byte array
395 byte* GetArray(void);
399 unsigned long long capacityInByte;
415 * Returns the size of the type of the current %BufferBase instance.
417 * @return The size of the type of the current %BufferBase instance
419 virtual int GetTypeSize(void) const = 0;
422 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
424 BufferBase(const BufferBase& obj);
427 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
429 BufferBase& operator =(const BufferBase& rhs);
431 friend class _BufferBaseImpl;
432 class _BufferBaseImpl * __pBufferBaseImpl;
438 #endif // _FBASE_BUFFER_BASE_H_