kmcifs-client/com.sorrowblue.kmcifs.client/SmbRandomAccessFile

SmbRandomAccessFile

class SmbRandomAccessFile(val share: SmbShare, val path: String, val mode: SmbRandomAccessMode = SmbRandomAccessMode.READ_ONLY, val bufferSize: Int = DEFAULT_BUFFER_SIZE) : AutoCloseable

Provides a java.io.RandomAccessFile-compatible random-access API over a remote SMB file.

Maintains an internal file pointer (position) and supports seeking to arbitrary offsets (seek), reading from the current position (read, readByte, readFully), writing at the current position (write), and querying or changing the file length (length / setLength).

For workloads with frequent small reads (such as readByte or container header parsing), pass a positive bufferSize to enable an in-memory read-ahead buffer (defaults to 0, disabling buffering). Any write or size change immediately invalidates the read buffer to preserve read-after-write consistency.

Like java.io.RandomAccessFile, a single SmbRandomAccessFile instance is designed for sequential use from one thread at a time. To read concurrently from multiple threads, open a separate SmbRandomAccessFile instance per thread (the underlying SmbShare and SmbClient are thread-safe and can be shared).

Constructors

SmbRandomAccessFile

constructor(share: SmbShare, path: String, mode: SmbRandomAccessMode = SmbRandomAccessMode.READ_ONLY, bufferSize: Int = DEFAULT_BUFFER_SIZE)

constructor(share: SmbShare, path: String, mode: String, bufferSize: Int = DEFAULT_BUFFER_SIZE)

Types

Companion

object Companion

Properties

bufferSize

val bufferSize: Int

callerJob

@Volatile

var callerJob: Job?

Optional Job of the active caller coroutine. When set and cancelled (isCancelled == true), synchronous operations (read, write, length, setLength, flush) immediately abort with CancellationException instead of continuing to issue SMB requests.

isOpen

val isOpen: Boolean

Whether the underlying SMB file handle is currently open.

length

val length: Long

Current length of the file in bytes.

metadata

val metadata: SmbFileMetadata

Metadata of the open SMB file.

mode

val mode: SmbRandomAccessMode

path

val path: String

position

val position: Long

Current file pointer offset in bytes from the beginning of the file.

val share: SmbShare

Functions

open override fun close()

closeSuspend

suspend fun closeSuspend()

Closes the remote SMB file handle on the server (SMB2 CLOSE) and releases internal buffers.

flush

fun flush()

Flushes server-side write buffers for this file to persistent storage (SMB2 FLUSH).

open

suspend fun open(): SmbRandomAccessFile

Opens the remote SMB file if it is not already open.

read

fun read(): Int

Reads a single byte from the current position and returns it as an integer in the range 0..255, or -1 if the end of the file has been reached.

fun read(b: ByteArray): Int

Reads up to b.size bytes from the current position into b and returns the number of bytes read, or -1 if no bytes could be read because the end of the file has been reached.

fun read(b: ByteArray, off: Int, len: Int): Int

Reads up to len bytes from the current position into b starting at offset off, returning the number of bytes read or -1 if the end of the file has been reached.

readBoolean

fun readBoolean(): Boolean

Reads a single byte from the current position and returns true if it is non-zero, or false if zero.

readByte

fun readByte(): Byte

Reads a signed 8-bit value (Byte) from the current position and advances the file pointer by 1. Throws SmbEndOfFileException if the end of the file has been reached.

readBytes

fun readBytes(length: Int): ByteArray

Reads up to length bytes from the current position and returns them as a new ByteArray.

readFully

fun readFully(b: ByteArray, off: Int = 0, len: Int = b.size - off)

Reads exactly len bytes from the current position into b starting at off. Throws SmbEndOfFileException if the end of the file is reached before len bytes are read.

readInt

fun readInt(): Int

Reads a signed 32-bit big-endian integer from the current position.

readLong

fun readLong(): Long

Reads a signed 64-bit big-endian integer from the current position.

readShort

fun readShort(): Short

Reads a signed 16-bit big-endian integer from the current position.

readUnsignedByte

fun readUnsignedByte(): Int

Reads an unsigned 8-bit value (0..255) from the current position and advances the file pointer by 1. Throws SmbEndOfFileException if the end of the file has been reached.

readUnsignedShort

fun readUnsignedShort(): Int

Reads an unsigned 16-bit big-endian integer from the current position.

seek

fun seek(pos: Long)

Sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs.

setLength

fun setLength(newLength: Long)

Truncates or extends the file to newLength bytes.

skipBytes

fun skipBytes(n: Int): Int

Attempts to skip over n bytes of input starting from the current position, returning the actual number of bytes skipped. Never skips past the end of the file.

write

fun write(b: ByteArray)

Writes all bytes from b at the current position and advances the file pointer.

fun write(b: Int)

Writes the low-order 8 bits of b at the current position and advances the file pointer by 1.

fun write(b: ByteArray, off: Int, len: Int): Int

Writes len bytes from b starting at offset off at the current position and advances the file pointer by the number of bytes written.

writeBoolean

fun writeBoolean(v: Boolean)

Writes a boolean value as a single byte (1 for true, 0 for false) at the current position.

writeByte

fun writeByte(v: Int)

Writes a single byte v at the current position and advances the file pointer by 1.

writeInt

fun writeInt(v: Int)

Writes a 32-bit big-endian integer at the current position.

writeLong

fun writeLong(v: Long)

Writes a 64-bit big-endian integer at the current position.

writeShort

fun writeShort(v: Int)

Writes a 16-bit big-endian integer at the current position.