smb_client.h File Reference

SMB2 client dialogue engine (PROTOCORE_ENABLE_SMB) - drives the smb2 / ntlm / spnego wire codecs through a real session to open a file on a Windows share. More...

#include "network_drivers/application/smb/smb2/smb2.h"
#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	SmbConfig
	Server credentials + the file to open. Strings are ASCII/UTF-8 (encoded UTF-16LE for you). More...
struct	SmbHandle
	An open file on an authenticated session; the ids thread the follow-up requests. More...
struct	SmbClientNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Typedefs
typedef enum PROTO_ENUM_PACKED	SmbResult
	Result of an SMB client operation. 0 is success; each failure is a distinct code.
typedef int(*	SmbSendFn) (void *ctx, const uint8_t *data, size_t len)
	Transport seam: the engine moves raw bytes only through these, so it runs against a real socket (protocore_client) or a test mock.
typedef int(*	SmbRecvFn) (void *ctx, uint8_t *buf, size_t cap)

Enumerations
enum	PROTO_ENUM_PACKED {   SMB_OK = 0 , SMB_ERR_ARG = -1 , SMB_ERR_IO = -2 , SMB_ERR_PROTOCOL = -3 ,   SMB_ERR_AUTH = -4 , SMB_ERR_OVERFLOW = -5 }
	Result of an SMB client operation. 0 is success; each failure is a distinct code. More...

Functions
	PROTOCORE_NS_LAYOUT (SmbClientNs, smb_open, smb_close, smb_read, smb_write)
SmbResult	protocore_smb_client_smb_open (uint8_t *work, const SmbConfig *cfg, SmbHandle *h, SmbSendFn send, SmbRecvFn recv, void *ctx)
	Run NEGOTIATE -> NTLMv2 SESSION_SETUP -> TREE_CONNECT -> CREATE and .
SmbResult	protocore_smb_client_smb_close (uint8_t *work, SmbHandle *h, SmbSendFn send, SmbRecvFn recv, void *ctx)
	CLOSE the open handle (releases the server-side FileId).
SmbResult	protocore_smb_client_smb_read (uint8_t *work, SmbHandle *h, uint64_t offset, uint8_t *out, size_t cap, size_t *out_len, SmbSendFn send, SmbRecvFn recv, void *ctx)
	Read up to cap bytes from offset of the open handle, looping READ .
SmbResult	protocore_smb_client_smb_write (uint8_t *work, SmbHandle *h, uint64_t offset, const uint8_t *data, size_t len, size_t *written, SmbSendFn send, SmbRecvFn recv, void *ctx)
	Write len bytes at offset of the open handle, looping WRITE .
uint8_t *	protocore_smb_client_span (void)
	The PROTOCORE_SMB_CLIENT_BORROW bytes this module's state lives in.

Variables
PROTOCORE_NS SmbClientNs SmbClient	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

SMB2 client dialogue engine (PROTOCORE_ENABLE_SMB) - drives the smb2 / ntlm / spnego wire codecs through a real session to open a file on a Windows share.

The wire codecs (smb2.h, ntlm.h, ntlmssp.h, spnego.h) are pure builders/parsers; this ties them into the actual exchange: NEGOTIATE, the two-round NTLMv2 SESSION_SETUP (SPNEGO-wrapped), TREE_CONNECT to \\server\share, and CREATE to open the file - handing back a handle that smb_read / smb_write / smb_close use. Like the SMTP engine it is written against a send/recv seam, so the whole exchange is host-tested with a scripted mock SMB2 server (no lwIP / real share).

Direct-TCP framing (the 4-byte length prefix) is handled here: each request is framed before send, each response is de-framed after recv (accumulating until a full message arrives).

work is PROTOCORE_SMB_CLIENT_BORROW bytes the CALLER took, at an address it knows. It is not held past the call, so nothing here aliases it. How those bytes are carved is this module's and is never named here.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file smb_client.h.

Typedef Documentation

SmbResult

typedef enum PROTO_ENUM_PACKED SmbResult

Result of an SMB client operation. 0 is success; each failure is a distinct code.

SmbSendFn

typedef int(* SmbSendFn)(void *ctx, const uint8_t *data, size_t len)

Transport seam: the engine moves raw bytes only through these, so it runs against a real socket (protocore_client) or a test mock.

Returns

send: bytes written (must equal len), else < 0. recv: bytes read (> 0), else <= 0 on close / error / timeout.

Definition at line 51 of file smb_client.h.

SmbRecvFn

typedef int(* SmbRecvFn) (void *ctx, uint8_t *buf, size_t cap)

Definition at line 53 of file smb_client.h.

Enumeration Type Documentation

PROTO_ENUM_PACKED

enum PROTO_ENUM_PACKED

Result of an SMB client operation. 0 is success; each failure is a distinct code.

Enumerator
SMB_OK
SMB_ERR_ARG	a required field was null/empty
SMB_ERR_IO	a send/recv failed, timed out, or the peer closed mid-message
SMB_ERR_PROTOCOL	a malformed response, or an unexpected NT status
SMB_ERR_AUTH	SESSION_SETUP was rejected (bad user/password/domain)
SMB_ERR_OVERFLOW	a message did not fit the work buffer (PROTOCORE_SMB_BUF)

Definition at line 35 of file smb_client.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	SmbClientNs	,
		smb_open	,
		smb_close	,
		smb_read	,
		smb_write
	)

protocore_smb_client_smb_open()

SmbResult protocore_smb_client_smb_open	(	uint8_t *	work,
		const SmbConfig *	cfg,
		SmbHandle *	h,
		SmbSendFn	send,
		SmbRecvFn	recv,
		void *	ctx
	)

Run NEGOTIATE -> NTLMv2 SESSION_SETUP -> TREE_CONNECT -> CREATE and .

Parameters

work	PROTOCORE_SMB_CLIENT_BORROW bytes the caller took. Not held past the call.
cfg	Cfg
h	H
send	Send
recv	Recv
ctx	Ctx

Returns

The SmbResult.

protocore_smb_client_smb_close()

SmbResult protocore_smb_client_smb_close	(	uint8_t *	work,
		SmbHandle *	h,
		SmbSendFn	send,
		SmbRecvFn	recv,
		void *	ctx
	)

CLOSE the open handle (releases the server-side FileId).

Parameters

work	PROTOCORE_SMB_CLIENT_BORROW bytes the caller took. Not held past the call.
h	H
send	Send
recv	Recv
ctx	Ctx

Returns

The SmbResult.

protocore_smb_client_smb_read()

SmbResult protocore_smb_client_smb_read	(	uint8_t *	work,
		SmbHandle *	h,
		uint64_t	offset,
		uint8_t *	out,
		size_t	cap,
		size_t *	out_len,
		SmbSendFn	send,
		SmbRecvFn	recv,
		void *	ctx
	)

Read up to cap bytes from offset of the open handle, looping READ .

Parameters

work	PROTOCORE_SMB_CLIENT_BORROW bytes the caller took. Not held past the call.
h	H
offset	Offset
out	Out
cap	Cap
out_len	receives the number of bytes actually read (may be < cap at EOF)
send	Send
recv	Recv
ctx	Ctx

Returns

The SmbResult.

protocore_smb_client_smb_write()

SmbResult protocore_smb_client_smb_write	(	uint8_t *	work,
		SmbHandle *	h,
		uint64_t	offset,
		const uint8_t *	data,
		size_t	len,
		size_t *	written,
		SmbSendFn	send,
		SmbRecvFn	recv,
		void *	ctx
	)

Write len bytes at offset of the open handle, looping WRITE .

Parameters

work	PROTOCORE_SMB_CLIENT_BORROW bytes the caller took. Not held past the call.
h	H
offset	Offset
data	Data
len	Len
written	receives the number of bytes written (equals len on success)
send	Send
recv	Recv
ctx	Ctx

Returns

The SmbResult.

protocore_smb_client_span()

uint8_t * protocore_smb_client_span

(

void

)

The PROTOCORE_SMB_CLIENT_BORROW bytes this module's state lives in.

Stated beside the namespace rather than on it: an entry takes a borrow, and this is where that borrow comes from. Taken once from the end of the pool, which no mark and no release walks, so the state lasts the life of the program.

Returns

the span.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS SmbClientNs SmbClient PROTOCORE_UNUSED

Initial value:

= {.smb_open = protocore_smb_client_smb_open,
                                                       .smb_close = protocore_smb_client_smb_close,
                                                       .smb_read = protocore_smb_client_smb_read,
                                                       .smb_write = protocore_smb_client_smb_write}

Module namespace.

Definition at line 174 of file smb_client.h.