All async methods return SmbTask<T>. Await with .result(). See Task model for subscribe, cancel, and hook patterns.
| 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; }| 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;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, andsecurityDescriptoris set when requested. - Native flushes when
batchSizeentries 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 thanbatchSize. - Delivery to JS is notify-and-drain: a busy JS thread coalesces several native flushes into one
subscribeEntriescallback. - 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 completechildren. Because entries keep server order, a large directory near the start delays every entry after it.
| 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.
| 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 |
SmbTask<SmbFileInfo[]> returned by listDirectory, plus:
| Member | Description |
|---|---|
subscribeEntries(listener) |
Receive entry batches (replays earlier ones first; coalesces while JS is busy); returns unsubscribe |
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.
| 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) |
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.