Actions

The SMB connector exposes the following clients:

Available clients:

Client	Purpose
`Client`	Perform imperative file operations on SMB shares — read, write, patch, list, create, delete, move, copy, and rename files and directories

For event-driven integration, see the Trigger Reference.

Client

Connects to an SMB share to read, write, and manage files and directories, with support for text, JSON, XML, CSV, and binary content.

Configuration

ClientConfiguration

Field	Type	Default	Description
`host`	`string`	`"localhost"`	Target SMB server hostname or IP address
`port`	`int`	`445`	Port number of the SMB service
`share`	`string`	Required	SMB share name to connect to
`auth`	`AuthConfiguration`	—	Authentication credentials for the SMB connection
`dialects`	`Dialect[]`	`[SMB_3_1_1, SMB_3_0_2, SMB_3_0, SMB_2_1, SMB_2_0_2]`	SMB protocol dialects to negotiate with, in order of preference
`signRequired`	`boolean`	`false`	Whether SMB message signing is required
`encryptData`	`boolean`	`false`	Whether to encrypt SMB data
`enableDfs`	`boolean`	`false`	Whether to enable Distributed File System (DFS) support
`bufferSize`	`int`	`65536`	Size of the buffer for read/write operations in bytes
`connectTimeout`	`decimal`	`30.0`	Connection timeout in seconds
`laxDataBinding`	`boolean`	`false`	Whether to relax data binding for XML, JSON, and CSV content
`csvFailSafe`	`FailSafeOptions`	—	When set, skips malformed CSV records and logs them to a file instead of failing the operation

AuthConfiguration

Field	Type	Default	Description
`credentials`	`Credentials`	—	NTLMv2 credentials for the SMB connection
`kerberosConfig`	`KerberosConfig`	—	Kerberos authentication configuration

Credentials

Field	Type	Default	Description
`username`	`string`	Required	Username for SMB authentication
`password`	`string`	Required	Password for SMB authentication
`domain`	`string`	`"WORKGROUP"`	Domain for domain-based authentication

KerberosConfig

Field	Type	Default	Description
`principal`	`string`	Required	Kerberos principal name in the `user@REALM` format
`keytab`	`string`	—	Path to the keytab file; the password is used when this is not provided
`configFile`	`string`	—	Path to the Kerberos configuration file (`krb5.conf`)

FailSafeOptions

Field	Type	Default	Description
`contentType`	`ErrorLogContentType`	`METADATA`	What to record in the error log for each skipped CSV record: `METADATA`, `RAW`, or `RAW_AND_METADATA`

Initializing the client

import ballerina/smb;

smb:ClientConfiguration config = {
    host: "smb-server.example.com",
    share: "myshare",
    auth: {
        credentials: {
            username: "smbuser",
            password: "smbpassword",
            domain: "WORKGROUP"
        }
    }
};
smb:Client client = check new (config);

Operations

Read Operations

getBytes

Reads a file from an SMB share as a byte array.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path

Returns: byte[]|Error

Sample code:

byte[] content = check client->getBytes("/files/image.png");

Sample response:

[72, 101, 108, 108, 111, 44, 32, 87, 111, 114, 108, 100]

getText

Reads a file from an SMB share as text.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path

Returns: string|Error

Sample code:

string content = check client->getText("/files/readme.txt");

Sample response:

Hello, World!
This is file content read from the SMB share.

getJson

Reads a file from an SMB share and parses it as JSON. Supports type binding to records and other Ballerina types via the targetType parameter.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`targetType`	`typedesc<json>`	No	The type descriptor of the target type; defaults to `json`

Returns: json|Error

Sample code:

// Read as generic json
json content = check client->getJson("/data/config.json");

// Read with type binding
type Config record {| string env; int maxRetries; |};
Config config = check client->getJson("/data/config.json");

Sample response:

{
  "env": "production",
  "maxRetries": 3
}

getXml

Reads a file from an SMB share and parses it as XML. Supports type binding to records and other Ballerina types via the targetType parameter.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`targetType`	`typedesc<xml\|record {}>`	No	The type descriptor of the target type; defaults to `xml`

Returns: xml|Error

Sample code:

// Read as generic xml
xml content = check client->getXml("/data/report.xml");

// Read with type binding
type Book record {| string title; string author; |};
Book book = check client->getXml("/data/book.xml");

Sample response:

<report><title>Monthly Sales</title><total>42500</total></report>

getCsv

Reads a file from an SMB share and parses it as CSV. Supports parsing to string arrays or record arrays with type binding via the targetType parameter.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`targetType`	`typedesc<string[][]\|record {}[]>`	No	The type descriptor of the target type; defaults to `string[][]`

Returns: string[][]|Error

Sample code:

// Read as raw string arrays
string[][] rows = check client->getCsv("/data/employees.csv");

// Read with type binding
type Employee record {| string name; int age; string city; |};
Employee[] employees = check client->getCsv("/data/employees.csv");

Sample response:

[
  ["name", "age", "city"],
  ["Alice", "30", "New York"],
  ["Bob", "25", "London"]
]

getBytesAsStream

Retrieves the file content as a byte stream from an SMB share. Use this for large files to avoid loading the entire content into memory.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path to the file on the SMB server

Returns: stream<byte[], error?>|Error

Sample code:

stream<byte[], error?> byteStream = check client->getBytesAsStream("/files/large-video.mp4");
record {| byte[] value; |}? chunk = check byteStream.next();

Sample response:

[72, 101, 108, 108, 111, 44, 32, 87, 111, 114, 108, 100, 33]

getCsvAsStream

Retrieves the file content as a CSV stream from an SMB share. Supports streams of string arrays or bound record types, suitable for large CSV files processed row by row.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The path to the file on the SMB server
`targetType`	`typedesc<string[]\|record {}>`	No	Expected element type for automatic data binding; defaults to `string[]`

Returns: stream<string[], error?>|Error

Sample code:

// Stream as string arrays
stream<string[], error?> csvStream = check client->getCsvAsStream("/data/large-data.csv");
record {| string[] value; |}? row = check csvStream.next();

// Stream with type binding
type Product record {| string id; string name; decimal price; |};
stream<Product, error?> productStream = check client->getCsvAsStream("/data/products.csv");

Sample response:

["id", "name", "price"]

Write Operations

putBytes

Writes byte array content to a file on an SMB share. Use OVERWRITE to replace any existing file or APPEND to add to it.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`content`	`byte[]`	Yes	Byte array content to write
`option`	`FileWriteOption`	No	File write option: `OVERWRITE` or `APPEND` (default: `OVERWRITE`)

Returns: Error?

Sample code:

byte[] data = [72, 101, 108, 108, 111];
smb:Error? result = check client->putBytes("/uploads/binary.dat", data, smb:OVERWRITE);

putText

Writes text content to a file on an SMB share. Use OVERWRITE to replace any existing file or APPEND to add to it.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`content`	`string`	Yes	Text content to write
`option`	`FileWriteOption`	No	File write option: `OVERWRITE` or `APPEND` (default: `OVERWRITE`)

Returns: Error?

Sample code:

smb:Error? result = check client->putText("/logs/app.log", "Application started\n", smb:APPEND);

putJson

Writes JSON content to a file on an SMB share. Use OVERWRITE to replace any existing file or APPEND to add to it.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`content`	`json`	Yes	JSON content to write
`option`	`FileWriteOption`	No	File write option: `OVERWRITE` or `APPEND` (default: `OVERWRITE`)

Returns: Error?

Sample code:

json data = {name: "John", age: 30};
smb:Error? result = check client->putJson("/data/user.json", data, smb:OVERWRITE);

putXml

Writes XML content to a file on an SMB share. Accepts either a native xml value or a record that is automatically converted to XML. Use OVERWRITE to replace any existing file or APPEND to add to it.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`content`	`xml\|record {\|json...;\|}`	Yes	XML content or a record to be serialized as XML
`option`	`FileWriteOption`	No	File write option: `OVERWRITE` or `APPEND` (default: `OVERWRITE`)

Returns: Error?

Sample code:

xml data = xml `<person><name>John</name></person>`;
smb:Error? result = check client->putXml("/data/person.xml", data, smb:OVERWRITE);

putCsv

Writes CSV content to a file on an SMB share. Accepts both array-of-arrays (string[][]) and array-of-records formats. When overwriting with a record array, column headers are added automatically.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`content`	`string[][]\|record {}[]`	Yes	CSV content as an array of string arrays or array of records
`option`	`FileWriteOption`	No	File write option: `OVERWRITE` or `APPEND` (default: `OVERWRITE`)

Returns: Error?

Sample code:

string[][] csvData = [["name", "age"], ["Alice", "30"], ["Bob", "25"]];
smb:Error? result = check client->putCsv("/reports/employees.csv", csvData, smb:OVERWRITE);

putBytesAsStream

Writes a byte stream to a file on an SMB share. Use this to stream large files without loading the entire content into memory.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`content`	`stream<byte[], error?>`	Yes	Byte stream content to write
`option`	`FileWriteOption`	No	File write option: `OVERWRITE` or `APPEND` (default: `OVERWRITE`)

Returns: Error?

Sample code:

stream<byte[], error?> byteStream = check client->getBytesAsStream("/source/video.mp4");
smb:Error? result = check client->putBytesAsStream("/dest/video.mp4", byteStream, smb:OVERWRITE);

putCsvAsStream

Writes a CSV stream to a file on an SMB share. Accepts streams of string arrays or records, suitable for large CSV datasets processed row by row.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`content`	`stream<string[]\|record {}, error?>`	Yes	CSV stream content as a stream of string arrays or records
`option`	`FileWriteOption`	No	File write option: `OVERWRITE` or `APPEND` (default: `OVERWRITE`)

Returns: Error?

Sample code:

stream<string[], error?> csvStream = check client->getCsvAsStream("/source/data.csv");
smb:Error? result = check client->putCsvAsStream("/dest/data.csv", csvStream, smb:OVERWRITE);

patch

Writes byte array content at a specified byte offset in a file on an SMB share, leaving the rest of the file untouched.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path
`content`	`byte[]`	Yes	Byte array content to write
`offset`	`int`	Yes	The byte offset position in the file where writing should start

Returns: Error?

Sample code:

byte[] patch = [65, 66, 67];
smb:Error? result = check client->patch("/files/data.bin", patch, 100);

Directory Operations

list

Lists files and directories in a folder on an SMB share, returning metadata for each entry.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The directory path

Returns: FileInfo[]|Error

Sample code:

smb:FileInfo[] entries = check client->list("/reports");

Sample response:

[
  {
    "name": "report-2024.json",
    "path": "/reports/report-2024.json",
    "size": 2048,
    "modifiedAt": [1706745600, 0.0],
    "createdAt": [1706745600, 0.0],
    "accessedAt": [1706745600, 0.0],
    "writtenAt": [1706745600, 0.0],
    "isDirectory": false,
    "extension": "json",
    "isExecutable": false,
    "isHidden": false,
    "isWritable": true,
    "uri": "smb://smb-server/myshare/reports/report-2024.json"
  }
]

mkdir

Creates a new directory on an SMB share.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The directory path to create

Returns: Error?

Sample code:

smb:Error? result = check client->mkdir("/archive/2024");

rmdir

Deletes an empty directory on an SMB share. The directory must be empty before it can be removed.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The directory path to delete

Returns: Error?

Sample code:

smb:Error? result = check client->rmdir("/archive/2024");

File Management

rename

Renames a file or directory on an SMB share, or moves it to a new location within the same share.

Parameters:

Name	Type	Required	Description
`origin`	`string`	Yes	The source file or directory location
`destination`	`string`	Yes	The destination file or directory location

Returns: Error?

Sample code:

smb:Error? result = check client->rename("/files/old-name.txt", "/files/new-name.txt");

move

Moves a file from one location to another on an SMB share.

Parameters:

Name	Type	Required	Description
`sourcePath`	`string`	Yes	The source file location
`destinationPath`	`string`	Yes	The destination file location

Returns: Error?

Sample code:

smb:Error? result = check client->move("/inbox/report.json", "/processed/report.json");

copy

Copies a file from one location to another on an SMB share, leaving the original file in place.

Parameters:

Name	Type	Required	Description
`sourcePath`	`string`	Yes	The source file location
`destinationPath`	`string`	Yes	The destination file location

Returns: Error?

Sample code:

smb:Error? result = check client->copy("/templates/invoice.xml", "/output/invoice-2024.xml");

delete

Deletes a file from an SMB share.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path

Returns: Error?

Sample code:

smb:Error? result = check client->delete("/temp/scratch.txt");

exists

Checks if a file or directory exists on an SMB share.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path

Returns: boolean|Error

Sample code:

boolean fileExists = check client->exists("/uploads/report.json");

Sample response:

true

size

Gets the size of a file on an SMB share in bytes.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path

Returns: int|Error

Sample code:

int fileSize = check client->size("/uploads/data.csv");

Sample response:

isDirectory

Checks if a given resource on an SMB share is a directory.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The resource path

Returns: boolean|Error

Sample code:

boolean isDir = check client->isDirectory("/archive");

Sample response:

true

Connection

Closes the SMB client connection and releases associated resources.

Parameters:

None

Returns: Error?

Sample code:

smb:Error? result = check client->close();

Client​

Configuration​

Initializing the client​

Operations​

Read Operations​

Write Operations​

Directory Operations​

File Management​

Connection​

Client

Configuration

Initializing the client

Operations

Read Operations

Write Operations

Directory Operations

File Management

Connection