inc/FBaseBufferBase.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FBaseBufferBase.h
  20  * @brief               This is the header file for the %BufferBase class.
  21  *
  22  * This header file contains the declarations of the %BufferBase class.
  23  */
  24
  25 #ifndef _FBASE_BUFFER_BASE_H_
  26 #define _FBASE_BUFFER_BASE_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseRtMutex.h>
  31
  32 namespace Tizen { namespace Base
  33 {
  34
  35 /**
  36  * @enum PositionTo
  37  *
  38  * Defines position.
  39  *
  40  * @since 2.0
  41  */
  42 enum PositionTo
  43 {
  44         POSITION_TO_ZERO = 0,   /**< The position is set to zero */
  45         POSITION_TO_MARK = 1,   /**< The position is set to the mark */
  46 };
  47
  48
  49 /**
  50  * @class       BufferBase
  51  * @brief       This class is the abstract base class of all buffer classes.
  52  *
  53  * @since 2.0
  54  *
  55  * The %BufferBase class is the abstract base class of all buffer classes.
  56  *
  57  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/buffer.htm">Buffer</a>.
  58  *
  59  * @see         Tizen::Base::ByteBuffer
  60  * @see         Tizen::Base::Buffer< Type >
  61  */
  62
  63 class _OSP_EXPORT_ BufferBase
  64         : public Object
  65 {
  66
  67 // Forward declaration
  68 protected:
  69         class _BufferData;
  70
  71 public:
  72         /**
  73          * This destructor overrides Tizen::Base::Object::~Object().
  74          *
  75          * @since 2.0
  76          */
  77         virtual ~BufferBase(void);
  78
  79         /**
  80          * Clears the calling %BufferBase object. @n
  81          * The buffer's position is set to @c 0, the limit is set to the capacity, and the mark is discarded.
  82          *
  83          * @since 2.0
  84          */
  85         void Clear(void);
  86
  87         /**
  88          * Copies the elements between the current position and limit (that are also known as remaining
  89          * elements), to the beginning of the calling %BufferBase instance.
  90          *
  91          * @since 2.0
  92          *
  93          * @remarks             After copying, the position is set to the number of elements copied rather than to @c 0,
  94          *                              so that an invocation of this method can be followed immediately by an invocation
  95          *                              of another relative set method. The limit is set to the capacity, and the mark is discarded.
  96          */
  97         void Compact(void);
  98
  99         /**
 100          * Flips the calling %BufferBase instance. @n
 101          * It sets the limit to the current position
 102          * and sets the position to either @c 0 or the mark, depending on the input value.
 103          *
 104          * @since 2.0
 105          *
 106          * @param[in]       to    The value to set the buffer position @n
 107          *                        The parameter may contain @c POSITION_TO_ZERO or @c POSITION_TO_MARK.
 108          * @remarks             If @c to is POSITION_TO_ZERO (or unspecified), the position is set to @c 0 after setting a limit to
 109          *                              the current position, and the mark is discarded.
 110          *                              Otherwise, if @c to is POSITION_TO_MARK, the position is set to the mark and
 111          *                              the mark is not discarded. 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 The current state of the instance prohibits the execution of the specified operation. @n
 164          *                                                                      The mark has not been set.
 165          * @remarks             Invoking this method neither changes nor discards the mark's value.
 166          */
 167         result Reset(void);
 168
 169         /**
 170          * Rewinds the current instance of %BufferBase. @n
 171          * It sets the position to
 172          * @c 0, discards the mark, and leaves the limit unchanged.
 173          *
 174          * @since 2.0
 175          */
 176         void Rewind(void);
 177
 178         /**
 179          * Shifts the limit of the current instance of %BufferBase. @n
 180          * The new limit is the current limit plus the given amount.
 181          *
 182          * @since 2.0
 183          *
 184          * @return              An error code
 185          * @param[in]   amount  The quantity of shift needed
 186          * @exception   E_SUCCESS                       The method is successful.
 187          * @exception   E_OUT_OF_RANGE          The value of an argument is outside the valid range defined by the method. @n
 188          *                                                                      The @c amount is larger than the capacity or smaller than @c 0 starting from the current limit.
 189          * @remarks             If the position is larger than the new limit, it is set to the new limit.
 190          *                              If the mark is defined and larger than the new limit, it is discarded.
 191          * @see                 SetLimit()
 192          */
 193         result ShiftLimit(int amount);
 194
 195         /**
 196          * Gets the capacity of the calling %BufferBase instance.
 197          *
 198          * @since 2.0
 199          *
 200          * @return              The capacity of the calling object
 201          */
 202         int GetCapacity(void) const;
 203
 204
 205         /**
 206          * Gets the limit of the calling %BufferBase instance.
 207          *
 208          * @since 2.0
 209          *
 210          * @return              The limit of the calling object
 211          * @see                         SetLimit()
 212          */
 213         int GetLimit(void) const;
 214
 215
 216         /**
 217          * Gets the mark of the calling %BufferBase instance. @n
 218          * If the mark has not been set, it returns @c -1.
 219          *
 220          * @since 2.0
 221          *
 222          * @return              The mark of the calling %BufferBase instance
 223          * @see                         SetMark()
 224          */
 225         int GetMark(void) const;
 226
 227
 228         /**
 229          * Gets the current position of the calling %BufferBase instance.
 230          *
 231          * @since 2.0
 232          *
 233          * @return              The current position of the calling %BufferBase instance
 234          * @see                         SetPosition()
 235          */
 236         int GetPosition(void) const;
 237
 238
 239         /**
 240          * Gets the number of elements between the current position and the limit
 241          * of the calling %BufferBase instance.
 242          *
 243          * @since 2.0
 244          *
 245          * @return              The number of elements between the current position and the limit
 246          * @see                         HasRemaining()
 247          */
 248         int GetRemaining(void) const;
 249
 250
 251         /**
 252          * Sets the limit of the calling %BufferBase instance.
 253          *
 254          * @since 2.0
 255          *
 256          * @return              An error code
 257          * @param[in]   limit   The new limit
 258          * @exception   E_SUCCESS                       The method is successful.
 259          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method. @n
 260          *                                                                      The @c limit is larger than the capacity or less than @c 0.
 261          * @remarks             If the position is larger than the new limit, it is set to the new limit.
 262          *                              If the mark is defined and larger than the new limit, it is discarded.
 263          * @see                 GetLimit()
 264          */
 265         result SetLimit(int limit);
 266
 267
 268         /**
 269          * Sets the mark of the current instance of %BufferBase at the current position. @n
 270          * If this method is called after InvalidateMark(), the mark is set to @c -1.
 271          *
 272          * @since 2.0
 273          *
 274          * @see                 GetMark()
 275          */
 276         void SetMark(void);
 277
 278
 279         /**
 280          * Sets the position of the calling %BufferBase instance.
 281          *
 282          * @since 2.0
 283          *
 284          * @return              An error code
 285          * @param[in]   position        The new position
 286          * @exception   E_SUCCESS                       The method is successful.
 287          * @exception   E_OUT_OF_RANGE           The value of an argument is outside the valid range defined by the method. @n
 288          *                                                                      The @c position is larger than the current limit or less than @c 0.
 289          * @remarks             If the mark is defined and larger than the new position then it is discarded.
 290          * @see                 GetPosition()
 291          */
 292         result SetPosition(int position);
 293
 294         /**
 295          * Returns @c true if there is at least one element between the current position and
 296          * the limit of the current instance of %BufferBase. Otherwise, it returns @c false.
 297          *
 298          * @since 2.0
 299          *
 300          * @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          *                               else @c false
 302          * @see                         GetRemaining()
 303          */
 304         bool HasRemaining(void) const;
 305
 306         /**
 307          * Expands the capacity and the limit of the internal buffer with the specified capacity.
 308          *
 309          * @since 2.0
 310          *
 311          * @return              An error code
 312          * @param[in]   newCapacity             The new capacity of this instance
 313          * @exception   E_SUCCESS                       The method is successful.
 314          * @exception   E_INVALID_ARG   The specified @c capacity is less than the current capacity.
 315          * @remarks             After calling this method, the address of the internal buffer may be either the same or a new location.
 316          */
 317         result ExpandCapacity(int newCapacity);
 318
 319 protected:
 320         /**
 321          * The object is not fully constructed after this constructor is called. For full construction,
 322          * the Construct() method must be called right after calling this constructor.
 323          *
 324          * @since 2.0
 325          */
 326         BufferBase(void);
 327
 328         /**
 329          * Initializes this instance of %BufferBase with the specified @c capacity.
 330          *
 331          * @since 2.0
 332          *
 333          * @return              An error code
 334          * @param[in]   capacity        The number of elements
 335          * @exception   E_SUCCESS               The method is successful.
 336          * @exception   E_INVALID_ARG   A specified input parameter is invalid. @n
 337          *                                                                The @c capacity is negative.
 338          */
 339         result Construct(int capacity);
 340
 341         /**
 342          * Increments the reference count by one.
 343          *
 344          * @since 2.0
 345          */
 346         long AddRef(void) const;
 347
 348
 349         /**
 350          * Decrements the reference count by one.
 351          *
 352          * @since 2.0
 353          *
 354          * @return              The reference count after decrement
 355          */
 356         long Release(void) const;
 357
 358         /**
 359          * Decreases the reference count. @n
 360          * After that, it frees the resource (memory allocation) if the reference count is zero.
 361          *
 362          * @since 2.0
 363          */
 364         virtual void Dispose(void);
 365
 366         /*
 367          * @class               _BufferData
 368          * @brief               This class encapsulates the @c byte array used by the buffer classes.
 369          *
 370          * @since 2.0
 371          *
 372          */
 373         class _BufferData
 374         {
 375         public:
 376                 //
 377                 //  This is the default constructor for this class.
 378                 //
 379                 //  @since 2.0
 380                 //
 381                 _BufferData(void);
 382
 383                 //
 384                 //  This is the destructor for this class.
 385                 //
 386                 // @since 2.0
 387                 //
 388                 virtual ~_BufferData(void);
 389
 390                 //
 391                 // Gets the pointer to the byte array.
 392                 //
 393                 // @since 2.0
 394                 // @return              Pointer to the @c byte array
 395                 //
 396                 byte* GetArray(void);
 397
 398
 399                 // Attribute
 400                 unsigned long long capacityInByte;
 401                 long refCount;
 402
 403         }; // _BufferData
 404
 405
 406         int _capacity;
 407         int _position;
 408         int _limit;
 409         int _mark;
 410         _BufferData* _pData;
 411         byte* __pArrayStart;
 412
 413
 414 private:
 415         /**
 416          * Returns the size of the type of the current %BufferBase instance.
 417          *
 418          * @return              The size of the type of the current %BufferBase instance
 419          */
 420         virtual int GetTypeSize(void) const = 0;
 421
 422         /**
 423          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 424          */
 425         BufferBase(const BufferBase& obj);
 426
 427         /**
 428          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 429          */
 430         BufferBase& operator =(const BufferBase& rhs);
 431
 432         friend class _BufferBaseImpl;
 433         class _BufferBaseImpl * __pBufferBaseImpl;
 434
 435 }; // BufferBase
 436
 437 }} // Tizen::Base
 438
 439 #endif // _FBASE_BUFFER_BASE_H_