inc/FBaseBufferBase.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   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
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  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.
  15 //
  16
  17 /**
  18  * @file                FBaseBufferBase.h
  19  * @brief               This is the header file for the %BufferBase class.
  20  *
  21  * This header file contains the declarations of the %BufferBase class.
  22  */
  23
  24 #ifndef _FBASE_BUFFER_BASE_H_
  25 #define _FBASE_BUFFER_BASE_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseTypes.h>
  29 #include <FBaseRtMutex.h>
  30
  31 namespace Tizen { namespace Base
  32 {
  33
  34 /**
  35  * @enum PositionTo
  36  *
  37  * Defines position.
  38  *
  39  * @since 2.0
  40  */
  41 enum PositionTo
  42 {
  43         POSITION_TO_ZERO = 0,   /**< The position is set to zero */
  44         POSITION_TO_MARK = 1,   /**< The position is set to the mark */
  45 };
  46
  47
  48 /**
  49  * @class       BufferBase
  50  * @brief       This class is the abstract base class of all buffer classes.
  51  *
  52  * @since 2.0
  53  *
  54  * The %BufferBase class is the abstract base class of all buffer classes.
  55  *
  56  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/buffer.htm">Buffer</a>.
  57  *
  58  * @see         Tizen::Base::ByteBuffer
  59  * @see         Tizen::Base::Buffer< Type >
  60  */
  61
  62 class _OSP_EXPORT_ BufferBase
  63         : public Object
  64 {
  65
  66 // Forward declaration
  67 protected:
  68         class _BufferData;
  69
  70 public:
  71         /**
  72          * This destructor overrides Tizen::Base::Object::~Object().
  73          *
  74          * @since 2.0
  75          */
  76         virtual ~BufferBase(void);
  77
  78         /**
  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.
  81          *
  82          * @since 2.0
  83          */
  84         void Clear(void);
  85
  86         /**
  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.
  89          *
  90          * @since 2.0
  91          *
  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.
  95          */
  96         void Compact(void);
  97
  98         /**
  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.
 102          *
 103          * @since 2.0
 104          *
 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.
 111          *
 112          * The following example demonstrates how to use the %Flip() method.
 113          *
 114          * @code
 115          *
 116          *      ByteBuffer buf;
 117          *      buf.Construct(10);                              // buf's position is zero, limit is 10, and mark is undefined.
 118          *
 119          *      buf.SetPosition(7);                             // Now, buf's position is 7 (limit and mark is unchanged).
 120          *
 121          *      buf.Flip();                                             // equal to "buf.Flip(POSITION_TO_ZERO)"
 122          *                                                                      // buf's position : 0, limit : 7, mark is still undefined.
 123          *
 124          *      buf.SetPosition(3);
 125          *      buf.SetMark();                                  // Both buf's position and mark are 3.
 126          *
 127          *      buf.SetPosition(5);                             // buf's position is 5, limit is 7, and mark is 3.
 128          *
 129          *      buf.Flip(POSITION_TO_MARK);             // Now, buf's position is 3, and limit and mark are unchanged.
 130          *
 131          * @endcode
 132          */
 133         void Flip(PositionTo to = POSITION_TO_ZERO);
 134
 135         /**
 136          * Gets the hash value of the calling object.
 137          *
 138          * @since 2.0
 139          *
 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()
 143          */
 144         virtual int GetHashCode(void) const;
 145
 146         /**
 147          * Invalidates the mark of the calling instance of %BufferBase (set to @c -1).
 148          *
 149          * @since 2.0
 150          *
 151          * @see                 SetMark()
 152          */
 153         void InvalidateMark(void);
 154
 155         /**
 156          * Resets the position of the calling %BufferBase object to the previously marked position.
 157          *
 158          * @since 2.0
 159          *
 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.
 165          */
 166         result Reset(void);
 167
 168         /**
 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.
 172          *
 173          * @since 2.0
 174          */
 175         void Rewind(void);
 176
 177         /**
 178          * Shifts the limit of the current instance of %BufferBase. @n
 179          * The new limit is the current limit plus the given amount.
 180          *
 181          * @since 2.0
 182          *
 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.
 190          * @see                 SetLimit()
 191          */
 192         result ShiftLimit(int amount);
 193
 194         /**
 195          * Gets the capacity of the calling %BufferBase instance.
 196          *
 197          * @since 2.0
 198          *
 199          * @return              The capacity of the calling object
 200          */
 201         int GetCapacity(void) const;
 202
 203
 204         /**
 205          * Gets the limit of the calling %BufferBase instance.
 206          *
 207          * @since 2.0
 208          *
 209          * @return              The limit of the calling object
 210          * @see                         SetLimit()
 211          */
 212         int GetLimit(void) const;
 213
 214
 215         /**
 216          * Gets the mark of the calling %BufferBase instance. @n
 217          * If the mark has not been set, it returns @c -1.
 218          *
 219          * @since 2.0
 220          *
 221          * @return              The mark of the calling %BufferBase instance
 222          * @see                         SetMark()
 223          */
 224         int GetMark(void) const;
 225
 226
 227         /**
 228          * Gets the current position of the calling %BufferBase instance.
 229          *
 230          * @since 2.0
 231          *
 232          * @return              The current position of the calling %BufferBase instance
 233          * @see                         SetPosition()
 234          */
 235         int GetPosition(void) const;
 236
 237
 238         /**
 239          * Gets the number of elements between the current position and the limit
 240          * of the calling %BufferBase instance.
 241          *
 242          * @since 2.0
 243          *
 244          * @return              The number of elements between the current position and the limit
 245          * @see                         HasRemaining()
 246          */
 247         int GetRemaining(void) const;
 248
 249
 250         /**
 251          * Sets the limit of the calling %BufferBase instance.
 252          *
 253          * @since 2.0
 254          *
 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.
 262          * @see                 GetLimit()
 263          */
 264         result SetLimit(int limit);
 265
 266
 267         /**
 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.
 270          *
 271          * @since 2.0
 272          *
 273          * @see                 GetMark()
 274          */
 275         void SetMark(void);
 276
 277
 278         /**
 279          * Sets the position of the calling %BufferBase instance.
 280          *
 281          * @since 2.0
 282          *
 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.
 289          * @see                 GetPosition()
 290          */
 291         result SetPosition(int position);
 292
 293         /**
 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.
 296          *
 297          * @since 2.0
 298          *
 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
 300          *                               else @c false
 301          * @see                         GetRemaining()
 302          */
 303         bool HasRemaining(void) const;
 304
 305         /**
 306          * Expands the capacity and the limit of the internal buffer with the specified capacity.
 307          *
 308          * @since 2.0
 309          *
 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.
 315          */
 316         result ExpandCapacity(int newCapacity);
 317
 318 protected:
 319         /**
 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.
 322          *
 323          * @since 2.0
 324          */
 325         BufferBase(void);
 326
 327         /**
 328          * Initializes this instance of %BufferBase with the specified @c capacity.
 329          *
 330          * @since 2.0
 331          *
 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.
 337          */
 338         result Construct(int capacity);
 339
 340         /**
 341          * Increments the reference count by one.
 342          *
 343          * @since 2.0
 344          */
 345         long AddRef(void) const;
 346
 347
 348         /**
 349          * Decrements the reference count by one.
 350          *
 351          * @since 2.0
 352          *
 353          * @return              The reference count after decrement
 354          */
 355         long Release(void) const;
 356
 357         /**
 358          * Decreases the reference count. @n
 359          * After that, it frees the resource (memory allocation) if the reference count is zero.
 360          *
 361          * @since 2.0
 362          */
 363         virtual void Dispose(void);
 364
 365         /*
 366          * @class               _BufferData
 367          * @brief               This class encapsulates the @c byte array used by the buffer classes.
 368          *
 369          * @since 2.0
 370          *
 371          */
 372         class _BufferData
 373         {
 374         public:
 375                 //
 376                 //  This is the default constructor for this class.
 377                 //
 378                 //  @since 2.0
 379                 //
 380                 _BufferData(void);
 381
 382                 //
 383                 //  This is the destructor for this class.
 384                 //
 385                 // @since 2.0
 386                 //
 387                 virtual ~_BufferData(void);
 388
 389                 //
 390                 // Gets the pointer to the byte array.
 391                 //
 392                 // @since 2.0
 393                 // @return              Pointer to the @c byte array
 394                 //
 395                 byte* GetArray(void);
 396
 397
 398                 // Attribute
 399                 unsigned long long capacityInByte;
 400                 long refCount;
 401
 402         }; // _BufferData
 403
 404
 405         int _capacity;
 406         int _position;
 407         int _limit;
 408         int _mark;
 409         _BufferData* _pData;
 410         byte* __pArrayStart;
 411
 412
 413 private:
 414         /**
 415          * Returns the size of the type of the current %BufferBase instance.
 416          *
 417          * @return              The size of the type of the current %BufferBase instance
 418          */
 419         virtual int GetTypeSize(void) const = 0;
 420
 421         /**
 422          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 423          */
 424         BufferBase(const BufferBase& obj);
 425
 426         /**
 427          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 428          */
 429         BufferBase& operator =(const BufferBase& rhs);
 430
 431         friend class _BufferBaseImpl;
 432         class _BufferBaseImpl * __pBufferBaseImpl;
 433
 434 }; // BufferBase
 435
 436 }} // Tizen::Base
 437
 438 #endif // _FBASE_BUFFER_BASE_H_