ByteBuffer Class

Definition

Namespace:

Java.Nio

Assembly:

Mono.Android.dll

A byte buffer.

[Android.Runtime.Register("java/nio/ByteBuffer", DoNotGenerateAcw=true)]
public abstract class ByteBuffer : Java.Nio.Buffer, IDisposable, Java.Interop.IJavaPeerable, Java.Lang.IComparable

[<Android.Runtime.Register("java/nio/ByteBuffer", DoNotGenerateAcw=true)>]
type ByteBuffer = class
    inherit Buffer
    interface IComparable
    interface IJavaObject
    interface IDisposable
    interface IJavaPeerable

Inheritance

Object

Object

Buffer

ByteBuffer

Derived

Java.Nio.MappedByteBuffer

Attributes

RegisterAttribute

Implements

IJavaObject IJavaPeerable IComparable IDisposable

Remarks

A byte buffer.

This class defines six categories of operations upon byte buffers:

<ul>

<li>

Absolute and relative #get() <i>get</i> and #put(byte) <i>put</i> methods that read and write single bytes;

</li>

<li>

Relative #get(byte[]) <i>bulk get</i> methods that transfer contiguous sequences of bytes from this buffer into an array;

</li>

<li>

Relative #put(byte[]) <i>bulk put</i> methods that transfer contiguous sequences of bytes from a byte array or some other byte buffer into this buffer;

</li>

<li>

Absolute and relative #getChar() <i>get</i> and #putChar(char) <i>put</i> methods that read and write values of other primitive types, translating them to and from sequences of bytes in a particular byte order;

</li>

<li>

Methods for creating view buffers, which allow a byte buffer to be viewed as a buffer containing values of some other primitive type; and

</li>

<li>

Methods for #compact compacting, #duplicate duplicating, and #slice slicing a byte buffer.

</li>

</ul>

Byte buffers can be created either by #allocate <i>allocation</i>, which allocates space for the buffer's

content, or by #wrap(byte[]) <i>wrapping</i> an existing byte array into a buffer.

"direct"><h2> Direct vs. non-direct buffers </h2>

A byte buffer is either direct or non-direct. Given a direct byte buffer, the Java virtual machine will make a best effort to perform native I/O operations directly upon it. That is, it will attempt to avoid copying the buffer's content to (or from) an intermediate buffer before (or after) each invocation of one of the underlying operating system's native I/O operations.

A direct byte buffer may be created by invoking the #allocateDirect(int) allocateDirect factory method of this class. The buffers returned by this method typically have somewhat higher allocation and deallocation costs than non-direct buffers. The contents of direct buffers may reside outside of the normal garbage-collected heap, and so their impact upon the memory footprint of an application might not be obvious. It is therefore recommended that direct buffers be allocated primarily for large, long-lived buffers that are subject to the underlying system's native I/O operations. In general it is best to allocate direct buffers only when they yield a measureable gain in program performance.

A direct byte buffer may also be created by java.nio.channels.FileChannel#map mapping a region of a file directly into memory. An implementation of the Java platform may optionally support the creation of direct byte buffers from native code via JNI. If an instance of one of these kinds of buffers refers to an inaccessible region of memory then an attempt to access that region will not change the buffer's content and will cause an unspecified exception to be thrown either at the time of the access or at some later time.

Whether a byte buffer is direct or non-direct may be determined by invoking its #isDirect isDirect method. This method is provided so that explicit buffer management can be done in performance-critical code.

"bin"><h2> Access to binary data </h2>

This class defines methods for reading and writing values of all other primitive types, except boolean. Primitive values are translated to (or from) sequences of bytes according to the buffer's current byte order, which may be retrieved and modified via the #order order methods. Specific byte orders are represented by instances of the ByteOrder class. The initial order of a byte buffer is always ByteOrder#BIG_ENDIAN BIG_ENDIAN.

For access to heterogeneous binary data, that is, sequences of values of different types, this class defines a family of absolute and relative get and put methods for each type. For 32-bit floating-point values, for example, this class defines:

<blockquote>

float  {@link #getFloat()}
            float  {@link #getFloat(int) getFloat(int index)}
             void  {@link #putFloat(float) putFloat(float f)}
             void  {@link #putFloat(int,float) putFloat(int index, float f)}

</blockquote>

Corresponding methods are defined for the types char, short, int, long, and double. The index parameters of the absolute get and put methods are in terms of bytes rather than of the type being read or written.

"views">

For access to homogeneous binary data, that is, sequences of values of the same type, this class defines methods that can create views of a given byte buffer. A view buffer is simply another buffer whose content is backed by the byte buffer. Changes to the byte buffer's content will be visible in the view buffer, and vice versa; the two buffers' position, limit, and mark values are independent. The #asFloatBuffer() asFloatBuffer method, for example, creates an instance of the FloatBuffer class that is backed by the byte buffer upon which the method is invoked. Corresponding view-creation methods are defined for the types char, short, int, long, and double.

View buffers have three important advantages over the families of type-specific get and put methods described above:

<ul>

<li>

A view buffer is indexed not in terms of bytes but rather in terms of the type-specific size of its values;

</li>

<li>

A view buffer provides relative bulk get and put methods that can transfer contiguous sequences of values between a buffer and an array or some other buffer of the same type; and

</li>

<li>

A view buffer is potentially much more efficient because it will be direct if, and only if, its backing byte buffer is direct.

</li>

</ul>

The byte order of a view buffer is fixed to be that of its byte buffer at the time that the view is created.

<h2> Invocation chaining </h2>

Methods in this class that do not otherwise have a value to return are specified to return the buffer upon which they are invoked. This allows method invocations to be chained.

The sequence of statements

<blockquote>

bb.putInt(0xCAFEBABE);
            bb.putShort(3);
            bb.putShort(45);

</blockquote>

can, for example, be replaced by the single statement

<blockquote>

bb.putInt(0xCAFEBABE).putShort(3).putShort(45);

</blockquote>

Added in 1.4.

Java documentation for java.nio.ByteBuffer.

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Constructors

ByteBuffer(IntPtr, JniHandleOwnership)

A constructor used when creating managed representations of JNI objects; called by the runtime.

Properties

Char	Returns the char at the current position and increases the position by 2.
Class	Returns the runtime class of this Object. (Inherited from Object)
Double	Returns the double at the current position and increases the position by 8.
Float	Returns the float at the current position and increases the position by 4.
Handle	The handle to the underlying Android instance. (Inherited from Object)
HasArray	Tells whether or not this buffer is backed by an accessible byte array.
HasRemaining	Tells whether there are any elements between the current position and the limit. (Inherited from Buffer)
Int	Returns the int at the current position and increases the position by 4.
IsDirect	Returns true if this is a direct buffer. (Inherited from Buffer)
IsReadOnly	Indicates whether this buffer is read-only. (Inherited from Buffer)
JniIdentityHashCode	(Inherited from Object)
JniPeerMembers
Long	Returns the long at the current position and increases the position by 8.
PeerReference	(Inherited from Object)
Short	Returns the short at the current position and increases the position by 2.
ThresholdClass	This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
ThresholdType	This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.

Methods

AlignedSlice(Int32)	Creates a new byte buffer whose content is a shared and aligned subsequence of this buffer's content.
AlignmentOffset(Int32, Int32)	Returns the memory address, pointing to the byte at the given index, modulus the given unit size.
Allocate(Int32)	Allocates a new byte buffer.
AllocateDirect(Int32)	Allocates a new direct byte buffer.
ArrayOffset()	Returns the offset within this buffer's backing array of the first element of the buffer  (optional operation).
AsCharBuffer()	Creates a view of this byte buffer as a char buffer.
AsDoubleBuffer()	Creates a view of this byte buffer as a double buffer.
AsFloatBuffer()	Creates a view of this byte buffer as a float buffer.
AsIntBuffer()	Creates a view of this byte buffer as an int buffer.
AsLongBuffer()	Creates a view of this byte buffer as a long buffer.
AsReadOnlyBuffer()	Creates a new, read-only byte buffer that shares this buffer's content.
AsShortBuffer()	Creates a view of this byte buffer as a short buffer.
Capacity()	Returns this buffer's capacity. (Inherited from Buffer)
Clear()	Clears this buffer. (Inherited from Buffer)
Clone()	Creates and returns a copy of this object. (Inherited from Object)
Compact()	Compacts this buffer  (optional operation).
CompareTo(ByteBuffer)	Compares this buffer to another.
Dispose()	(Inherited from Object)
Dispose(Boolean)	(Inherited from Object)
Duplicate()	Creates a new byte buffer that shares this buffer's content.
Equals(Object)	Indicates whether some other object is "equal to" this one. (Inherited from Object)
Flip()	Flips this buffer. (Inherited from Buffer)
Get()	Relative get method.
Get(Byte[], Int32, Int32)	Relative bulk get method.
Get(Byte[])	Relative bulk get method.
Get(Int32)	Absolute get method.
GetChar(Int32)	Absolute get method for reading a char value.
GetDirectBufferAddress()	(Inherited from Buffer)
GetDouble(Int32)	Absolute get method for reading a double value.
GetFloat(Int32)	Absolute get method for reading a float value.
GetHashCode()	Returns a hash code value for the object. (Inherited from Object)
GetInt(Int32)	Absolute get method for reading an int value.
GetLong(Int32)	Absolute get method for reading a long value.
GetShort(Int32)	Absolute get method for reading a short value.
JavaFinalize()	Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. (Inherited from Object)
Limit()	Returns this buffer's limit. (Inherited from Buffer)
Limit(Int32)	Sets this buffer's limit. (Inherited from Buffer)
Mark()	Sets this buffer's mark at its position. (Inherited from Buffer)
Mismatch(ByteBuffer)	Finds and returns the relative index of the first mismatch between this buffer and a given buffer.
Notify()	Wakes up a single thread that is waiting on this object's monitor. (Inherited from Object)
NotifyAll()	Wakes up all threads that are waiting on this object's monitor. (Inherited from Object)
Order()	Retrieves this buffer's byte order.
Order(ByteOrder)	Modifies this buffer's byte order.
Position()	Returns this buffer's position. (Inherited from Buffer)
Position(Int32)	Sets this buffer's position. (Inherited from Buffer)
Put(Byte[], Int32, Int32)	Relative bulk put method  (optional operation).
Put(Byte[])	Relative bulk put method  (optional operation).
Put(ByteBuffer)	Relative bulk put method  (optional operation).
Put(Int32, SByte)	Absolute put method  (optional operation).
Put(SByte)	Relative put method  (optional operation).
PutChar(Char)	Relative put method for writing a char value  (optional operation).
PutChar(Int32, Char)	Absolute put method for writing a char value  (optional operation).
PutDouble(Double)	Relative put method for writing a double value  (optional operation).
PutDouble(Int32, Double)	Absolute put method for writing a double value  (optional operation).
PutFloat(Int32, Single)	Absolute put method for writing a float value  (optional operation).
PutFloat(Single)	Relative put method for writing a float value  (optional operation).
PutInt(Int32, Int32)	Absolute put method for writing an int value  (optional operation).
PutInt(Int32)	Relative put method for writing an int value  (optional operation).
PutLong(Int32, Int64)	Absolute put method for writing a long value  (optional operation).
PutLong(Int64)	Relative put method for writing a long value  (optional operation).
PutShort(Int16)	Relative put method for writing a short value  (optional operation).
PutShort(Int32, Int16)	Absolute put method for writing a short value  (optional operation).
Remaining()	Returns the number of elements between the current position and the limit. (Inherited from Buffer)
Reset()	Resets this buffer's position to the previously-marked position. (Inherited from Buffer)
Rewind()	Rewinds this buffer. (Inherited from Buffer)
SetHandle(IntPtr, JniHandleOwnership)	Sets the Handle property. (Inherited from Object)
Slice()	Creates a new byte buffer whose content is a shared subsequence of this buffer's content.
Slice(Int32, Int32)	Creates a new byte buffer whose content is a shared subsequence of this buffer's content.
ToArray<T>()	(Inherited from Object)
ToString()	Returns a string representation of the object. (Inherited from Object)
UnregisterFromRuntime()	(Inherited from Object)
Wait()	Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>. (Inherited from Object)
Wait(Int64, Int32)	Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object)
Wait(Int64)	Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object)
Wrap(Byte[], Int32, Int32)	Wraps a byte array into a buffer.
Wrap(Byte[])	Wraps a byte array into a buffer.

Explicit Interface Implementations

IComparable.CompareTo(Object)
IJavaPeerable.Disposed()	(Inherited from Object)
IJavaPeerable.DisposeUnlessReferenced()	(Inherited from Object)
IJavaPeerable.Finalized()	(Inherited from Object)
IJavaPeerable.JniManagedPeerState	(Inherited from Object)
IJavaPeerable.SetJniIdentityHashCode(Int32)	(Inherited from Object)
IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates)	(Inherited from Object)
IJavaPeerable.SetPeerReference(JniObjectReference)	(Inherited from Object)

Extension Methods

JavaCast<TResult>(IJavaObject)	Performs an Android runtime-checked type conversion.
JavaCast<TResult>(IJavaObject)
GetJniTypeName(IJavaPeerable)