Skip to content

Latest commit

 

History

History
177 lines (140 loc) · 8.36 KB

API.md

File metadata and controls

177 lines (140 loc) · 8.36 KB

API reference

All async methods return SmbTask<T>. Await with .result(). See Task model for subscribe, cancel, and hook patterns.

Connection

Method Returns result() type Notes
initialize(url, creds) SmbTask<void> void Configure server and credentials; no share
connect(url, creds) SmbTask<SmbConnectionInfo> SmbConnectionInfo Auth + mount share from URL
connectShare(share) SmbTask<SmbConnectionInfo> SmbConnectionInfo Switch share
disconnect() SmbTask<void> void Cancel work and close the session; client remains reusable
listShares() SmbTask<SmbShare[]> SmbShare[] Enumerate shares
isConnected() boolean — Sync
isInitialized() boolean — Sync

Connection URLs are smb://<host>[:<port>] for initialize, and smb://<host>[:<port>]/<share> for connect. Pass username and password in SmbCredentials; pass directory and file paths to filesystem methods.

interface SmbCredentials { username: string; password: string; }

interface SmbConnectionInfo {
  url: string; server: string; share: string; isConnected: boolean;
}

interface SmbShare { name: string; comment: string; }

File system

Method Returns result() type Notes
listDirectory(path, options?) SmbListTask SmbFileInfo[] See ListDirectoryOptions below
getPathInfo(path) SmbTask<SmbFileInfo> SmbFileInfo Item itself plus SD; folders get childCount, no children
downloadFile(remote, local) SmbTask<void> void subscribe() for progress
uploadFile(local, remote) SmbTask<void> void subscribe() for progress
createDirectory(path) SmbTask<void> void Creates parents
deleteItem(path) SmbTask<void> void Recursive for dirs
renameItem(path, newName) SmbTask<void> void Basename only
moveItem(from, to) SmbTask<void> void
copyItem(from, to, recursive?) SmbTask<void> void
duplicateItem(path) SmbTask<string> string New path
getSecurityDescriptor(path) SmbTask<SmbSecurityDescriptor> SmbSecurityDescriptor
interface SmbFileInfo {
  name: string; path: string; size: number; isDirectory: boolean;
  modifiedAt: number; accessedAt: number; createdAt: number; changedAt: number;
  childCount?: number; children?: SmbFileInfo[];
  securityDescriptor?: SmbSecurityDescriptor;
}
interface ListDirectoryOptions {
  maxDepth?: number;                    // nested levels as `children`: 0 = this level only (default), -1 = unlimited
  includeSecurityDescriptor?: boolean;  // default false
  batchSize?: number;                   // top-level entries per streamed batch; default 10
}

Set includeSecurityDescriptor to true to issue an additional SD query for each returned item, including nested children. If the account is denied access to an item's SD, the item remains in the result without securityDescriptor; any other SD failure fails the listing.

getPathInfo reads the item itself (links resolve to their target; / is the share root) together with its SD. Folders also get childCount, but never children; use listDirectory for contents. If the account is denied access to the SD, path metadata is still returned without securityDescriptor; any other SD failure fails the task.

const files = await smb.listDirectory('/', { includeSecurityDescriptor: true }).result();
const firstDacl = files[0]?.securityDescriptor?.dacl;

Streaming a listing

listDirectory delivers top-level entries while the listing is still running, so large folders render before the scan finishes:

const task = smb.listDirectory('/Media');
const unsubscribe = task.subscribeEntries((batch) => {
  setFiles((prev) => prev.concat(batch));
});
try {
  await task.wait(); // or `await task.result()` for the complete array
} finally {
  unsubscribe();
}
  • Every streamed entry is final: directories already carry childCount, and securityDescriptor is set when requested.
  • Native flushes when batchSize entries are ready or 100 ms after the previous flush (the first flush goes out as soon as anything is ready). Each flush takes every entry ready at that moment, so it can be larger than batchSize.
  • Delivery to JS is notify-and-drain: a busy JS thread coalesces several native flushes into one subscribeEntries callback.
  • Subscribing late loses nothing: the first callback replays every entry emitted so far.
  • Entries arrive in server order. Sort in the UI if you need a stable order.
  • If the task fails or is cancelled, entries already received are an incomplete listing.
  • With a non-zero maxDepth, a top-level entry is emitted once its whole subtree is listed, carrying its complete children. Because entries keep server order, a large directory near the start delays every entry after it.

Pool

Method Returns Notes
getPoolInfo() PoolInfo Slot snapshot
subscribePoolInfo(cb) string Listener ID
unsubscribePoolInfo(id) void
resetPool() void Disconnect all slots
destroy() Promise<void> Cancel tasks, disconnect pool, stop transfer tracking; not reusable

See Connection pool.

Types

SmbTask<T>

Member Description
id Task identifier
progress, status Live getters after subscribe()
result() Promise<T>
wait() Promise<void>; settles like result() without reading the result value
subscribe(listener?) Returns unsubscribe
cancel() Abort
get() One-shot snapshot
SmbTask.settleAll(tasks) Promise.allSettled over results

SmbListTask

SmbTask<SmbFileInfo[]> returned by listDirectory, plus:

Member Description
subscribeEntries(listener) Receive entry batches (replays earlier ones first; coalesces while JS is busy); returns unsubscribe

Errors

SmbTaskError with code: SmbError and optional taskId.

Code SmbError Meaning
0 Unknown An unexpected internal or malformed bridge error. SMB operation failures use a specific code.
1 Cancelled The caller cancelled before the operation failed.
100 InvalidArgument Invalid URL, path, or operation argument.
101 NotFound The requested remote item does not exist.
102 AlreadyExists A destination or duplicate name is already present.
103 AccessDenied The authenticated account lacks access to the item or share.
104 NotDirectory A directory operation targeted a file.
105 IsDirectory A file operation targeted a directory.
106 DirectoryNotEmpty A directory could not be removed because it contains items.
200 NotConnected The SMB transport closed or is unavailable.
201 ConnectionRefused The server refused the connection.
202 TimedOut The SMB operation made no progress before its timeout.
203 AuthenticationFailed Credentials or account state prevented authentication.
300 Busy The item is locked or otherwise busy.
301 NoSpace Local or remote storage is full.
302 Io Other local or remote I/O failure.

Nested listing (maxDepth != 0), copy, duplicate, and delete fail on the first descendant failure; they never return a silent partial success. Security descriptors are omitted only when the account is denied descriptor access.

Hooks

Hook Purpose
useSubscribe(task) React state for progress/status
useTransfers(smb) Active transfers plus observed terminal transfers until cleared or hidden
useTransferActions(smb) clearCompleted(), hide(taskId)

Utilities

Path helpers:

Function Description
normalizePath Forward slashes, trim trailing /
splitPath { parentDirectory, baseFileName, extension, fullFileName }
joinPath, getParentPath, getFileName Path composition
generateCopyName "file copy 2.pdf" naming
formatFileSize, formatDate Display helpers

Label helpers: statusLabel, operationLabel, isTransferKind, isDeterminateKind, isTerminalStatus.