Table of Contents

Interface IFileChannels

Namespace
RDCore.SDK.Runtime.Abstract.Execution
Assembly
RDCore.SDK.dll

The file numbers a session has open (MS-VBAL §5.4.5): the shim every file statement goes through.

public interface IFileChannels

Remarks

🎯 A single seam on purpose, and not only because twelve statements share it. File I/O is the most consequential thing a VBA program does to the machine it runs on, so it is the thing an administrator most needs to be able to see, restrict, or redirect, and the thing a test most needs to be able to fake. Every one of those is a matter of which implementation the session was composed with rather than of anything the statements know.

The file system is already abstracted platform-wide (System.IO.Abstractions), so what this adds is the part VBA has and a file system does not: numbered channels, the modes they were opened under, and the rules about which statement may use which.

⚖️RDCore provides an implementation of this interface licensed under GPLv3.

Properties

Open

The channels currently open, in no particular order.

IEnumerable<IFileChannel> Open { get; }

Property Value

IEnumerable<IFileChannel>

Methods

Close(int)

Disassociates fileNumber, closing the file (MS-VBAL §5.4.5.2).

bool Close(int fileNumber)

Parameters

fileNumber int

The file number to close.

Returns

bool

false when it was not open.

CloseAll()

Closes every open channel: what a Close with no file number, and a Reset, both do (MS-VBAL §5.4.5.2).

int CloseAll()

Returns

int

How many were closed.

TryChangeDirectory(string)

Changes the current directory (ChDir, MS-VBAL §6.1.2.5.2.1).

RDCoreDiagnosticCode? TryChangeDirectory(string path)

Parameters

path string

The directory that is to be the current one.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 76 for a directory that does not exist.

TryChangeDrive(string)

Changes the current drive (ChDrive, MS-VBAL §6.1.2.5.2.2): an empty one changes nothing.

RDCoreDiagnosticCode? TryChangeDrive(string drive)

Parameters

drive string

The drive, of which only the first letter is read.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 68 for a letter that is no drive, 5 for a drive that is no letter.

TryCopy(string, string)

Copies a file (FileCopy, MS-VBAL §6.1.2.5.2.3), replacing the destination.

RDCoreDiagnosticCode? TryCopy(string source, string destination)

Parameters

source string

The path of the file that is copied.

destination string

The path of the copy.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 52, 53, 55, 75, 76 (IStdFileSystemModule.FileCopy).

TryCreateDirectory(string)

Creates a directory (MkDir, MS-VBAL §6.1.2.5.2.5).

RDCoreDiagnosticCode? TryCreateDirectory(string path)

Parameters

path string

The path of the directory to create.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 75 when something of the name exists, 76 when the directory it is in does not.

TryDelete(string)

Deletes the files that match pattern (Kill, MS-VBAL §6.1.2.5.2.4): not a directory, nor a hidden or a system file.

RDCoreDiagnosticCode? TryDelete(string pattern)

Parameters

pattern string

A file name, with or without wildcards, that can include a directory and a drive.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 53, 55, 75 (IStdFileSystemModule.Kill).

TryFindFirst(string, VBFileAttribute, out string)

The first name that matches pattern (Dir, MS-VBAL §6.1.2.5.1.2), and what the next TryFindNext(out string) goes on from.

RDCoreDiagnosticCode? TryFindFirst(string pattern, VBFileAttribute attributes, out string name)

Parameters

pattern string

A file name with wildcards, that can include a directory and a drive.

attributes VBFileAttribute

The attributes, besides the normal ones, of what matches.

name string

The name, with no directory part; empty when nothing matches.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null.

TryFindNext(out string)

The next name that matches the pattern TryFindFirst(string, VBFileAttribute, out string) was last given.

RDCoreDiagnosticCode? TryFindNext(out string name)

Parameters

name string

The name; empty when there is no other.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 5 when there is no pattern to go on with.

TryGet(int, out IFileChannel?)

The channel fileNumber is open on.

bool TryGet(int fileNumber, out IFileChannel? channel)

Parameters

fileNumber int

The file number source referred to.

channel IFileChannel

The channel it is open on.

Returns

bool

false when that file number is not currently open.

TryGetAttributes(string, out VBFileAttribute)

The attributes of a file or a directory (GetAttr, MS-VBAL §6.1.2.8.1.8).

RDCoreDiagnosticCode? TryGetAttributes(string path, out VBFileAttribute attributes)

Parameters

path string

The path of the file or the directory.

attributes VBFileAttribute

Its attributes.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 53 for what does not exist, 52 for a pattern.

TryGetCurrentDirectory(string?, out string)

The current directory of a drive (CurDir, MS-VBAL §6.1.2.5.1.1).

RDCoreDiagnosticCode? TryGetCurrentDirectory(string? drive, out string path)

Parameters

drive string

The drive, of which only the first letter is read; null or empty for the current drive.

path string

The directory.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 68 for a letter that is no drive, 5 for a drive that is no letter.

TryGetLastWriteTime(string, out DateTime)

When a file or a directory was last modified (FileDateTime, MS-VBAL §6.1.2.5.1.5), local time.

RDCoreDiagnosticCode? TryGetLastWriteTime(string path, out DateTime modified)

Parameters

path string

The path of the file or the directory.

modified DateTime

When it was last modified, local time.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 53 for what does not exist, 52 for a pattern.

TryGetLength(string, out long)

The length of a file on the file system, in bytes (FileLen, MS-VBAL §6.1.2.5.1.6): 0 for a directory.

RDCoreDiagnosticCode? TryGetLength(string path, out long length)

Parameters

path string

The path of the file or the directory.

length long

Its length, in bytes.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 53 for what does not exist, 52 for a pattern.

TryOpen(int, string, VBFileMode, VBFileAccessMode, VBFileLockMode, int)

Associates fileNumber with path (MS-VBAL §5.4.5.1).

RDCoreDiagnosticCode? TryOpen(int fileNumber, string path, VBFileMode mode, VBFileAccessMode access, VBFileLockMode @lock, int recordLength)

Parameters

fileNumber int

The file number to associate. Must not already be open.

path string

The complete path specification.

mode VBFileMode

The mode, defaulted by the caller from the statement's own clauses.

access VBFileAccessMode

The access, defaulted by the caller from mode.

lock VBFileLockMode

The lock, Shared when the statement declared none.

recordLength int

The Len = record length, or 0.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null when the channel is open. The specification names which: 55 when the file number is already open, 53 when an Input names no existing file, 55 when an Append/Output names a file another channel already has open, 70 when the requested lock cannot be had, and 75 when the file cannot be created.

Remarks

Creates the external file when it does not exist, unless the mode is Input, which the specification says is an error instead.

TryReadAll(string, out byte[])

Reads every byte of a file, opening no channel and taking no file number: what LoadPicture reads a picture from.

RDCoreDiagnosticCode? TryReadAll(string path, out byte[] bytes)

Parameters

path string

The path of the file.

bytes byte[]

Its bytes; empty when an error stopped it.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 52 for a pattern, 53 for a file that does not exist or no path, 76 for a folder that does not, 75 for a directory or a file the file system cannot read, 70 for one the program may not read.

TryRemoveDirectory(string)

Removes an empty directory (RmDir, MS-VBAL §6.1.2.5.2.6).

RDCoreDiagnosticCode? TryRemoveDirectory(string path)

Parameters

path string

The path of the directory to remove.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 75 for one that is not empty, 76 for one that does not exist.

TryRename(string, string)

Renames a file or a directory, moving it when the new path is somewhere else (Name … As …; see RD-VBAL §5.4.5.13).

RDCoreDiagnosticCode? TryRename(string oldPath, string newPath)

Parameters

oldPath string

The path of the existing file or directory.

newPath string

The path it is to have, which must not exist.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null when it was renamed: 52 when either path has a wildcard in it, 53 when oldPath names nothing, 55 when it is open, 58 when newPath exists, 74 when a directory would change drive, 76 when a directory the paths name does not exist, 70 when access is refused, and 75 when anything else about the path or the device stops it.

Remarks

The channels are the ones that know which files are open, which is why this is theirs and not the file system's: a file that has a file number association is not renamed. Neither path is a pattern.

TrySetAttributes(string, VBFileAttribute)

Sets the attributes of a file (SetAttr, MS-VBAL §6.1.2.5.2.7).

RDCoreDiagnosticCode? TrySetAttributes(string path, VBFileAttribute attributes)

Parameters

path string

The path of the file.

attributes VBFileAttribute

The attributes it is to have.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 5, 52, 53, 55 (IStdFileSystemModule.SetAttr).

TryWriteAll(string, byte[])

Writes a file whole, replacing what it held, opening no channel and taking no file number: what SavePicture writes a picture to.

RDCoreDiagnosticCode? TryWriteAll(string path, byte[] bytes)

Parameters

path string

The path of the file.

bytes byte[]

What the file is to hold.

Returns

RDCoreDiagnosticCode?

The error that stopped it, or null: 52 for a pattern, 76 for a folder that does not exist, 75 for no path, a directory, or a file the file system cannot write (one a channel locked included), 70 for one the program may not write.

Remarks

A file a channel has open is written too, as MS-VBA writes it, unless the channel locked it against writing.