Connecting
A plain, blocking TCP client with explicit timeouts on every wait — the counterpart of the callbacktcp listener, and the piece that lets a script speak line- or frame-oriented TCP protocols (the interpreter's own debugger among them: Tests/debugger_client_*.dom drive domin-debug with it).
tcpclient.Connect
tcpclient.Connect($Host, $Port, $TimeoutMs) -> i32
Opens a TCP connection to $Host (name or IPv4/IPv6 literal) on $Port, waiting at most $TimeoutMs for the handshake. Returns a handle (≥ 1) or 0 when the host could not be resolved or the connection was refused or timed out — that is an ordinary outcome, not a runtime error: read LastError and decide. A port outside 1..65535 or a negative timeout is a runtime error. Up to 64 connections may be open at once.
Sending and receiving
Text or raw bytes out; one line or whatever has arrived in. Timeouts and a closed peer are ordinary return values, not errors.
tcpclient.WriteText
tcpclient.WriteText($Handle, $Text) -> i32
Sends the bytes of $Text (no terminator is added — append "\n" yourself for line protocols). Returns the number of bytes actually sent; fewer than the length means the peer closed, and LastError says so.
tcpclient.WriteBlob
tcpclient.WriteBlob($Handle, $Data) -> i32
Sends the raw bytes of a blob. Same return contract as WriteText. Use it for binary or length-prefixed frames (the callbacktcp listener's frame is uint32 size + payload, big-endian).
tcpclient.ReadLine
tcpclient.ReadLine($Handle, $TimeoutMs) -> string
Returns one line from the stream without its trailing \n or \r\n, waiting at most $TimeoutMs for more bytes. Bytes after the newline stay buffered for the next call. Returns "" on timeout or when the peer closed — check LastError to tell an empty line from those (it is empty after a successful read). A line longer than 64 KiB is a runtime error.
tcpclient.ReadBlob
tcpclient.ReadBlob($Handle, $MaxBytes, $TimeoutMs) -> blob
Returns whatever has arrived, 1..$MaxBytes bytes (max 8192), like recv(); an empty blob means timeout or closed peer. A frame reader loops until it has the bytes it needs — see Tests/test_tcpclient_listener_roundtrip.dom for the exact-read helper.
Lifecycle and diagnostics
Closing and the last-error text.
tcpclient.Close
tcpclient.Close($Handle) -> i32
Closes the connection. Returns 1 if the handle was open, 0 if it was not (already closed or never valid) — never a runtime error, so cleanup code can call it unconditionally.
tcpclient.LastError
tcpclient.LastError() -> string
Text of the most recent failure on any connection (resolve, connect, timeout, peer closed), or "" when the last operation succeeded. The runtime-error paths (bad arguments, invalid handle, out of memory) set it too.
Example
A line-protocol exchange with the debugger, the way the test client does it.
plugin "../plugins/tcp_client/TcpClientPlugin"; plugin "../plugins/print/PrintPlugin"; i32 main() { i32 $C = tcpclient.Connect("127.0.0.1", 46100, 1000); if ($C == 0) { printf("no server: %s\n", tcpclient.LastError()); return 1; } string $Hello[256] = tcpclient.ReadLine($C, 5000); tcpclient.WriteText($C, "STACK\n"); string $Line[1024] = tcpclient.ReadLine($C, 5000); while (str.Equals($Line, "END") == 0) { printf("%s\n", $Line); $Line = tcpclient.ReadLine($C, 5000); } tcpclient.Close($C); return 0; }