2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FBaseByteBuffer.h
19 * @brief This is the header file for the %ByteBuffer class.
21 * This header file contains the declarations of the %ByteBuffer class.
23 #ifndef _FBASE_BYTE_BUFFER_H_
24 #define _FBASE_BYTE_BUFFER_H_
26 #include <FBaseBufferBase.h>
27 #include <FBaseBuffer.h>
30 namespace Tizen { namespace Base
35 * @brief This class provides a contiguous sequence of the @c byte (@c unsigned @c char) built-in type.
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.
44 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/buffer.htm">Buffer</a>.
46 * @see Tizen::Base::BufferBase
48 * The following example demonstrates how to use the %ByteBuffer class.
53 * using namespace Tizen::Base;
56 * MyClass::ByteBufferSample(void)
58 * // Defines the maximum buffer size : capacity
59 * const int BUFFER_SIZE_MAX = 1024;
61 * // Initializes a buf using the Construct method to the capacity
63 * buf.Construct(BUFFER_SIZE_MAX);
65 * // Copies five values into the buf
66 * for (int i = 0; i < 5; i++)
70 * // Writes byte b to the current position of the buf
71 * buf.SetByte(b); // The position is incremented by one
73 * // The position is moved to 5
77 * // Now, position = 0 and limit = 5
79 * // Reads bytes from the buf using "relative access method"
80 * while (buf.HasRemaining())
84 * // Reads byte b from the current position of the buf
85 * buf.GetByte(b); // The position is incremented by one
91 * // The buf's position = 0 and limit = capacity
93 * // Writes int values to the buf
94 * for (int i = 0; i < 5; i++)
96 * // Writes int value at the current position
97 * buf.SetInt(i); // The position is incremented by sizeof(int)
102 * // Now, position = 0 and limit = sizeof(int) * 5
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();
109 * // Tests whether the change in view buffer(IntBuffer) is visible in original buffer(ByteBuffer)
110 * pIntBuf->Set(4, 9);
112 * // Reads int values from the buf using "absolute access method"
113 * for (int i = 0; i < 5; i++)
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
128 class _OSP_EXPORT_ ByteBuffer
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.
139 * @remarks After creating an instance of %ByteBuffer, one of the Construct() methods must be called explicitly to initialize this instance.
144 * This destructor overrides Tizen::Base::Object::~Object().
148 virtual ~ByteBuffer(void);
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.
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.
163 result Construct(const ByteBuffer& buffer);
166 * Initializes this instance of %ByteBuffer with the specified @c capacity.
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.
178 result Construct(int capacity);
181 * Initializes this instance of %ByteBuffer with the specified @c buffer which is shared with this instance.
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.
199 result Construct(const byte* pBuffer, int index, int length, int capacity);
202 * Gets a reference to the @c byte value at the specified @c index.
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.
210 byte& operator [](int index);
213 * Gets the @c byte value at the specified @c index of the constant object.
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.
221 byte operator [](int index) const;
224 * Compares two %ByteBuffer instances.
228 * @return @c true if the input buffer is equal to the calling %ByteBuffer instance, @n
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).
236 bool operator ==(const ByteBuffer& buffer) const;
239 * Checks whether the current instance and the specfied %ByteBuffer instance are not equal.
243 * @return @c true if the current instance and the specified %ByteBuffer instance are not equal, @n
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).
251 bool operator !=(const ByteBuffer& buffer) const;
254 * Creates a new @c double buffer view for the content of the byte buffer.
258 * @return DoubleBuffer A pointer to the current position of the calling object
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.
265 DoubleBuffer* AsDoubleBufferN(void) const;
268 * Creates a new @c float buffer view for the content of the byte buffer.
272 * @return FloatBuffer A pointer to the current position of the calling buffer
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.
279 FloatBuffer* AsFloatBufferN(void) const;
282 * Creates a new @c int buffer view for the content of the byte buffer.
286 * @return IntBuffer A pointer to the current position of the calling buffer
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.
293 IntBuffer* AsIntBufferN(void) const;
296 * Creates a new @c long buffer view for the content of the byte buffer.
300 * @return LongBuffer A pointer to the current position of the calling buffer
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.
307 LongBuffer* AsLongBufferN(void) const;
310 * Creates a new @c long @c long buffer view for the content of the byte buffer.
314 * @return LongLongBuffer A pointer to the current position of the calling buffer
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.
321 LongLongBuffer* AsLongLongBufferN(void) const;
325 * Creates a new @c mchar buffer view of the underlying content of the byte buffer.
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.
332 * @return McharBuffer A pointer to the current position of the calling buffer
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.
340 McharBuffer* AsMcharBufferN(void) const;
343 * Creates a new @c wchar buffer view of the underlying content of the byte buffer.
347 * @return WcharBuffer A pointer to the current position of the calling buffer
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.
354 WcharBuffer* AsWcharBufferN(void) const;
357 * Creates a new @c short buffer view for the content of the byte buffer.
361 * @return ShortBuffer A pointer to the current position of the calling buffer
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.
368 ShortBuffer* AsShortBufferN(void) const;
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.
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.
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.
398 * The following example demonstrates how to use the %CopyFrom() method.
402 * // Creates instances of ByteBuffer to act as source and destination buffers
404 * ByteBuffer destBuf;
406 * // Declares an array of byte values
407 * byte pArray[] = {'A','B','C','D','E','F','G','H','I','J'};
409 * // Initializes the source array with a capacity of ten elements.
410 * srcBuf.Construct(10);
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);
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
421 * destBuf.Construct(20);
423 * // Copies from the srcBuf to the destBuf
424 * // Now, srcBuf's position = 10, the destBuf's position = 10
425 * destBuf.CopyFrom(srcBuf);
429 * The following example has exactly the same effect as the above %CopyFrom() method.
433 * int copyNum = srcBuf.GetRemaining();
434 * for (int i = 0; i < copyNum; i++)
438 * // Reads from source buffer
439 * srcBuf.GetByte(b); // The srcBuf position is incremented by 1
441 * // Writes to destination buffer
442 * destBuf.SetByte(b); // The destBuf position is incremented by 1
447 result CopyFrom(ByteBuffer& buffer);
450 * Gets the specified number of bytes from the current instance of %ByteBuffer.
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.
473 result GetArray(byte* pArray, int index, int length);
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.
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.
489 result GetByte(byte& value);
492 * Gets the @c byte value at the given index. @n
493 * It provides a way to perform absolute indexing and reading.
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.
507 result GetByte(int index, byte& value) const;
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.
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.
526 result GetDouble(double& value);
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.
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.
546 result GetDouble(int index, double& value) const;
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.
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.
565 result GetFloat(float& value);
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.
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.
585 result GetFloat(int index, float& value) const;
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.
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.
604 result GetInt(int& value);
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.
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.
624 result GetInt(int index, int& value) const;
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.
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.
643 result GetLong(long& value);
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.
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.
663 result GetLong(int index, long& value) const;
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.
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.
682 result GetLongLong(long long& value);
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.
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.
702 result GetLongLong(int index, long long& value) const;
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.
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.
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.
726 result GetMchar(wchar_t& value);
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.
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.
745 result GetWchar(wchar_t& value);
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.
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.
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.
770 result GetMchar(int index, wchar_t& value) const;
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.
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.
790 result GetWchar(int index, wchar_t& value) const;
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.
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.
809 result GetShort(short& value);
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.
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.
829 result GetShort(int index, short& value) const;
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.
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.
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.
853 * The following example demonstrates how to use the %ReadFrom() method.
857 * // Creates instances of %ByteBuffer to act as source and destination buffers
859 * ByteBuffer destBuf;
861 * // Declares an array of byte values
862 * byte pArray[] = {'A','B','C','D','E','F','G','H','I','J'};
864 * // Initializes the source array with capacity of ten elements.
865 * srcBuf.Construct(10);
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);
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
875 * // Initializes the destination buffer with capacity of ten elements
876 * destBuf.Construct(10);
878 * // Sets the limit of destBuf to 5
879 * destBuf.SetLimit(5);
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);
890 * The following example has exactly the same effect as the above %ReadFrom() method.
894 * int copyNum = (destBuf.GetRemaining() < srcBuf.GetRemaing())? destBuf.GetRemaining() : srcBuf.GetRemaining();
895 * for (int i = 0; i < copyNum; i++)
899 * // Reads from the source buffer
900 * srcBuf.GetByte(b); // The srcBuf position is incremented by 1
902 * // Writes to the destination buffer
903 * destBuf.SetByte(b); // The destBuf position is incremented by 1
909 result ReadFrom(ByteBuffer& buffer);
912 * Sets the @c byte values in the specified array to the current instance of %ByteBuffer.
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.
936 result SetArray(const byte* pArray, int index, int length);
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.
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.
953 result SetByte(byte value);
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.
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.
971 result SetByte(int index, byte value);
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.
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.
990 result SetDouble(double value);
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.
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.
1009 result SetFloat(float value);
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.
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.
1028 result SetInt(int value);
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.
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.
1047 result SetLong(long value);
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.
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()
1066 result SetLongLong(long long value);
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.
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.
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.
1090 result SetMchar(wchar_t value);
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.
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.
1109 result SetWchar(wchar_t value);
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.
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.
1128 result SetShort(short value);
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.
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.
1148 result SetDouble(int index, double value);
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.
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.
1168 result SetFloat(int index, float value);
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.
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.
1188 result SetInt(int index, int value);
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.
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.
1208 result SetLong(int index, long value);
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.
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()
1228 result SetLongLong(int index, long long value);
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.
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.
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.
1253 result SetMchar(int index, wchar_t value);
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.
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.
1273 result SetWchar(int index, wchar_t value);
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.
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.
1293 result SetShort(int index, short value);
1296 * Creates a new %ByteBuffer whose content is a shared portion of
1297 * the content of the calling %ByteBuffer instance.
1301 * @return A %ByteBuffer pointer to the current position of the calling object
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.
1308 ByteBuffer* SliceN(void) const;
1311 * Gets a pointer to the raw array of the calling buffer. @n
1312 * If the capacity is zero, it returns @c null.
1316 * @return A pointer to the raw array of the calling buffer
1318 const byte* GetPointer(void) const;
1321 * Gets a pointer to the raw array of the calling buffer. @n
1322 * If the capacity is zero, it returns @c null.
1326 * @return A pointer (non-constant) to the raw array of the calling buffer
1328 byte* GetPointer(void);
1331 * Compares the input Object with the calling %ByteBuffer instance.
1335 * @return @c true if the input Object equals the calling %ByteBuffer instance, @n
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()
1343 virtual bool Equals(const Tizen::Base::Object& obj) const;
1346 * Gets the hash value of the current instance.
1350 * @return The hash value of the current instance
1351 * @remarks The hash code of a buffer depends only upon its remaining elements.
1353 virtual int GetHashCode(void) const;
1357 * This copy constructor is intentionally declared as private to prohibit copying of objects by users.
1359 ByteBuffer(const ByteBuffer& buffer)
1360 : __pByteBufferImpl(null)
1366 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1368 ByteBuffer& operator =(const ByteBuffer& buffer);
1371 * Returns the size of byte(1).
1373 * @return The size of byte(1)
1375 virtual int GetTypeSize(void) const;
1378 friend class _ByteBufferImpl;
1379 class _ByteBufferImpl* __pByteBufferImpl;
1385 #endif // _FBASE_BYTE_BUFFER_H_