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.
23 #ifndef _FBASE_BUFFER_BASE_H_
24 #define _FBASE_BUFFER_BASE_H_
26 #include <FBaseObject.h>
27 #include <FBaseTypes.h>
28 #include <FBaseRtMutex.h>
30 namespace Tizen { namespace Base
42 POSITION_TO_ZERO = 0, /**< The position is set to zero */
43 POSITION_TO_MARK = 1, /**< The position is set to the mark */
49 * @brief This class is the abstract base class of all buffer classes.
53 * The %BufferBase class is the abstract base class of all buffer classes.
55 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/buffer.htm">Buffer</a>.
57 * @see Tizen::Base::ByteBuffer
58 * @see Tizen::Base::Buffer< Type >
61 class _OSP_EXPORT_ BufferBase
65 // Forward declaration
71 * This destructor overrides Tizen::Base::Object::~Object().
75 virtual ~BufferBase(void);
78 * Clears the calling %BufferBase object. @n
79 * The buffer's position is set to @c 0, the limit is set to the capacity, and the mark is discarded.
86 * Copies the elements between the current position and limit (that are also known as remaining
87 * elements), to the beginning of the calling %BufferBase instance.
91 * @remarks After copying, the position is set to the number of elements copied rather than to @c 0,
92 * so that an invocation of this method can be followed immediately by an invocation
93 * of another relative set method. The limit is set to the capacity, and the mark is discarded.
98 * Flips the calling %BufferBase instance. @n
99 * It sets the limit to the current position
100 * and sets the position to either @c 0 or the mark, depending on the input value.
104 * @param[in] to The value to set the buffer position @n
105 * The parameter may contain @c POSITION_TO_ZERO or @c POSITION_TO_MARK.
106 * @remarks If @c to is POSITION_TO_ZERO (or unspecified), the position is set to @c 0 after setting a limit to
107 * the current position, and the mark is discarded.
108 * Otherwise, if @c to is POSITION_TO_MARK, the position is set to the mark and
109 * the mark is not discarded. If the mark is undefined, the position is set to @c 0.
111 * The following example demonstrates how to use the %Flip() method.
116 * buf.Construct(10); // buf's position is zero, limit is 10, and mark is undefined.
118 * buf.SetPosition(7); // Now, buf's position is 7 (limit and mark is unchanged).
120 * buf.Flip(); // equal to "buf.Flip(POSITION_TO_ZERO)"
121 * // buf's position : 0, limit : 7, mark is still undefined.
123 * buf.SetPosition(3);
124 * buf.SetMark(); // Both buf's position and mark are 3.
126 * buf.SetPosition(5); // buf's position is 5, limit is 7, and mark is 3.
128 * buf.Flip(POSITION_TO_MARK); // Now, buf's position is 3, and limit and mark are unchanged.
132 void Flip(PositionTo to = POSITION_TO_ZERO);
135 * Gets the hash value of the calling object.
139 * @return The hash value of the calling object
140 * @remarks The hash code of a buffer depends only upon its remaining elements.
141 * @see Tizen::Base::Object::Equals()
143 virtual int GetHashCode(void) const;
146 * Invalidates the mark of the calling instance of %BufferBase (set to @c -1).
152 void InvalidateMark(void);
155 * Resets the position of the calling %BufferBase object to the previously marked position.
159 * @return An error code
160 * @exception E_SUCCESS The method is successful.
161 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
162 * The mark has not been set.
163 * @remarks Invoking this method neither changes nor discards the mark's value.
168 * Rewinds the current instance of %BufferBase. @n
169 * It sets the position to
170 * @c 0, discards the mark, and leaves the limit unchanged.
177 * Shifts the limit of the current instance of %BufferBase. @n
178 * The new limit is the current limit plus the given amount.
182 * @return An error code
183 * @param[in] amount The quantity of shift needed
184 * @exception E_SUCCESS The method is successful.
185 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method. @n
186 * The @c amount is larger than the capacity or smaller than @c 0 starting from the current limit.
187 * @remarks If the position is larger than the new limit, it is set to the new limit.
188 * If the mark is defined and larger than the new limit, it is discarded.
191 result ShiftLimit(int amount);
194 * Gets the capacity of the calling %BufferBase instance.
198 * @return The capacity of the calling object
200 int GetCapacity(void) const;
204 * Gets the limit of the calling %BufferBase instance.
208 * @return The limit of the calling object
211 int GetLimit(void) const;
215 * Gets the mark of the calling %BufferBase instance. @n
216 * If the mark has not been set, it returns @c -1.
220 * @return The mark of the calling %BufferBase instance
223 int GetMark(void) const;
227 * Gets the current position of the calling %BufferBase instance.
231 * @return The current position of the calling %BufferBase instance
234 int GetPosition(void) const;
238 * Gets the number of elements between the current position and the limit
239 * of the calling %BufferBase instance.
243 * @return The number of elements between the current position and the limit
244 * @see HasRemaining()
246 int GetRemaining(void) const;
250 * Sets the limit of the calling %BufferBase instance.
254 * @return An error code
255 * @param[in] limit The new limit
256 * @exception E_SUCCESS The method is successful.
257 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method. @n
258 * The @c limit is larger than the capacity or less than @c 0.
259 * @remarks If the position is larger than the new limit, it is set to the new limit.
260 * If the mark is defined and larger than the new limit, it is discarded.
263 result SetLimit(int limit);
267 * Sets the mark of the current instance of %BufferBase at the current position. @n
268 * If this method is called after InvalidateMark(), the mark is set to @c -1.
278 * Sets the position of the calling %BufferBase instance.
282 * @return An error code
283 * @param[in] position The new position
284 * @exception E_SUCCESS The method is successful.
285 * @exception E_OUT_OF_RANGE The value of an argument is outside the valid range defined by the method. @n
286 * The @c position is larger than the current limit or less than @c 0.
287 * @remarks If the mark is defined and larger than the new position then it is discarded.
290 result SetPosition(int position);
293 * Returns @c true if there is at least one element between the current position and
294 * the limit of the current instance of %BufferBase. Otherwise, it returns @c false.
298 * @return @c true if there is at least one element between the current position and the limit of the current instance of %BufferBase, @n
300 * @see GetRemaining()
302 bool HasRemaining(void) const;
305 * Expands the capacity and the limit of the internal buffer with the specified capacity.
309 * @return An error code
310 * @param[in] newCapacity The new capacity of this instance
311 * @exception E_SUCCESS The method is successful.
312 * @exception E_INVALID_ARG The specified @c capacity is less than the current capacity.
313 * @remarks After calling this method, the address of the internal buffer may be either the same or a new location.
315 result ExpandCapacity(int newCapacity);
319 * The object is not fully constructed after this constructor is called. For full construction,
320 * the Construct() method must be called right after calling this constructor.
327 * Initializes this instance of %BufferBase with the specified @c capacity.
331 * @return An error code
332 * @param[in] capacity The number of elements
333 * @exception E_SUCCESS The method is successful.
334 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
335 * The @c capacity is negative.
337 result Construct(int capacity);
340 * Increments the reference count by one.
344 long AddRef(void) const;
348 * Decrements the reference count by one.
352 * @return The reference count after decrement
354 long Release(void) const;
357 * Decreases the reference count. @n
358 * After that, it frees the resource (memory allocation) if the reference count is zero.
362 virtual void Dispose(void);
366 * @brief This class encapsulates the @c byte array used by the buffer classes.
375 // This is the default constructor for this class.
382 // This is the destructor for this class.
386 virtual ~_BufferData(void);
389 // Gets the pointer to the byte array.
392 // @return Pointer to the @c byte array
394 byte* GetArray(void);
398 unsigned long long capacityInByte;
414 * Returns the size of the type of the current %BufferBase instance.
416 * @return The size of the type of the current %BufferBase instance
418 virtual int GetTypeSize(void) const = 0;
421 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
423 BufferBase(const BufferBase& obj);
426 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
428 BufferBase& operator =(const BufferBase& rhs);
430 friend class _BufferBaseImpl;
431 class _BufferBaseImpl* __pBufferBaseImpl;
437 #endif // _FBASE_BUFFER_BASE_H_