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 #ifndef _FBASE_BUFFER_BASE_H_
  24 #define _FBASE_BUFFER_BASE_H_
  25
  26 #include <FBaseObject.h>
  27 #include <FBaseTypes.h>
  28 #include <FBaseRtMutex.h>
  29
  30 namespace Tizen { namespace Base
  31 {
  32
  33 /**
  34  * @enum PositionTo
  35  *
  36  * Defines position.
  37  *
  38  * @since 2.0
  39  */
  40 enum PositionTo
  41 {
  42         POSITION_TO_ZERO = 0,   /**< The position is set to zero */
  43         POSITION_TO_MARK = 1,   /**< The position is set to the mark */
  44 };
  45
  46
  47 /**
  48  * @class       BufferBase
  49  * @brief       This class is the abstract base class of all buffer classes.
  50  *
  51  * @since 2.0
  52  *
  53  * The %BufferBase class is the abstract base class of all buffer classes.
  54  *
  55  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/buffer.htm">Buffer</a>.
  56  *
  57  * @see         Tizen::Base::ByteBuffer
  58  * @see         Tizen::Base::Buffer< Type >
  59  */
  60
  61 class _OSP_EXPORT_ BufferBase
  62         : public Object
  63 {
  64
  65 // Forward declaration
  66 protected:
  67         class _BufferData;
  68
  69 public:
  70         /**
  71          * This destructor overrides Tizen::Base::Object::~Object().
  72          *
  73          * @since 2.0
  74          */
  75         virtual ~BufferBase(void);
  76
  77         /**
  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.
  80          *
  81          * @since 2.0
  82          */
  83         void Clear(void);
  84
  85         /**
  86          * Copies the elements between the current position and the limit (that are also known as the remaining
  87          * elements), to the beginning of the calling %BufferBase instance.
  88          *
  89          * @since 2.0
  90          *
  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. @n
  94          *                              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 of the buffer position to set @n
 106          *                        The parameter may contain @c POSITION_TO_ZERO or @c POSITION_TO_MARK.
 107          * @remarks     If @c to is @c 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 @c POSITION_TO_MARK, the position is set to the mark and
 110          *                              the mark is not discarded. @n
 111          *                              If the mark is undefined, the position is set to @c 0.
 112          *
 113          * The following example demonstrates how to use the %Flip() method.
 114          *
 115          * @code
 116          *
 117          *      ByteBuffer buf;
 118          *      buf.Construct(10);                              // buf's position is zero, limit is 10, and mark is undefined.
 119          *
 120          *      buf.SetPosition(7);                             // Now, buf's position is 7 (limit and mark is unchanged).
 121          *
 122          *      buf.Flip();                                             // equal to "buf.Flip(POSITION_TO_ZERO)"
 123          *                                                                      // buf's position : 0, limit : 7, mark is still undefined.
 124          *
 125          *      buf.SetPosition(3);
 126          *      buf.SetMark();                                  // Both buf's position and mark are 3.
 127          *
 128          *      buf.SetPosition(5);                             // buf's position is 5, limit is 7, and mark is 3.
 129          *
 130          *      buf.Flip(POSITION_TO_MARK);             // Now, buf's position is 3, and limit and mark are unchanged.
 131          *
 132          * @endcode
 133          */
 134         void Flip(PositionTo to = POSITION_TO_ZERO);
 135
 136         /**
 137          * Gets the hash value of the calling object.
 138          *
 139          * @since 2.0
 140          *
 141          * @return              The hash value of the calling object
 142          * @remarks             The hash code of a buffer depends only upon its remaining elements.
 143          * @see                 Tizen::Base::Object::Equals()
 144          */
 145         virtual int GetHashCode(void) const;
 146
 147         /**
 148          * Invalidates the mark of the calling instance of %BufferBase (set to @c -1).
 149          *
 150          * @since 2.0
 151          *
 152          * @see                 SetMark()
 153          */
 154         void InvalidateMark(void);
 155
 156         /**
 157          * Resets the position of the calling %BufferBase object to the previously marked position.
 158          *
 159          * @since 2.0
 160          *
 161          * @return              An error code
 162          * @exception   E_SUCCESS                       The method is successful.
 163          * @exception   E_INVALID_OPERATION Either of the following conditions has occurred:
 164          *                                                                      - The current state of the instance prohibits the execution of the specified operation.
 165          *                                                                      - The mark has not been set.
 166          * @remarks     Invoking this method neither changes nor discards the mark's value.
 167          */
 168         result Reset(void);
 169
 170         /**
 171          * Rewinds the current instance of %BufferBase. @n
 172          * It sets the position to
 173          * @c 0, discards the mark, and leaves the limit unchanged.
 174          *
 175          * @since 2.0
 176          */
 177         void Rewind(void);
 178
 179         /**
 180          * Shifts the limit of the current instance of %BufferBase. @n
 181          * The new limit is the current limit plus the given @c amount.
 182          *
 183          * @since 2.0
 184          *
 185          * @return              An error code
 186          * @param[in]   amount                          The quantity of the shift needed
 187          * @exception   E_SUCCESS                       The method is successful.
 188          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 189          *                                                                      - The value of the argument is outside the valid range defined by the method.
 190          *                                                                      - The @c amount is larger than the capacity starting from the current limit.
 191          *                                                                      - The @c amount is smaller than @c 0.
 192          * @remarks
 193          *                              - If the position is larger than the new limit, it is set to the new limit.
 194          *                              - If the mark is defined and is larger than the new limit, it is discarded.
 195          * @see                 SetLimit()
 196          */
 197         result ShiftLimit(int amount);
 198
 199         /**
 200          * Gets the capacity of the calling %BufferBase instance.
 201          *
 202          * @since 2.0
 203          *
 204          * @return              The capacity of the calling %BufferBase instance
 205          */
 206         int GetCapacity(void) const;
 207
 208
 209         /**
 210          * Gets the limit of the calling %BufferBase instance.
 211          *
 212          * @since 2.0
 213          *
 214          * @return                      The limit of the calling %BufferBase instance
 215          * @see                         SetLimit()
 216          */
 217         int GetLimit(void) const;
 218
 219
 220         /**
 221          * Gets the mark of the calling %BufferBase instance. @n
 222          * If the mark has not been set, it returns @c -1.
 223          *
 224          * @since 2.0
 225          *
 226          * @return                      The mark of the calling %BufferBase instance
 227          * @see                         SetMark()
 228          */
 229         int GetMark(void) const;
 230
 231
 232         /**
 233          * Gets the current position of the calling %BufferBase instance.
 234          *
 235          * @since 2.0
 236          *
 237          * @return                      The current position of the calling %BufferBase instance
 238          * @see                         SetPosition()
 239          */
 240         int GetPosition(void) const;
 241
 242
 243         /**
 244          * Gets the number of elements between the current position and the limit
 245          * of the calling %BufferBase instance.
 246          *
 247          * @since 2.0
 248          *
 249          * @return                      The number of elements between the current position and the limit
 250          * @see                         HasRemaining()
 251          */
 252         int GetRemaining(void) const;
 253
 254
 255         /**
 256          * Sets the limit of the calling %BufferBase instance.
 257          *
 258          * @since 2.0
 259          *
 260          * @return              An error code
 261          * @param[in]   limit                           The limit of the calling %BufferBase instance
 262          * @exception   E_SUCCESS                       The method is successful.
 263          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 264          *                                                                      - The value of the argument is outside the valid range defined by the method.
 265          *                                                                      - The specified @c limit is larger than the capacity.
 266          *                                                                      - The specified @c limit is less than @c 0.
 267          * @remarks
 268          *                              - If the position is larger than the new limit, it is set to the new limit.
 269          *                              - If the mark is defined and is larger than the new limit, it is discarded.
 270          * @see                 GetLimit()
 271          */
 272         result SetLimit(int limit);
 273
 274
 275         /**
 276          * Sets the mark of the current instance of %BufferBase at the current position. @n
 277          * If this method is called after the InvalidateMark() method , the mark is set to @c -1.
 278          *
 279          * @since               2.0
 280          *
 281          * @see                 GetMark()
 282          */
 283         void SetMark(void);
 284
 285
 286         /**
 287          * Sets the position of the calling %BufferBase instance.
 288          *
 289          * @since 2.0
 290          *
 291          * @return              An error code
 292          * @param[in]   position                        The position of the calling %BufferBase instance
 293          * @exception   E_SUCCESS                       The method is successful.
 294          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 295          *                                                                      - The value of the argument is outside the valid range defined by the method.
 296          *                                                                      - The specified @c position is larger than the current limit.
 297          *                                                                      - The specified @c position is less than @c 0.
 298          * @remarks             If the mark is defined and is larger than the new position then it is discarded.
 299          * @see                 GetPosition()
 300          */
 301         result SetPosition(int position);
 302
 303         /**
 304          * Returns @c true if there is at least one element between the current position and
 305          * the limit of the current %BufferBase instance. Otherwise, it returns @c false.
 306          *
 307          * @since 2.0
 308          *
 309          * @return              @c true if there is at least one element between the current position and the limit of the current %BufferBase instance, @n
 310          *                              else @c false
 311          * @see                 GetRemaining()
 312          */
 313         bool HasRemaining(void) const;
 314
 315         /**
 316          * Expands the capacity and the limit of the internal buffer with the specified @c newCapacity.
 317          *
 318          * @since 2.0
 319          *
 320          * @return              An error code
 321          * @param[in]   newCapacity             The new capacity of this instance
 322          * @exception   E_SUCCESS               The method is successful.
 323          * @exception   E_INVALID_ARG   The specified @c newCapacity is less than the current capacity.
 324          * @remarks     After calling this method, the address of the internal buffer may be either the same or a new location.
 325          */
 326         result ExpandCapacity(int newCapacity);
 327
 328 protected:
 329         /**
 330          * The object is not fully constructed after this constructor is called. For full construction,
 331          * the Construct() method must be called right after calling this constructor.
 332          *
 333          * @since 2.0
 334          */
 335         BufferBase(void);
 336
 337         /**
 338          * Initializes this instance of %BufferBase with the specified @c capacity.
 339          *
 340          * @since 2.0
 341          *
 342          * @return              An error code
 343          * @param[in]   capacity                The number of elements
 344          * @exception   E_SUCCESS               The method is successful.
 345          * @exception   E_INVALID_ARG   A specified input parameter is invalid. @n
 346          *                                                              The @c capacity is negative.
 347          */
 348         result Construct(int capacity);
 349
 350         /**
 351          * Increments the reference count by one.
 352          *
 353          * @since 2.0
 354          */
 355         long AddRef(void) const;
 356
 357
 358         /**
 359          * Decrements the reference count by one.
 360          *
 361          * @since 2.0
 362          *
 363          * @return              The reference count after decrement
 364          */
 365         long Release(void) const;
 366
 367         /**
 368          * Decreases the reference count. @n
 369          * After that, it frees the resource (memory allocation) if the reference count is zero.
 370          *
 371          * @since 2.0
 372          */
 373         virtual void Dispose(void);
 374
 375         /*
 376          * @class               _BufferData
 377          * @brief               This class encapsulates the @c byte array used by the buffer classes.
 378          *
 379          * @since 2.0
 380          *
 381          */
 382         class _BufferData
 383         {
 384         public:
 385                 //
 386                 //  This is the default constructor for this class.
 387                 //
 388                 //  @since 2.0
 389                 //
 390                 _BufferData(void);
 391
 392                 //
 393                 //  This is the destructor for this class.
 394                 //
 395                 // @since 2.0
 396                 //
 397                 virtual ~_BufferData(void);
 398
 399                 //
 400                 // Gets a pointer to the byte array.
 401                 //
 402                 // @since 2.0
 403                 // @return              Pointer to the @c byte array
 404                 //
 405                 byte* GetArray(void);
 406
 407
 408                 // Attribute
 409                 unsigned long long capacityInByte;
 410                 long refCount;
 411
 412         }; // _BufferData
 413
 414
 415         int _capacity;
 416         int _position;
 417         int _limit;
 418         int _mark;
 419         _BufferData* _pData;
 420         byte* __pArrayStart;
 421
 422
 423 private:
 424         /**
 425          * Returns the size of the type of the current %BufferBase instance.
 426          *
 427          * @return              The size of the type of the current %BufferBase instance
 428          */
 429         virtual int GetTypeSize(void) const = 0;
 430
 431         /**
 432          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 433          */
 434         BufferBase(const BufferBase& obj);
 435
 436         /**
 437          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 438          */
 439         BufferBase& operator =(const BufferBase& rhs);
 440
 441         friend class _BufferBaseImpl;
 442         class _BufferBaseImpl* __pBufferBaseImpl;
 443
 444 }; // BufferBase
 445
 446 }} // Tizen::Base
 447
 448 #endif // _FBASE_BUFFER_BASE_H_