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 limit (that are also known as 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. The limit is set to the capacity, and the mark is discarded.
  94          */
  95         void Compact(void);
  96
  97         /**
  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.
 101          *
 102          * @since 2.0
 103          *
 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.
 110          *
 111          * The following example demonstrates how to use the %Flip() method.
 112          *
 113          * @code
 114          *
 115          *      ByteBuffer buf;
 116          *      buf.Construct(10);                              // buf's position is zero, limit is 10, and mark is undefined.
 117          *
 118          *      buf.SetPosition(7);                             // Now, buf's position is 7 (limit and mark is unchanged).
 119          *
 120          *      buf.Flip();                                             // equal to "buf.Flip(POSITION_TO_ZERO)"
 121          *                                                                      // buf's position : 0, limit : 7, mark is still undefined.
 122          *
 123          *      buf.SetPosition(3);
 124          *      buf.SetMark();                                  // Both buf's position and mark are 3.
 125          *
 126          *      buf.SetPosition(5);                             // buf's position is 5, limit is 7, and mark is 3.
 127          *
 128          *      buf.Flip(POSITION_TO_MARK);             // Now, buf's position is 3, and limit and mark are unchanged.
 129          *
 130          * @endcode
 131          */
 132         void Flip(PositionTo to = POSITION_TO_ZERO);
 133
 134         /**
 135          * Gets the hash value of the calling object.
 136          *
 137          * @since 2.0
 138          *
 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()
 142          */
 143         virtual int GetHashCode(void) const;
 144
 145         /**
 146          * Invalidates the mark of the calling instance of %BufferBase (set to @c -1).
 147          *
 148          * @since 2.0
 149          *
 150          * @see                 SetMark()
 151          */
 152         void InvalidateMark(void);
 153
 154         /**
 155          * Resets the position of the calling %BufferBase object to the previously marked position.
 156          *
 157          * @since 2.0
 158          *
 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.
 164          */
 165         result Reset(void);
 166
 167         /**
 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.
 171          *
 172          * @since 2.0
 173          */
 174         void Rewind(void);
 175
 176         /**
 177          * Shifts the limit of the current instance of %BufferBase. @n
 178          * The new limit is the current limit plus the given amount.
 179          *
 180          * @since 2.0
 181          *
 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.
 189          * @see                 SetLimit()
 190          */
 191         result ShiftLimit(int amount);
 192
 193         /**
 194          * Gets the capacity of the calling %BufferBase instance.
 195          *
 196          * @since 2.0
 197          *
 198          * @return              The capacity of the calling object
 199          */
 200         int GetCapacity(void) const;
 201
 202
 203         /**
 204          * Gets the limit of the calling %BufferBase instance.
 205          *
 206          * @since 2.0
 207          *
 208          * @return                      The limit of the calling object
 209          * @see                         SetLimit()
 210          */
 211         int GetLimit(void) const;
 212
 213
 214         /**
 215          * Gets the mark of the calling %BufferBase instance. @n
 216          * If the mark has not been set, it returns @c -1.
 217          *
 218          * @since 2.0
 219          *
 220          * @return                      The mark of the calling %BufferBase instance
 221          * @see                         SetMark()
 222          */
 223         int GetMark(void) const;
 224
 225
 226         /**
 227          * Gets the current position of the calling %BufferBase instance.
 228          *
 229          * @since 2.0
 230          *
 231          * @return                      The current position of the calling %BufferBase instance
 232          * @see                         SetPosition()
 233          */
 234         int GetPosition(void) const;
 235
 236
 237         /**
 238          * Gets the number of elements between the current position and the limit
 239          * of the calling %BufferBase instance.
 240          *
 241          * @since 2.0
 242          *
 243          * @return                      The number of elements between the current position and the limit
 244          * @see                         HasRemaining()
 245          */
 246         int GetRemaining(void) const;
 247
 248
 249         /**
 250          * Sets the limit of the calling %BufferBase instance.
 251          *
 252          * @since 2.0
 253          *
 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.
 261          * @see                 GetLimit()
 262          */
 263         result SetLimit(int limit);
 264
 265
 266         /**
 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.
 269          *
 270          * @since 2.0
 271          *
 272          * @see                 GetMark()
 273          */
 274         void SetMark(void);
 275
 276
 277         /**
 278          * Sets the position of the calling %BufferBase instance.
 279          *
 280          * @since 2.0
 281          *
 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.
 288          * @see                 GetPosition()
 289          */
 290         result SetPosition(int position);
 291
 292         /**
 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.
 295          *
 296          * @since 2.0
 297          *
 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
 299          *                              else @c false
 300          * @see                 GetRemaining()
 301          */
 302         bool HasRemaining(void) const;
 303
 304         /**
 305          * Expands the capacity and the limit of the internal buffer with the specified capacity.
 306          *
 307          * @since 2.0
 308          *
 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.
 314          */
 315         result ExpandCapacity(int newCapacity);
 316
 317 protected:
 318         /**
 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.
 321          *
 322          * @since 2.0
 323          */
 324         BufferBase(void);
 325
 326         /**
 327          * Initializes this instance of %BufferBase with the specified @c capacity.
 328          *
 329          * @since 2.0
 330          *
 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.
 336          */
 337         result Construct(int capacity);
 338
 339         /**
 340          * Increments the reference count by one.
 341          *
 342          * @since 2.0
 343          */
 344         long AddRef(void) const;
 345
 346
 347         /**
 348          * Decrements the reference count by one.
 349          *
 350          * @since 2.0
 351          *
 352          * @return              The reference count after decrement
 353          */
 354         long Release(void) const;
 355
 356         /**
 357          * Decreases the reference count. @n
 358          * After that, it frees the resource (memory allocation) if the reference count is zero.
 359          *
 360          * @since 2.0
 361          */
 362         virtual void Dispose(void);
 363
 364         /*
 365          * @class               _BufferData
 366          * @brief               This class encapsulates the @c byte array used by the buffer classes.
 367          *
 368          * @since 2.0
 369          *
 370          */
 371         class _BufferData
 372         {
 373         public:
 374                 //
 375                 //  This is the default constructor for this class.
 376                 //
 377                 //  @since 2.0
 378                 //
 379                 _BufferData(void);
 380
 381                 //
 382                 //  This is the destructor for this class.
 383                 //
 384                 // @since 2.0
 385                 //
 386                 virtual ~_BufferData(void);
 387
 388                 //
 389                 // Gets the pointer to the byte array.
 390                 //
 391                 // @since 2.0
 392                 // @return              Pointer to the @c byte array
 393                 //
 394                 byte* GetArray(void);
 395
 396
 397                 // Attribute
 398                 unsigned long long capacityInByte;
 399                 long refCount;
 400
 401         }; // _BufferData
 402
 403
 404         int _capacity;
 405         int _position;
 406         int _limit;
 407         int _mark;
 408         _BufferData* _pData;
 409         byte* __pArrayStart;
 410
 411
 412 private:
 413         /**
 414          * Returns the size of the type of the current %BufferBase instance.
 415          *
 416          * @return              The size of the type of the current %BufferBase instance
 417          */
 418         virtual int GetTypeSize(void) const = 0;
 419
 420         /**
 421          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 422          */
 423         BufferBase(const BufferBase& obj);
 424
 425         /**
 426          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 427          */
 428         BufferBase& operator =(const BufferBase& rhs);
 429
 430         friend class _BufferBaseImpl;
 431         class _BufferBaseImpl* __pBufferBaseImpl;
 432
 433 }; // BufferBase
 434
 435 }} // Tizen::Base
 436
 437 #endif // _FBASE_BUFFER_BASE_H_