udp_client

Introduction

The udp_client plugin is the counterpart of udp_server: it opens a UDP-sending endpoint on loopback and works **bidirectionally**. With SendText/SendBlob calls it sends datagrams to a given host:port address, and a concurrent background thread forwards any incoming replies to a script-level callback. So a single plugin serves both request sending and reply receiving — a classic UDP request-response pattern.

Relationship to udp_server and async_meta

The two plugins (client and server) share lifecycle and state model. State returns async_meta.RouteStateOpen (=1) or RouteStateClosed (=0); StateText is the “open”/“closed” text counterpart. The callback form is identical on both sides: the borrowed blob is the raw datagram, and the peer's host and port arrive as optional extra parameters (ref blob $X, string $PeerHost, i32 $PeerPort).

Lifecycle in a nutshell

(1) Open(callbackName, timeoutMs, localPort?) opens a UDP socket on loopback and starts a background thread for incoming replies. (2) SendText or SendBlob sends a datagram. (3) If a reply arrives, the background thread forwards it to the callback: the blob is the raw reply payload, with the peer's host and port as extra parameters. (4) Close shuts down the socket and waits for the thread to stop. Meanwhile, the state and diagnostic functions (LocalPort, State, Delivered, Dropped, Info, OpenCount) can be queried any time.

Loading the plugin

plugin "builtin:print";
plugin "../plugins/udp_client/UdpClientPlugin";

A typical flow — UDP request-response

callback i32 OnReply(ref blob $X)
{
    // ... process the reply ...
    return(1);
}
i32 main()
{
    i64 $cli;
    $cli = udp_client.Open("OnReply", -1, 0);
    udp_client.SendText($cli, "127.0.0.1", 9999, "PING");
    // ... wait (e.g. timer.SleepMs), meanwhile OnReply may fire ...
    udp_client.Close($cli);
    return(0);
}

What to know about every function (the basics)

• Open always binds to LOOPBACK (127.0.0.1) — a security default, as on the server side.

• localPort = 0 lets the OS pick a free port; the actual port is returned by LocalPort.

• timeout = -1 means infinite wait for callback invocation. With a positive timeoutMs, the background thread DROPS an incoming packet if the callback does not fit in the time limit.

• SendBlob and SendText return the ACTUALLY sent byte count — for UDP, this is normally exactly the payload size.

• SendText internally calls SendBlob: it wraps the string as a read-only external blob and sends it.

• EnableAnsiColors returns 1 on Linux (already supported); on Windows it tries to enable virtual-terminal mode (ENABLE_VIRTUAL_TERMINAL_PROCESSING) — handy for colored logging/diagnostic output.

• An error (stopping the script) is caused by a wrong argument count or type, an out-of-range port (0..65535) or timeout, an invalid clientId, a host resolution failure, touching an already-closed client, and a socket/thread startup failure.

How to read the signatures

callbackName is the script-level reply callback name. timeoutMs is the maximum wait for callback invocation in milliseconds; -1 = infinite. localPort is the local (client-side) UDP port (0 = OS picks). clientId is the positive id given by Open. host is an IPv4 string or a name-resolvable name (typically “127.0.0.1” in the sandbox). The type after the -> arrow is the return type.