FileStream CLASS

A stream backed by a file as defined on the underlying file system.

Parent Class

• System.IO.StreamBase

Parent Interfaces

• System.IO.AsyncStream

All Members

---

Type	Name	Signature
constructor	FileStream	public FileStream(string, System.IO.FileMode)
method	canRead	public bool canRead()
method	canReadAsync	public bool canReadAsync()
method	canWrite	public bool canWrite()
method	canWriteAsync	public bool canWriteAsync()
method	readAsync	public Promise readAsync(byte[], int)
method	readToEndAsync	public Promise readToEndAsync(byte[], Function)
method	writeAsync	public Promise writeAsync(byte[], int, int)

Constructors

---

public FileStream(string path, FileMode mode)

Create a file stream with specified path and mode.

Parameters

• path Can be a relative path to the working directory.
• mode

Methods

---

public bool canRead()

Returns

• True if the stream was open with OPEN.

public bool canReadAsync()

(INHERITED DOC)

Whether this stream supports asynchronous reading. This method governs readAsync, readAllAsync.

Returns

• True if the stream was open with OPEN.

public bool canWrite()

Returns

• True if the stream was open with APPEND or CREATE.

public bool canWriteAsync()

(INHERITED DOC)

Whether this stream supports asynchronous writing. This method governs writeAsync.

Returns

• True if the stream was open with OPEN or APPEND.

public Promise readAsync(byte[] buffer, int offset)

(INHERITED DOC)

Read asynchronously from the stream to the buffer, and invokes callback upon completion.

This method tries to read as many bytes as possible from the stream into the given buffer, starting from the offset and not exceeding the buffer's capacity. This will move forward the stream pointer by the number of bytes actually read. If the stream hits the end, or the buffer runs short of room before reading the specified count, only those bytes will be read, making the returned value less than the count argument.

Upon successful completion, the callback function will be invoked. The callback function has signature Function(int, PromiseHandle), with first parameter indicating the number of bytes successfully read. If the reading failed, this callback won't be called, and the users must process that with a continuation on the promise itself.

This method moves forward the stream pointer by the count equal to returned value. If canRead() returns false, this method will throw IOException.

Required Policies

• System.IO/read

Parameters

• buffer The byte buffer to hold the data which is read off of the stream.
• offset The offset on buffer to start filling the data in.

Returns

• A promise that can be continued on. An on-success callback will set the result to be the number of bytes successfully read. -1 if reaching the end, while buffer will contain no valid bytes; an on-error callback will take as argument the exception faulting the IO operation.

public Promise readToEndAsync(byte[] buffer, Function callback)

(INHERITED DOC)

Read asynchronously from the stream to the buffer until the end of stream is hit, and invoke callback evertime a chunk of data is read, which usually fills the buffer, except for the last time.

This method tries to read as many bytes as possible from the stream into the given buffer. Everytime it reads a chunk of data, it will invoke the callback function, which has signature Function(int, PromiseHandle), with first parameter indicating the number of bytes successfully read. If the reading failed, this callback won't be called, and the users must process that with a continuation on the promise itself.

This method moves forward the stream pointer to the end of stream. If canRead() return false, this method will throw IOException.

Required Policies

• System.IO/read

Parameters

• buffer The byte buffer to hold the data which is read off of the stream.
• callback The function to be called upon successful reading. The type of this function is Function(int, PromiseHandle), first parameter indicating the number of bytes successfully read. -1 if reaching the end, while buffer will contain no valid bytes. Throughout the promise's life cycle this callback will be invoked multiple times.

Returns

• A promise that can be continued on. An on-success callback will take as argument the result returned from the callback; an on-error callback will take as argument the exception faulting the IO operation.

public Promise writeAsync(byte[] buffer, int offset, int length)

(INHERITED DOC)

Write asynchronously from the buffer to the stream.

This method tries to write all the bytes from the given buffer to the stream, starting from the offset and not exceeding either length or the buffer's capacity. This will move forward the stream pointer by the number of bytes actually written.

This method moves forward the stream pointer by the count equal to value used to settle the promise. If canWriteAsync() return false, this method will throw IOException.

Required Policies

• System.IO/write

Parameters

• buffer The byte buffer to hold the data which is to write to the stream.
• offset The offset on buffer to start reading data from.
• length The total count of bytes to read from the buffer, relative to the offset.

Returns

• A promise that can be continued on. An on-success callback will take as argument the total count of bytes that have been written; an on-error callback will take as argument the exception faulting the IO operation.