inc/FBaseByteBuffer.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                FBaseByteBuffer.h
  19  * @brief               This is the header file for the %ByteBuffer class.
  20  *
  21  * This header file contains the declarations of the %ByteBuffer class.
  22  */
  23 #ifndef _FBASE_BYTE_BUFFER_H_
  24 #define _FBASE_BYTE_BUFFER_H_
  25
  26 #include <FBaseBufferBase.h>
  27 #include <FBaseBuffer.h>
  28
  29
  30 namespace Tizen { namespace Base
  31 {
  32
  33 /**
  34  * @class       ByteBuffer
  35  * @brief       This class provides a contiguous sequence of the @c byte (@c unsigned @c char) built-in type.
  36  *
  37  * @since 2.0
  38  *
  39  * The %ByteBuffer class provides a means of encapsulating a sequence of bytes in the memory. It defines
  40  * methods to read and write all primitive built-in types (except @c bool), to and from a sequence of
  41  * bytes. These methods read the size of primitive type bytes from a @c byte sequence and
  42  * convert it to the actual primitive type.
  43  *
  44  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/buffer.htm">Buffer</a>.
  45  *
  46  * @see         Tizen::Base::BufferBase
  47  *
  48  * The following example demonstrates how to use the %ByteBuffer class.
  49  *
  50  * @code
  51  *      #include <FBase.h>
  52  *
  53  *      using namespace Tizen::Base;
  54  *
  55  *      void
  56  *      MyClass::ByteBufferSample(void)
  57  *      {
  58  *              // Defines the maximum buffer size : capacity
  59  *              const int BUFFER_SIZE_MAX = 1024;
  60  *
  61  *              // Initializes a buf using the Construct method to the capacity
  62  *              ByteBuffer buf;
  63  *              buf.Construct(BUFFER_SIZE_MAX);
  64  *
  65  *              // Copies five values into the buf
  66  *              for (int i = 0; i < 5; i++)
  67  *              {
  68  *                      byte b = 'A' + i;
  69  *
  70  *                      // Writes byte b to the current position of the buf
  71  *                      buf.SetByte(b); // The position is incremented by one
  72  *              }
  73  *              // The position is moved to 5
  74  *
  75  *              // Flips the buf
  76  *              buf.Flip();
  77  *              // Now, position = 0 and limit = 5
  78  *
  79  *              // Reads bytes from the buf using "relative access method"
  80  *              while (buf.HasRemaining())
  81  *              {
  82  *                      byte b;
  83  *
  84  *                      // Reads byte b from the current position of the buf
  85  *                      buf.GetByte(b); // The position is incremented by one
  86  *              }
  87  *
  88  *
  89  *              // Clears the buf
  90  *              buf.Clear();
  91  *              // The buf's position = 0 and limit = capacity
  92  *
  93  *              // Writes int values to the buf
  94  *              for (int i = 0; i < 5; i++)
  95  *              {
  96  *                      // Writes int value at the current position
  97  *                      buf.SetInt(i); // The position is incremented by sizeof(int)
  98  *              }
  99  *
 100  *              // Flips the buf
 101  *              buf.Flip();
 102  *              // Now, position = 0 and limit = sizeof(int) * 5
 103  *
 104  *              // Creates a new view, IntBuffer.
 105  *              // Capacity of intBuf = 5
 106  *              // The content of intBuf is from the buf's position to the buf's limit
 107  *              IntBuffer* pIntBuf = buf.AsIntBufferN();
 108  *
 109  *              // Tests whether the change in view buffer(IntBuffer) is visible in original buffer(ByteBuffer)
 110  *              pIntBuf->Set(4, 9);
 111  *
 112  *              // Reads int values from the buf using "absolute access method"
 113  *              for (int i = 0; i < 5; i++)
 114  *              {
 115  *                      int out;
 116  *
 117  *                      // Reads int value from the buf with the specified index.
 118  *                      buf.GetInt((i * sizeof(int)), out);             // 0, 1, 2, 3, 9
 119  *                                                                                                      //  The position is not changed
 120  *              }
 121  *
 122  *              delete pIntBuf;
 123  *
 124  *      }
 125  *
 126  * @endcode
 127  */
 128 class _OSP_EXPORT_ ByteBuffer
 129         : public BufferBase
 130 {
 131
 132 public:
 133         /**
 134          * The object is not fully constructed after this constructor is called. @n
 135          * For full construction, the Construct() method must be called right after calling this constructor.
 136          *
 137          * @since 2.0
 138          *
 139          * @remarks             After creating an instance of %ByteBuffer, one of the Construct() methods must be called explicitly to initialize this instance.
 140          */
 141         ByteBuffer(void);
 142
 143         /**
 144          * This destructor overrides Tizen::Base::Object::~Object().
 145          *
 146          * @since 2.0
 147          */
 148         virtual ~ByteBuffer(void);
 149
 150         /**
 151          * Initializes this instance of %ByteBuffer which is a view of the specified @c buffer. @n
 152          * This is the copy constructor of the %ByteBuffer class.
 153          *
 154          * @since 2.0
 155          *
 156          * @param[in]   buffer          The %ByteBuffer instance used to initialize the new object
 157          * @exception   E_SUCCESS               The method is successful.
 158          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 159          *                                                              - A specified input parameter is invalid.
 160          *                                                              - The source buffer has not been constructed.
 161          * @see                                                 ByteBuffer()
 162          */
 163         result Construct(const ByteBuffer& buffer);
 164
 165         /**
 166          * Initializes this instance of %ByteBuffer with the specified @c capacity.
 167          *
 168          * @since 2.0
 169          *
 170          * @return              An error code
 171          * @param[in]   capacity                The number of elements
 172          * @exception   E_SUCCESS               The method is successful.
 173          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 174          *                                                              - A specified input parameter is invalid.
 175          *                                                              - The specified @c capacity is negative.
 176          * @see                                                 ByteBuffer()
 177          */
 178         result Construct(int capacity);
 179
 180         /**
 181         * Initializes this instance of %ByteBuffer with the specified @c buffer which is shared with this instance.
 182         *
 183         * @since 2.0
 184         *
 185         * @return                       An error code
 186         * @param[in]            pBuffer                         The shared buffer
 187         * @param[in]            index                           The starting index of the buffer from where the first @c byte value is read
 188         * @param[in]            length                          The number of bytes to read from the given buffer @n
 189         *                                                                               This is the limit of this instance.
 190         * @param[in]            capacity                        The capacity of this instance
 191         * @exception            E_SUCCESS                       The method is successful.
 192         * @exception            E_INVALID_ARG           Either of the following conditions has occurred:
 193         *                                                                               - A specified input parameter is invalid.
 194         *                                                                               - The specified @c pBuffer is @c null.
 195         * @exception       E_OUT_OF_RANGE               Either of the following conditions has occurred:
 196         *                                                                               - The specified @c index is outside the bounds of the data structure.
 197         *                                                                               - The specified @c index is larger than or equal to the specfied @c capacity.
 198         */
 199         result Construct(const byte* pBuffer, int index, int length, int capacity);
 200
 201         /**
 202          * Gets a reference to the @c byte value at the specified @c index.
 203          *
 204          * @since               2.0
 205          *
 206          * @return              A reference to the @c byte value
 207          * @param[in]   index   The index of the @c byte value in the calling %ByteBuffer instance @n
 208          *                                              It must be less than the limit.
 209          */
 210         byte& operator [](int index);
 211
 212         /**
 213          * Gets the @c byte value at the specified @c index of the constant object.
 214          *
 215          * @since 2.0
 216          *
 217          * @return              The @c byte value at the specified @c index
 218          * @param[in]   index   The index of the @c byte value in the calling %ByteBuffer instance @n
 219          *                                              It must be less than the limit.
 220          */
 221         byte operator [](int index) const;
 222
 223         /**
 224          * Compares two %ByteBuffer instances.
 225          *
 226          * @since 2.0
 227          *
 228          * @return              @c true if the input buffer is equal to the calling %ByteBuffer instance, @n
 229          *                              else @c false
 230          * @param[in]   buffer  The %ByteBuffer instance to compare with the current instance
 231          * @remarks                     This method returns @c true if the two buffers have the same number of
 232          *                              remaining elements, and the sequences of the remaining elements are equal
 233          *                              (considered independently, irrespective of their starting positions).
 234          * @see                                 Equals()
 235          */
 236         bool operator ==(const ByteBuffer& buffer) const;
 237
 238         /**
 239          * Checks whether the current instance and the specfied %ByteBuffer instance are not equal.
 240          *
 241          * @since 2.0
 242          *
 243          * @return              @c true if the current instance and the specified %ByteBuffer instance are not equal, @n
 244          *                              else @c false
 245          * @param[in]   buffer  The %ByteBuffer instance to compare with the current instance
 246          * @remarks             This method returns @c false if the two buffers have the same
 247          *                              number of remaining elements, and the sequences of the remaining elements are equal
 248          *                              (considered independently, irrespective of their starting positions).
 249          * @see                                 Equals()
 250          */
 251         bool operator !=(const ByteBuffer& buffer) const;
 252
 253         /**
 254          * Creates a new @c double buffer view for the content of the byte buffer.
 255          *
 256          * @since 2.0
 257          *
 258          * @return              DoubleBuffer    A pointer to the current position of the calling object
 259          * @remarks
 260          *                              - The content of the view buffer starts at the current position of the calling buffer.
 261          *                              - The new buffer's position is zero, the mark is undefined, and the capacity and limit
 262          *                              are equal to the remaining part of the calling buffer divided by the size of the @c double value.
 263          *                              - Any change to the byte buffer content is visible in the @c double buffer view, and vice versa.
 264          */
 265         DoubleBuffer* AsDoubleBufferN(void) const;
 266
 267         /**
 268          * Creates a new @c float buffer view for the content of the byte buffer.
 269          *
 270          * @since 2.0
 271          *
 272          * @return              FloatBuffer     A pointer to the current position of the calling buffer
 273          * @remarks
 274          *                              - The content of the view buffer starts at the current position of the calling buffer.
 275          *                              - The new buffer's position is zero, the mark is undefined, and the capacity and limit
 276          *                              are equal to the remaining part of the calling buffer divided by the size of the @c float value.
 277          *                              - Any change to the byte buffer content is visible in the @c float buffer view, and vice versa.
 278          */
 279         FloatBuffer* AsFloatBufferN(void) const;
 280
 281         /**
 282          * Creates a new @c int buffer view for the content of the byte buffer.
 283          *
 284          * @since 2.0
 285          *
 286          * @return              IntBuffer               A pointer to the current position of the calling buffer
 287          * @remarks
 288          *                              - The content of the view buffer starts at the current position of the calling buffer.
 289          *                              - The new buffer's position is zero, the mark is undefined, and the capacity and limit
 290          *                              are equal to the remaining part of the calling buffer divided by the size of the @c int value.
 291          *                              - Any change to the byte buffer content is visible in the @c int buffer view, and vice versa.
 292          */
 293         IntBuffer* AsIntBufferN(void) const;
 294
 295         /**
 296          * Creates a new @c long buffer view for the content of the byte buffer.
 297          *
 298          * @since 2.0
 299          *
 300          * @return              LongBuffer              A pointer to the current position of the calling buffer
 301          * @remarks
 302          *                              - The content of the view buffer starts at the current position of the calling buffer.
 303          *                              - The new buffer's position is zero, the mark is undefined, and the capacity and limit
 304          *                              are equal to the remaining part of the calling buffer divided by the size of the @c long value.
 305          *                              - Any change to the byte buffer content is visible in the @c long buffer view, and vice versa.
 306          */
 307         LongBuffer* AsLongBufferN(void) const;
 308
 309         /**
 310          * Creates a new @c long @c long buffer view for the content of the byte buffer.
 311          *
 312          * @since 2.0
 313          *
 314          * @return              LongLongBuffer  A pointer to the current position of the calling buffer
 315          * @remarks
 316          *                              - The content of the view buffer starts at the current position of the calling buffer.
 317          *                              - The new buffer's position is zero, the mark is undefined, and the capacity and limit
 318          *                              are equal to the remaining part of the calling buffer divided by the size of the @c long @c long value.
 319          *                              - Any change to the byte buffer content is visible in the @c long @c long buffer view, and vice versa.
 320          */
 321         LongLongBuffer* AsLongLongBufferN(void) const;
 322
 323         /**
 324          * @if OSPDEPREC
 325          * Creates a new @c mchar buffer view of the underlying content of the byte buffer.
 326          *
 327          * @brief               <i> [Deprecated] </i>
 328          * @deprecated  This method is deprecated as @c mchar type is changed to @c wchar_t type.
 329          *                              Instead of using this method, use the AsWcharBufferN() method.
 330          * @since 2.0
 331          *
 332          * @return              McharBuffer     A pointer to the current position of the calling buffer
 333          * @remarks
 334          *                              - The content of the view buffer starts at the current position of the calling buffer.
 335          *                              - The new buffer's position is zero, the mark is undefined, and the capacity and limit
 336          *                              are equal to the remaining part of the calling buffer divided by the size of the @c mchar value.
 337          *                              - Any change to the byte buffer content is visible in the @c mchar buffer view, and vice versa.
 338          * @endif
 339          */
 340         McharBuffer* AsMcharBufferN(void) const;
 341
 342         /**
 343          * Creates a new @c wchar buffer view of the underlying content of the byte buffer.
 344          *
 345          * @since 2.0
 346          *
 347          * @return              WcharBuffer     A pointer to the current position of the calling buffer
 348          * @remarks
 349          *                              - The content of the view buffer start at the current position of the calling buffer.
 350          *                              - The new buffer's position is zero, the mark is undefined, and the capacity and limit
 351          *                              are equal to the remaining part of the calling buffer divided by the size of the @c wchar value.
 352          *                              - Any change to the byte buffer content is visible in the @c wchar buffer view, and vice versa.
 353          */
 354         WcharBuffer* AsWcharBufferN(void) const;
 355
 356         /**
 357          * Creates a new @c short buffer view for the content of the byte buffer.
 358          *
 359          * @since 2.0
 360          *
 361          * @return              ShortBuffer     A pointer to the current position of the calling buffer
 362          * @remarks
 363          *                              - The content of the view buffer starts at the current position of the calling buffer.
 364          *                              - The new buffer's position is zero, the mark is undefined, and the capacity and limit
 365          *                              are equal to the remaining part of the calling buffer divided by the size of the @c short value.
 366          *                              - Any change to the byte buffer content is visible in the @c short buffer view, and vice versa.
 367          */
 368         ShortBuffer* AsShortBufferN(void) const;
 369
 370         /**
 371          * Copies the remaining bytes of the input %ByteBuffer instance into the calling %ByteBuffer object. @n
 372          * It returns @c E_OVERFLOW if the remaining bytes in the current instance are less
 373          * than the remaining bytes in the input instance.
 374          *
 375          * @since 2.0
 376          *
 377          * @return              An error code
 378          * @param[in]   buffer                  The source buffer from which bytes are read @n
 379          *                                                              It must not be the calling object.
 380          * @exception   E_SUCCESS               The method is successful.
 381          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 382          *                                                              - A specified input parameter is invalid.
 383          *                                                              - The source buffer is same as the destination buffer,
 384          *                                                                that is, the current instance of the buffer.
 385          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
 386          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
 387          *                                                              - The number of remaining bytes in the current buffer is smaller than
 388          *                                                                the number of remaining bytes in the input buffer.
 389          * @remarks
 390          *                              - After the copy operation, the current (destination) buffer's position and the given
 391          *                              (source) buffer's positions are incremented by the number of bytes copied (the number of
 392          *                              remaining bytes in the given buffer).
 393          *                              - If the remaining part of the current instance is greater than or equal to the remaining part of the input instance,
 394          *                              the effect of this method and the ReadFrom() method is the same. @n
 395          *                              If the remaining part of the current instance is less, the %ReadFrom() method
 396          *                              copies the number of remaining elements of the current instance while this method returns @c E_OVERFLOW and does not copy.
 397          *
 398          * The following example demonstrates how to use the %CopyFrom() method.
 399          *
 400          * @code
 401          *
 402          *      // Creates instances of ByteBuffer to act as source and destination buffers
 403          *      ByteBuffer srcBuf;
 404          *      ByteBuffer destBuf;
 405          *
 406          *      // Declares an array of byte values
 407          *      byte pArray[] = {'A','B','C','D','E','F','G','H','I','J'};
 408          *
 409          *      // Initializes the source array with a capacity of ten elements.
 410          *      srcBuf.Construct(10);
 411          *
 412          *      // Copies the ten values from pArray starting at position 0 to the srcBuf
 413          *      // Now, srcBuf's position = 10
 414          *      srcBuf.SetArray(pArray, 0, 10);
 415          *
 416          *      // Flips the buffer: The limit is set to the current position and
 417          *      // then the position is set to zero
 418          *      srcBuf.Flip();                  // srcBuf's position = 0 and limit = 10
 419          *
 420          *
 421          *      destBuf.Construct(20);
 422          *
 423          *      // Copies from the srcBuf to the destBuf
 424          *      // Now, srcBuf's position = 10, the destBuf's position = 10
 425          *      destBuf.CopyFrom(srcBuf);
 426          *
 427          * @endcode
 428          *
 429          * The following example has exactly the same effect as the above %CopyFrom() method.
 430          *
 431          * @code
 432          *
 433          *      int copyNum = srcBuf.GetRemaining();
 434          *      for (int i = 0; i < copyNum; i++)
 435          *      {
 436          *              byte b;
 437          *
 438          *              // Reads from source buffer
 439          *              srcBuf.GetByte(b);                      // The srcBuf position is incremented by 1
 440          *
 441          *              // Writes to destination buffer
 442          *              destBuf.SetByte(b);                     // The destBuf position is incremented by 1
 443          *
 444          *      }
 445          * @endcode
 446          */
 447         result CopyFrom(ByteBuffer& buffer);
 448
 449         /**
 450          * Gets the specified number of bytes from the current instance of %ByteBuffer.
 451          *
 452          * @since 2.0
 453          *
 454          * @return              An error code
 455          * @param[out]  pArray                  A pointer to the destination array into which the bytes are written
 456          * @param[in]   index                   The starting index of the array where the first byte is written
 457          * @param[in]   length                  The number of bytes to write into the given array
 458          * @exception   E_SUCCESS               The method is successful.
 459          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 460          *                                                              - A specified input parameter is invalid.
 461          *                                                              - The specified @c pArray is @c null.
 462          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 463          *                                                              - A specified input parameter is invalid.
 464          *                                                              - The specified @c index or the specified @c length is less than @c 0.
 465          * @exception   E_UNDERFLOW             Either of the following conditions has occurred:
 466          *                                                              - The operation (arithmetic/casting/conversion) has caused an underflow.
 467          *                                                              - The remaining bytes of this buffer are smaller than the specified @c length.
 468          * @remarks             This method copies @c length bytes from the current instance of %ByteBuffer into the given array,
 469          *                              starting from the current position and the given index in the array. @n
 470          *                              After the copy operation, the position is incremented by @c length bytes.
 471          * @see                 SetArray()
 472          */
 473         result GetArray(byte* pArray, int index, int length);
 474
 475         /**
 476          * Gets the @c byte value from the buffer at the current position, and then increments the position. @n
 477          * It provides a way to perform relative indexing and reading.
 478          *
 479          * @since 2.0
 480          *
 481          * @return              An error code
 482          * @param[out]  value                   The @c byte value at the current position in the %ByteBuffer instance
 483          * @exception   E_SUCCESS               The method is successful.
 484          * @exception   E_UNDERFLOW             Either of the following conditions has occurred:
 485          *                                                              - The operation (arithmetic/casting/conversion) has caused an underflow.
 486          *                                                              - The current position is not smaller than the limit.
 487          * @see                 SetByte()
 488          */
 489         result GetByte(byte& value);
 490
 491         /**
 492          * Gets the @c byte value at the given index. @n
 493          * It provides a way to perform absolute indexing and reading.
 494          *
 495          * @since 2.0
 496          *
 497          * @return              An error code
 498          * @param[in]   index                   The index of the current %ByteBuffer instance, from which the byte is read
 499          * @param[out]  value           The @c byte value at the given @c index
 500          * @exception   E_SUCCESS               The method is successful.
 501          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 502          *                                                              - The specified @c index is outside the bounds of the data structure.
 503          *                                                              - The specified @c index is not smaller than the limit.
 504          *                                                              - The specified @c index is less than @c 0.
 505          * @see                 SetByte()
 506          */
 507         result GetByte(int index, byte& value) const;
 508
 509         /**
 510          * Gets the size of the @c double number of bytes from the buffer at the current position, converts
 511          * it to the corresponding @c double equivalent, and then increments the position. @n
 512          * It provides a way to perform relative indexing and reading.
 513          *
 514          * @since 2.0
 515          *
 516          * @return              An error code
 517          * @param[out]  value                   The @c double value at the current position in the %ByteBuffer instance
 518          * @exception   E_SUCCESS               The method is successful.
 519          * @exception   E_UNDERFLOW             Either of the following conditions has occurred:
 520          *                                                              - The operation (arithmetic/casting/conversion) has caused an underflow.
 521          *                                                              - The remaining bytes in this buffer are smaller than the size of the @c double value.
 522          * @remarks             This method reads the next size of the @c double number of bytes at the current position,
 523          *                              converts it into a @c double value, and then increments the position by the size of the @c double value.
 524          * @see                 SetDouble()
 525          */
 526         result GetDouble(double& value);
 527
 528         /**
 529          * Gets the size of the @c double number of bytes at the given index and converts it to the equivalent @c double value. @n
 530          * It provides a way to perform absolute indexing and reading.
 531          *
 532          * @since 2.0
 533          *
 534          * @return              An error code
 535          * @param[in]   index                           The index of the current %ByteBuffer instance, from which the bytes are read
 536          * @param[out]  value                           The @c double value at the given @c index
 537          * @exception   E_SUCCESS                       The method is successful.
 538          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 539          *                                                                      - The specified @c index is outside the bounds of the data structure.
 540          *                                                                      - The specified @c index is larger than the limit minus the size of the @c double value.
 541          *                                                                      - The specified @c index is less than @c 0.
 542          * @remarks             This method reads the size of the @c double number of bytes at the given @c index
 543          *                              and converts it into a @c double value.
 544          * @see                 SetDouble()
 545          */
 546         result GetDouble(int index, double& value) const;
 547
 548         /**
 549          * Gets the size of the @c float number of bytes from the buffer at the current position, converts
 550          * it to the corresponding @c float equivalent, and then increments the position. @n
 551          * It provides a way to perform relative indexing and reading.
 552          *
 553          * @since 2.0
 554          *
 555          * @return              An error code
 556          * @param[out]  value                           The @c float value at the current position in the %ByteBuffer instance
 557          * @exception   E_SUCCESS                       The method is successful.
 558          * @exception   E_UNDERFLOW                     Either of the following conditions has occurred:
 559          *                                                                      - The operation (arithmetic/casting/conversion) has caused an underflow.
 560          *                                                                      - The remaining bytes of this buffer are smaller than the size of the @c float value.
 561          * @remarks             This method reads the next size of the @c float number of bytes at the current position,
 562          *                              converts it into a @c float value, and then increments the position by the size of the @c float value.
 563          * @see                 SetFloat()
 564          */
 565         result GetFloat(float& value);
 566
 567         /**
 568          * Gets the size of the @c float number of bytes at the given index and converts it to an equivalent @c float value. @n
 569          * It provides a way to perform absolute indexing and reading.
 570          *
 571          * @since 2.0
 572          *
 573          * @return              An error code
 574          * @param[in]   index                   The index of the current %ByteBuffer instance, from which the bytes are read
 575          * @param[out]  value                   The @c float value at the given @c index
 576          * @exception   E_SUCCESS                       The method is successful.
 577          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 578          *                                                                      - The specified @c index is outside the bounds of the data structure.
 579          *                                                                      - The specified @c index is larger than the limit minus the size of the @c float value.
 580          *                                                                      - The specified @c index is less than @c 0.
 581          * @remarks             This method reads the size of the @c float number of bytes at the given @c index
 582          *                              and converts it into a @c float value.
 583          * @see                 SetFloat()
 584          */
 585         result GetFloat(int index, float& value) const;
 586
 587         /**
 588          * Gets the size of the @c int number of bytes from the buffer at the current position, converts
 589          * it to the corresponding @c int equivalent, and then increments the position. @n
 590          * It provides a way to perform relative indexing and reading.
 591          *
 592          * @since 2.0
 593          *
 594          * @return              An error code
 595          * @param[out]  value                           The @c int value at the current position in the %ByteBuffer instance
 596          * @exception   E_SUCCESS                       The method is successful.
 597          * @exception   E_UNDERFLOW                     Either of the following conditions has occurred:
 598          *                                                                      - The operation (arithmetic/casting/conversion) has caused an underflow.
 599          *                                                                      - The remaining bytes of this buffer are smaller than the size of the @c int value.
 600          * @remarks             This method reads the next size of the @c int number of bytes at the current position,
 601          *                              converts them into an @c int value, and then increments the position by the size of the @c int value.
 602          * @see                 SetInt()
 603          */
 604         result GetInt(int& value);
 605
 606         /**
 607          * Gets the size of the @c int number of bytes at the given @c index and converts it to the equivalent @c int value. @n
 608          * It provides a way to perform absolute indexing and reading.
 609          *
 610          * @since 2.0
 611          *
 612          * @return              An error code
 613          * @param[in]   index                   The index of the current %ByteBuffer instance, from which the bytes are read
 614          * @param[out]  value                   The @c int value at the given @c index
 615          * @exception   E_SUCCESS                       The method is successful.
 616          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 617          *                                                                      - The specified @c index is outside the bounds of the data structure.
 618          *                                                                      - The specified @c index is larger than the limit minus the size of the @c int.
 619          *                                                                      - The specified @c index is negative.
 620          * @remarks             This method reads the size of the @c int number of bytes at the given @c index
 621          *                              and converts it into an @c int value.
 622          * @see                 SetInt()
 623          */
 624         result GetInt(int index, int& value) const;
 625
 626         /**
 627          * Gets the size of the @c long number of bytes from the buffer at the current position, converts
 628          * it to the corresponding @c long equivalent, and then increments the position. @n
 629          * It provides a way to perform relative indexing and reading.
 630          *
 631          * @since 2.0
 632          *
 633          * @return              An error code
 634          * @param[out]  value                           The @c long value at the current position in the %ByteBuffer instance
 635          * @exception   E_SUCCESS                       The method is successful.
 636          * @exception   E_UNDERFLOW                     Either of the following conditions has occurred:
 637          *                                                                      - The operation (arithmetic/casting/conversion) has caused an underflow.
 638          *                                                                      - The remaining bytes of this buffer are smaller than the size of the @c long value.
 639          * @remarks             This method reads the next size of the @c long number of bytes at the current position,
 640          *                              converts it into a @c long value, and then increments the position by the size of the @c long value.
 641          * @see                 SetLong()
 642          */
 643         result GetLong(long& value);
 644
 645         /**
 646          * Gets the size of the @c long number of bytes at the given @c index and converts it to the equivalent @c long value. @n
 647          * It provides a way to perform absolute indexing and reading.
 648          *
 649          * @since 2.0
 650          *
 651          * @return              An error code
 652          * @param[in]   index                   The index of the current %ByteBuffer instance, from which the bytes are read
 653          * @param[out]  value                   The @c long value at the given @c index
 654          * @exception   E_SUCCESS                       The method is successful.
 655          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 656          *                                                                      - The specified @c index is outside the bounds of the data structure.
 657          *                                                                      - The specified @c index is larger than the limit minus the size of the @c long value.
 658          *                                                                      - The specified @c index is less than @c 0.
 659          * @remarks             This method reads the size of the @c long number of bytes at the given @c index
 660          *                              and converts it into a @c long value.
 661          * @see                 SetLong()
 662          */
 663         result GetLong(int index, long& value) const;
 664
 665         /**
 666          * Gets the size of the @c long @c long number of bytes from the buffer at the current position, converts
 667          * it to the corresponding @c long @c long equivalent, and then increments the position. @n
 668          * It provides a way to perform relative indexing and reading.
 669          *
 670          * @since 2.0
 671          *
 672          * @return              An error code
 673          * @param[out]  value                           The @c long @c long value at the current position in the %ByteBuffer instance
 674          * @exception   E_SUCCESS                       The method is successful.
 675          * @exception   E_UNDERFLOW                     Either of the following conditions has occurred:
 676          *                                                                      - The operation (arithmetic/casting/conversion) has caused an underflow.
 677          *                                                                      - The remaining bytes of this buffer are smaller than the size of the @c long @c long value.
 678          * @remarks             This method reads the next size of the @c long @c long number of bytes at the current position,
 679          *                              converts it into a @c long @c long value, and then increments the position by the size of the @c long @c long value.
 680          * @see                 SetLongLong()
 681          */
 682         result GetLongLong(long long& value);
 683
 684         /**
 685          * Gets the size of the @c long @c long number of bytes at the given @c index and converts it to the equivalent @c long @c long value. @n
 686          * It provides a way to perform absolute indexing and reading.
 687          *
 688          * @since 2.0
 689          *
 690          * @return              An error code
 691          * @param[in]   index                   The index of the current %ByteBuffer instance, from which the bytes are read
 692          * @param[out]  value                   The @c long @c long value at the given @c index
 693          * @exception   E_SUCCESS                       The method is successful.
 694          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 695          *                                                                      - The specified @c index is outside the bounds of the data structure.
 696          *                                                                      - The specified @c index is larger than the limit minus the size of the @c long @c long value.
 697          *                                                                      - The specified @c index is less than @c 0.
 698          * @remarks             This method reads the size of the @c long @c long number of bytes at the given @c index
 699          *                              and converts it into a @c long @c long value.
 700          * @see                 SetLongLong()
 701          */
 702         result GetLongLong(int index, long long& value) const;
 703
 704         /**
 705          * @if OSPDEPREC
 706          * Gets the size of the @c wchar_t number of bytes from the buffer at the current position, converts
 707          * it to the corresponding @c wchar_t equivalent, and then increments the position. @n
 708          * It provides a way to perform relative indexing and reading.
 709          *
 710          * @brief               <i> [Deprecated] </i>
 711          * @deprecated  This method is deprecated as @c mchar type is changed to @c wchar_t type.
 712          *                              Instead of using this method, use the GetWchar(wchar_t& value) method.
 713          * @since 2.0
 714          *
 715          * @return              An error code
 716          * @param[out]  value                   The @c wchar_t value at the current position in the %ByteBuffer instance
 717          * @exception   E_SUCCESS               The method is successful.
 718          * @exception   E_UNDERFLOW             Either of the following conditions has occurred:
 719          *                                                              - The operation (arithmetic/casting/conversion) has caused an underflow.
 720          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c wchar_t value.
 721          * @remarks             This method reads the next size of the @c wchar_t number of bytes at the current position,
 722          *                              converts it into a @c wchar_t value, and then increments the position by the size of the @c wchar_t value.
 723          * @see                 SetMchar()
 724          * @endif
 725          */
 726         result GetMchar(wchar_t& value);
 727
 728         /**
 729          * Gets the size of the @c wchar_t number of bytes from the buffer at the current position, converts
 730          * it to the corresponding @c wchar_t equivalent, and then increments the position. @n
 731          * It provides a way to perform relative indexing and reading.
 732          *
 733          * @since 2.0
 734          *
 735          * @return  An error code
 736          * @param[out]  value                   The @c wchar_t value at the current position in the %ByteBuffer instance
 737          * @exception   E_SUCCESS               The method is successful.
 738          * @exception   E_UNDERFLOW             Either of the following conditions has occurred:
 739          *                                                              - The operation (arithmetic/casting/conversion) has caused an underflow.
 740          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c wchar_t value.
 741          * @remarks             This method reads the next size of the @c wchar_t number of bytes at the current position,
 742          *                              converts it into a @c wchar_t value, and then increments the position by the size of the @c wchar_t value.
 743          * @see                 SetWchar()
 744          */
 745         result GetWchar(wchar_t& value);
 746
 747         /**
 748          * @if OSPDEPREC
 749          * Provides a way to perform absolute indexing and reading. @n
 750          * It reads the size of the @c wchar_t number of bytes at the given @c index and converts it to the equivalent @c wchar_t value.
 751          *
 752          * @brief               <i> [Deprecated] </i>
 753          * @deprecated This method is deprecated as @c mchar type is changed to @c wchar_t type.
 754          *                         Instead of using this method, use the GetWchar(int index, wchar_t& value) method.
 755          * @since 2.0
 756          *
 757          * @return              An error code
 758          * @param[in]   index                   The index of the current %ByteBuffer instance, from which the bytes are read
 759          * @param[out]  value                   The @c wchar_t value at the given @c index
 760          * @exception   E_SUCCESS                       The method is successful.
 761          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 762          *                                                                      - The specified @c index is outside the bounds of the data structure.
 763          *                                                                      - The specified @c index is larger than the limit minus the size of the @c wchar_t value.
 764          *                                                                      - The specified @c index is less than @c 0.
 765          * @remarks             This method reads the size of the @c wchar_t number of bytes at the given @c index
 766          *                              and converts it into a @c wchar_t value.
 767          * @see                 SetMchar()
 768          * @endif
 769          */
 770         result GetMchar(int index, wchar_t& value) const;
 771
 772         /**
 773          * Provides a way to perform absolute indexing and reading. @n
 774          * It reads the size of the @c wchar_t number of bytes at the given @c index and converts it to the equivalent @c wchar_t value.
 775          *
 776          * @since 2.0
 777          *
 778          * @return              An error code
 779          * @param[in]   index                   The index of the current %ByteBuffer instance, from which the bytes are read
 780          * @param[out]  value                   The @c wchar_t value at the given @c index
 781          * @exception   E_SUCCESS               The method is successful.
 782          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 783          *                                                              - The specified @c index is outside the bounds of the data structure.
 784          *                                                              - The specified @c index is larger than the limit minus the size of the @c wchar_t value.
 785          *                                                              - The specified @c index is less than @c 0.
 786          * @remarks             This method reads the size of the @c wchar_t number of bytes at the given @c index
 787          *                              and converts it into a @c wchar_t value.
 788          * @see                 SetWchar()
 789          */
 790         result GetWchar(int index, wchar_t& value) const;
 791
 792         /**
 793          * Gets the size of the @c short number of bytes from the buffer at the current position, converts
 794          * it to the corresponding @c short equivalent, and then increments the position. @n
 795          * Provides a way to perform relative indexing and reading.
 796          *
 797          * @since 2.0
 798          *
 799          * @return              An error code
 800          * @param[out]  value                           The @c short value at the current position in the %ByteBuffer instance
 801          * @exception   E_SUCCESS                       The method is successful.
 802          * @exception   E_UNDERFLOW                     Either of the following conditions has occurred:
 803          *                                                                      - The operation (arithmetic/casting/conversion) has caused an underflow.
 804          *                                                                      - The remaining bytes of this buffer are smaller than the size of the @c short value.
 805          * @remarks             This method reads the next size of the @c short number of bytes at the current position,
 806          *                              converts it into a @c short value, and then increments the position by the size of the @c short value.
 807          * @see                 SetShort()
 808          */
 809         result GetShort(short& value);
 810
 811         /**
 812          * Gets the size of the @c short number of bytes at the given @c index and converts it to the equivalent @c short value. @n
 813          * Provides a way to perform absolute indexing and reading.
 814          *
 815          * @since 2.0
 816          *
 817          * @return              An error code
 818          * @param[in]   index                   The index of the current %ByteBuffer instance, from which the bytes are read
 819          * @param[out]  value                   The @c short value at the given @c index
 820          * @exception   E_SUCCESS                       The method is successful.
 821          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 822          *                                                                      - The specified @c index is outside the bounds of the data structure.
 823          *                                                                      - The specified @c index is larger than the limit minus the size of the @c short value.
 824          *                                                                      - The specified @c index is less than @c 0.
 825          * @remarks             This method reads the size of the @c short number of bytes at the given @c index
 826          *                              and converts it into a @c short value.
 827          * @see                 SetShort()
 828          */
 829         result GetShort(int index, short& value) const;
 830
 831         /**
 832          * Copies the remaining bytes of the input %ByteBuffer instance into the calling %ByteBuffer instance,
 833          * if the remaining part of the current instance is greater than or equal to the remaining part of the input instance. @n
 834          * Otherwise, the number of bytes copied is equal to the number of remaining elements of the current instance.
 835          *
 836          * @since 2.0
 837          *
 838          * @return              An error code
 839          * @param[in]   buffer                  The source buffer from which bytes are read @n
 840          *                                                              It must not be the calling %ByteBuffer instance.
 841          * @exception   E_SUCCESS               The method is successful.
 842          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 843          *
 844          * @remarks
 845          *                              - After the copy operation, the current (destination) buffer's position and the given
 846          *                              (source) buffer's position are incremented by the number of elements copied (the lesser of
 847          *                              the number of elements remaining in the current buffer and the given buffer).
 848          *                              - If the remaining part of the current instance is greater than or equal to the remaining part of the input instance,
 849          *                              the effect of this method is the same as the CopyFrom() method. @n
 850          *                              If the remaining part of the current instance is less, the %CopyFrom() method returns @c E_OVERFLOW and does not transfer;
 851          *                              whereas this method copies the number of remaining elements of the current instance.
 852          *
 853          * The following example demonstrates how to use the %ReadFrom() method.
 854          *
 855          * @code
 856          *
 857          *      // Creates instances of %ByteBuffer to act as source and destination buffers
 858          *      ByteBuffer srcBuf;
 859          *      ByteBuffer destBuf;
 860          *
 861          *      // Declares an array of byte values
 862          *      byte pArray[] = {'A','B','C','D','E','F','G','H','I','J'};
 863          *
 864          *      // Initializes the source array with capacity of ten elements.
 865          *      srcBuf.Construct(10);
 866          *
 867          *      // Copies the 10 values from pArray starting at position 0 to srcBuf
 868          *      // Now, srcBuf's position = 10
 869          *      srcBuf.SetArray(pArray, 0, 10);
 870          *
 871          *      // Flips the buffer: The limit is set to the current position and
 872          *      // then the position is set to zero
 873          *      srcBuf.Flip();  // srcBuf's position = 0 and limit = 10
 874          *
 875          *      // Initializes the destination buffer with capacity of ten elements
 876          *      destBuf.Construct(10);
 877          *
 878          *      // Sets the limit of destBuf to 5
 879          *      destBuf.SetLimit(5);
 880          *
 881          *      // Reads from the srcBuf to the destBuf
 882          *      // The destBuf's remaining is 5, smaller than the srcBuf's (10)
 883          *      // Therefore, five elements are transferred
 884          *      // srcBuf's position = 5, destBuf's position = 5
 885          *      destBuf.ReadFrom(srcBuf);
 886          *
 887          *
 888          * @endcode
 889          *
 890          * The following example has exactly the same effect as the above %ReadFrom() method.
 891          *
 892          * @code
 893          *
 894          *      int copyNum = (destBuf.GetRemaining() < srcBuf.GetRemaing())? destBuf.GetRemaining() : srcBuf.GetRemaining();
 895          *      for (int i = 0; i < copyNum; i++)
 896          *      {
 897          *              byte b;
 898          *
 899          *              // Reads from the source buffer
 900          *              srcBuf.GetByte(b); // The srcBuf position is incremented by 1
 901          *
 902          *              // Writes to the destination buffer
 903          *              destBuf.SetByte(b);     // The destBuf position is incremented by 1
 904          *
 905          *      }
 906          *
 907          * @endcode
 908          */
 909         result ReadFrom(ByteBuffer& buffer);
 910
 911         /**
 912          * Sets the @c byte values in the specified array to the current instance of %ByteBuffer.
 913          *
 914          * @since 2.0
 915          *
 916          * @return              An error code
 917          * @param[in]   pArray                  The array from which the bytes are read
 918          * @param[in]   index                   The starting index of the array from where the first @c byte value is read
 919          * @param[in]   length                  The number of bytes to read from the given array
 920          * @exception   E_SUCCESS               The method is successful.
 921          * @exception   E_INVALID_ARG   Either of the following conditions has occurred:
 922          *                                                              - A specified input parameter is invalid.
 923          *                                                              - The specified @c pArray is @c null.
 924          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
 925          *                                                              - The specified @c index is outside the bounds of the data structure.
 926          *                                                              - The specified @c index or the specified @c length is less than @c 0.
 927          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
 928          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
 929          *                                                              - The remaining bytes are smaller than the specified @c length.
 930          * @remarks             This method copies the specified number (@c length) of @c byte values from the source array
 931          *                              into the calling object of the buffer, starting from the current position,
 932          *                              and at the given index in the array. @n
 933          *                              After the copy operation, the position is incremented by @c length.
 934          * @see                 GetArray()
 935          */
 936         result SetArray(const byte* pArray, int index, int length);
 937
 938         /**
 939          * Sets the given @c byte value into the calling %ByteBuffer object
 940          * at the current position, and then increments the position. @n
 941          * It provides a way to perform relative indexing and writing.
 942          *
 943          * @since 2.0
 944          *
 945          * @return              An error code
 946          * @param[in]   value                   The @c byte value to write to the current instance of %ByteBuffer
 947          * @exception   E_SUCCESS               The method is successful.
 948          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
 949          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
 950          *                                                              - The current position is not smaller than the limit.
 951          * @see                 GetByte()
 952          */
 953         result SetByte(byte value);
 954
 955         /**
 956          * Sets the given @c byte value into the calling %ByteBuffer object at the specified @c index. @n
 957          * Provides a way to perform absolute indexing and writing.
 958          *
 959          * @since 2.0
 960          *
 961          * @return              An error code
 962          * @param[in]   index                           The index of the current instance of %ByteBuffer at which the byte is written
 963          * @param[in]   value                           The @c byte value to write
 964          * @exception   E_SUCCESS                       The method is successful.
 965          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 966          *                                                                      - The specified @c index is outside the bounds of the data structure.
 967          *                                                                      - The specified @c index is not smaller than the limit.
 968          *                                                                      - The specified @c index is less than @c 0.
 969          * @see                 GetByte()
 970          */
 971         result SetByte(int index, byte value);
 972
 973         /**
 974          * Sets the given @c double value into the calling %ByteBuffer object
 975          * at the current position, and then increments the position. @n
 976          * It provides a way to perform relative indexing and writing.
 977          *
 978          * @since 2.0
 979          *
 980          * @return              An error code
 981          * @param[in]   value                   The @c double value to write
 982          * @exception   E_SUCCESS               The method is successful.
 983          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
 984          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
 985          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c double value.
 986          * @remarks             This method writes the size of the @c double number of bytes containing the given @c double value
 987          *                              into the calling buffer, at the current position, and then increments the position by the size of the @c double value.
 988          * @see                 GetDouble()
 989          */
 990         result SetDouble(double value);
 991
 992         /**
 993          * Sets the given @c float value into the calling %ByteBuffer object
 994          * at the current position, and then increments the position. @n
 995          * It provides a way to perform relative indexing and writing.
 996          *
 997          * @since 2.0
 998          *
 999          * @return              An error code
1000          * @param[in]   value                   The @c float value to write
1001          * @exception   E_SUCCESS               The method is successful.
1002          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
1003          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
1004          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c float value.
1005          * @remarks             This method writes the size of the @c float number of bytes containing the given @c float value
1006          *                              into the calling buffer, at the current position, and then increments the position by the size of the @c float value.
1007          * @see                 GetFloat()
1008          */
1009         result SetFloat(float value);
1010
1011         /**
1012          * Sets the given @c int value into the calling %ByteBuffer instance at the current
1013          * position, and then increments the position. @n
1014          * It provides a way to perform relative indexing and writing.
1015          *
1016          * @since 2.0
1017          *
1018          * @return              An error code
1019          * @param[in]   value                   The @c int value to write
1020          * @exception   E_SUCCESS               The method is successful.
1021          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
1022          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
1023          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c int value.
1024          * @remarks             This method writes the size of the @c int number of bytes containing the given @c int value
1025          *                              into the calling buffer, at the current position, and then increments the position by the size of the @c int value.
1026          * @see                 GetInt()
1027          */
1028         result SetInt(int value);
1029
1030         /**
1031          * Sets the given @c long value into the calling %ByteBuffer instance at the current
1032          * position, and then increments the position. @n
1033          * It provides a way to perform relative indexing and writing.
1034          *
1035          * @since 2.0
1036          *
1037          * @return              An error code
1038          * @param[in]   value                   The @c long value to write
1039          * @exception   E_SUCCESS               The method is successful.
1040          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
1041          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
1042          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c long value.
1043          * @remarks             This method writes the size of the @c long number of bytes containing the given @c long value
1044          *                              into the calling buffer, at the current position, and then increments the position by the size of the @c long value.
1045          * @see                 GetLong()
1046          */
1047         result SetLong(long value);
1048
1049         /**
1050          * Sets the given @c long @c long value into the calling %ByteBuffer instance at the current
1051          * position, and then increments the position. @n
1052          * It provides a way to perform relative indexing and writing.
1053          *
1054          * @since 2.0
1055          *
1056          * @return              An error code
1057          * @param[in]   value                   The @c long @c long value to write
1058          * @exception   E_SUCCESS               The method is successful.
1059          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
1060          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
1061          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c long @c long value.
1062          * @remarks             This method writes the size of the @c long @c long number of bytes containing the given @c long @c long value
1063          *                              into the calling buffer, at the current position, and then increments the position by the size of the @c long @c long value.
1064          * @see                 GetLongLong()
1065          */
1066         result SetLongLong(long long value);
1067
1068         /**
1069          * @if OSPDEPREC
1070          * Sets the given @c wchar_t value into the calling %ByteBuffer instance at the current
1071          * position, and then increments the position. @n
1072          * It provides a way to perform relative indexing and writing.
1073          *
1074          * @brief               <i> [Deprecated] </i>
1075          * @deprecated  This method is deprecated as @c mchar type is changed to @c wchar_t type.
1076          *                              Instead of using this method, use the SetWchar(wchar_t value) method.
1077          * @since 2.0
1078          *
1079          * @return              An error code
1080          * @param[in]   value                   The @c wchar_t value to write
1081          * @exception   E_SUCCESS               The method is successful.
1082          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
1083          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
1084          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c wchar_t value.
1085          * @remarks             This method writes the size of the @c wchar_t number of bytes containing the given @c wchar_t value
1086          *                              into the calling buffer, at the current position, and then increments the position by the size of the @c wchar_t value.
1087          * @see                 GetMchar()
1088          * @endif
1089          */
1090         result SetMchar(wchar_t value);
1091
1092         /**
1093          * Sets the given @c wchar_t value into the calling %ByteBuffer instance at the current
1094          * position, and then increments the position. @n
1095          * It provides a way to perform relative indexing and writing.
1096          *
1097          * @since 2.0
1098          *
1099          * @return              An error code
1100          * @param[in]   value           The @c wchar_t value to write
1101          * @exception   E_SUCCESS               The method is successful.
1102          * @exception   E_OVERFLOW      Either of the following conditions has occurred:
1103          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
1104          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c wchar_t value.
1105          * @remarks     This method writes the size of the @c wchar_t number of bytes containing the given @c wchar_t value
1106          *                              into the calling buffer, at the current position, and then increments the position by the size of the @c wchar_t value.
1107          * @see                 GetWchar()
1108          */
1109         result SetWchar(wchar_t value);
1110
1111         /**
1112          * Sets the given @c short value into the current %ByteBuffer instance at the current
1113          * position, and then increments the position. @n
1114          * Provides a way to perform relative indexing and writing.
1115          *
1116          * @since 2.0
1117          *
1118          * @return              An error code
1119          * @param[in]   value                   The @c short value to write
1120          * @exception   E_SUCCESS               The method is successful.
1121          * @exception   E_OVERFLOW              Either of the following conditions has occurred:
1122          *                                                              - The operation (arithmetic/casting/conversion) has caused an overflow.
1123          *                                                              - The remaining bytes of this buffer are smaller than the size of the @c short value.
1124          * @remarks             This method writes the size of the @c short number of bytes containing the given @c short value
1125          *                              into the calling buffer, at the current position, and then increments the position by the size of the @c short value.
1126          * @see                 GetShort()
1127          */
1128         result SetShort(short value);
1129
1130         /**
1131          * Sets a @c double value at the specified @c index of the current %ByteBuffer instance. @n
1132          * It provides a way to perform absolute indexing and writing.
1133          *
1134          * @since 2.0
1135          *
1136          * @return              An error code
1137          * @param[in]   index                           The index of the current instance of %ByteBuffer at which the bytes are written
1138          * @param[in]   value                           The @c double value to write
1139          * @exception   E_SUCCESS                       The method is successful.
1140          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
1141          *                                                                      - The specified @c index is outside the bounds of the data structure.
1142          *                                                                      - The specified @c index is larger than the limit minus the size of the @c double value.
1143          *                                                                      - The specified @c index is less than @c 0.
1144          * @remarks             This method writes the size of the @c double number of bytes containing the given @c double value
1145          *                              into the calling buffer, at the given @c index.
1146          * @see                 GetDouble()
1147          */
1148         result SetDouble(int index, double value);
1149
1150         /**
1151          *  Sets a @c float value at the specified @c index of the calling %ByteBuffer instance. @n
1152          *  It provides a way to perform absolute indexing and writing.
1153          *
1154          * @since 2.0
1155          *
1156          * @return              An error code
1157          * @param[in]   index                           The index of the current instance of %ByteBuffer at which the bytes are written
1158          * @param[in]   value                           The @c float value to write
1159          * @exception   E_SUCCESS                       The method is successful.
1160          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
1161          *                                                                      - The specified @c index is outside the bounds of the data structure.
1162          *                                                                      - The specified @c index is larger than the limit minus the size of the @c float value.
1163          *                                                                      - The specified @c index is less than @c 0.
1164          * @remarks             This method writes the size of the @c float number of bytes containing the given @c float value
1165          *                              into the calling buffer, at the given @c index.
1166          * @see                 GetFloat()
1167          */
1168         result SetFloat(int index, float value);
1169
1170         /**
1171          * Sets a @c int value at the specified @c index of the calling %ByteBuffer instance. @n
1172          * It provides a way to perform absolute indexing and writing.
1173          *
1174          * @since 2.0
1175          *
1176          * @return              An error code
1177          * @param[in]   index                           The index of the current instance of %ByteBuffer at which the bytes are written
1178          * @param[in]   value                           The @c int value to write
1179          * @exception   E_SUCCESS                       The method is successful.
1180          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
1181          *                                                                      - The specified @c index is outside the bounds of the data structure.
1182          *                                                                      - The specified @c index is larger than the limit minus the size of the @c int value.
1183          *                                                                      - The specified @c index is less than @c 0
1184          * @remarks             This method writes the size of the @c int number of bytes containing the given @c int value
1185          *                              into the calling buffer, at the given @c index.
1186          * @see                 GetInt()
1187          */
1188         result SetInt(int index, int value);
1189
1190         /**
1191          * Sets a @c long value at the specified index of the calling %ByteBuffer instance. @n
1192          * It provides a way to perform absolute indexing and writing.
1193          *
1194          * @since 2.0
1195          *
1196          * @return              An error code
1197          * @param[in]   index                           The index at which the bytes are written
1198          * @param[in]   value                           The @c long value to write
1199          * @exception   E_SUCCESS                       The method is successful.
1200          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
1201          *                                                                      - The specified @c index is outside the bounds of the data structure.
1202          *                                                                      - The specified @c index is larger than the limit minus the size of the @c long value.
1203          *                                                                      - The specified @c index is less than @c 0.
1204          * @remarks             This method writes the size of the @c long number of bytes containing the given @c long value
1205          *                              into the calling buffer, at the given @c index.
1206          * @see                 GetLong()
1207          */
1208         result SetLong(int index, long value);
1209
1210         /**
1211          * Sets a @c long @c long value at the specified @c index of the calling %ByteBuffer instance. @n
1212          * It provides a way to perform absolute indexing and writing.
1213          *
1214          * @since 2.0
1215          *
1216          * @return              An error code
1217          * @param[in]   index                           The index at which the bytes are written
1218          * @param[in]   value                           The @c long @c long value to write
1219          * @exception   E_SUCCESS                       The method is successful.
1220          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
1221          *                                                                      - The specified @c index is outside the bounds of the data structure.
1222          *                                                                      - The specified @c index is larger than the limit minus the size of the @c long @c long value.
1223          *                                                                      - The specified @c index is less than @c 0.
1224          * @remarks             This method writes the size of the @c long @c long number of bytes containing the given @c long @c long value
1225          *                              into the calling buffer, at the given @c index.
1226          * @see                 GetLongLong()
1227          */
1228         result SetLongLong(int index, long long value);
1229
1230         /**
1231          * @if OSPDEPREC
1232          * Sets a @c wchar_t value at the specified @c index of the calling %ByteBuffer instance. @n
1233          * It provides a way to perform absolute indexing and writing.
1234          *
1235          * @brief               <i> [Deprecated] </i>
1236          * @deprecated  This method is deprecated as @c mchar type is changed to @c wchar_t type.
1237          *                              Instead of using this method, use the SetWchar(int index, wchar_t value) method.
1238          * @since 2.0
1239          *
1240          * @return              An error code
1241          * @param[in]   index                           The index at which the bytes are written
1242          * @param[in]   value                           The @c wchar_t value to write
1243          * @exception   E_SUCCESS                       The method is successful.
1244          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
1245          *                                                                      - The specified index is outside the bounds of the data structure.
1246          *                                                                      - The specified @c index is larger than the limit minus the size of the @c wchar_t value.
1247          *                                                                      - The specified @c index is less than @c 0.
1248          * @remarks             This method writes the size of the @c wchar_t number of bytes containing the given @c wchar_t value
1249          *                              into the calling buffer, at the given @c index.
1250          * @see                 GetMchar()
1251          * @endif
1252          */
1253         result SetMchar(int index, wchar_t value);
1254
1255         /**
1256          * Sets a @c wchar_t value at the specified @c index of the calling %ByteBuffer instance. @n
1257          * It provides a way to perform absolute indexing and writing.
1258          *
1259          * @since 2.0
1260          *
1261          * @return              An error code
1262          * @param[in]   index           The index at which the bytes are written
1263          * @param[in]   value           The @c wchar_t value to write
1264          * @exception   E_SUCCESS               The method is successful.
1265          * @exception   E_OUT_OF_RANGE  Either of the following conditions has occurred:
1266          *                                                              - The specified @c index is outside the bounds of the data structure.
1267          *                                                              - The specified @c index is larger than the limit minus the size of the @c wchar_t value.
1268          *                                                              - The specified @c index is less than @c 0.
1269          * @remarks             This method writes the size of the @c wchar_t number of bytes containing the given @c wchar_t value
1270          *                              into the calling buffer, at the given @c index.
1271          * @see                 GetWchar()
1272          */
1273         result SetWchar(int index, wchar_t value);
1274
1275         /**
1276          * Sets a @c short value at the specified @c index of the calling %ByteBuffer instance. @n
1277          * It provides a way to perform absolute indexing and writing.
1278          *
1279          * @since 2.0
1280          *
1281          * @return              An error code
1282          * @param[in]   index                           The index of at which the bytes are written
1283          * @param[in]   value                           The @c short value to write
1284          * @exception   E_SUCCESS                       The method is successful.
1285          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
1286          *                                                                      - The specified @c index is outside the bounds of the data structure.
1287          *                                                                      - The specified @c index is larger than the limit minus the size of the @c short value.
1288          *                                                                      - The specified @c index is less than @c 0.
1289          * @remarks             This method writes the size of the @c short number of bytes containing the given @c short value
1290          *                              into the calling buffer, at the given @c index.
1291          * @see                 GetShort()
1292          */
1293         result SetShort(int index, short value);
1294
1295         /**
1296          * Creates a new %ByteBuffer whose content is a shared portion of
1297          * the content of the calling %ByteBuffer instance.
1298          *
1299          * @since 2.0
1300          *
1301          * @return              A %ByteBuffer pointer to the current position of the calling object
1302          * @remarks
1303          *                              - The content of the new buffer starts at the current position of the calling %ByteBuffer object.
1304          *                              - The new buffer's position is zero, its capacity and limit are
1305          *                              the number of bytes remaining in the current instance of %ByteBuffer,
1306          *                              and its mark is undefined.
1307          */
1308         ByteBuffer* SliceN(void) const;
1309
1310         /**
1311          * Gets a pointer to the raw array of the calling buffer. @n
1312          * If the capacity is zero, it returns @c null.
1313          *
1314          * @since 2.0
1315          *
1316          * @return              A pointer to the raw array of the calling buffer
1317          */
1318         const byte* GetPointer(void) const;
1319
1320         /**
1321          * Gets a pointer to the raw array of the calling buffer. @n
1322          * If the capacity is zero, it returns @c null.
1323          *
1324          * @since 2.1
1325          *
1326          * @return              A pointer (non-constant) to the raw array of the calling buffer
1327          */
1328         byte* GetPointer(void);
1329
1330         /**
1331          * Compares the input Object with the calling %ByteBuffer instance.
1332          *
1333          * @since 2.0
1334          *
1335          * @return              @c true if the input Object equals the calling %ByteBuffer instance, @n
1336          *                              else @c false
1337          * @param[in]   obj                     The Object instance to compare with the calling object
1338          * @remarks         This method returns @c true only if the specified object is also an instance of
1339          *                              the %ByteBuffer class, the two buffers have the same number of remaining elements, and the
1340          *                              sequences of the remaining elements are equal (considered independent of their starting positions).
1341          * @see                 Tizen::Base::BufferBase::GetHashCode()
1342          */
1343         virtual bool Equals(const Tizen::Base::Object& obj) const;
1344
1345         /**
1346          *      Gets the hash value of the current instance.
1347          *
1348          *      @since 2.0
1349          *
1350          *      @return                 The hash value of the current instance
1351          *      @remarks                The hash code of a buffer depends only upon its remaining elements.
1352          */
1353         virtual int GetHashCode(void) const;
1354
1355 private:
1356         /**
1357          * This copy constructor is intentionally declared as private to prohibit copying of objects by users.
1358          */
1359         ByteBuffer(const ByteBuffer& buffer)
1360                 : __pByteBufferImpl(null)
1361         {
1362                 Construct(buffer);
1363         }
1364
1365         /**
1366          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1367          */
1368         ByteBuffer& operator =(const ByteBuffer& buffer);
1369
1370         /**
1371          * Returns the size of byte(1).
1372          *
1373          * @return              The size of byte(1)
1374          */
1375         virtual int GetTypeSize(void) const;
1376
1377
1378         friend class _ByteBufferImpl;
1379         class _ByteBufferImpl* __pByteBufferImpl;
1380
1381 }; // ByteBuffer
1382
1383 }} // Tizen::Base
1384
1385 #endif // _FBASE_BYTE_BUFFER_H_