network.capture

Syntax

network.capture(filter)

Parameters

filter

WinDivert capture filter, such as "udp and udp.DstPort >= 30000".

Return value

See the remarks for the returned value and runtime behavior.

Remarks

Starts or replaces network capture with a WinDivert filter such as "udp and udp.DstPort >= 30000"; an empty filter diverts every packet. Returns true when Atlas accepts the request: capture then starts in the background, network.active becomes true once packets can flow, and network.error explains a failure such as a declined administrator prompt, a WinDivert that is missing or unverified, or a filter WinDivert cannot compile. Returns false when Atlas refuses the request itself: the filter has more than 2048 characters, a character other than printable ASCII, tabs and line breaks, or unbalanced parentheses; starting the network helper already failed in this Run, for example because the administrator prompt was declined; or the script is not running (a global initializer or on_stop). network.error then gives the reason, from that call on, until a request is accepted or the script is loaded or run again. The first call in a Run shows the administrator prompt; later calls reuse the approved helper.

Examples

var logged = 0;

event on_start() {
    if (!network.capture("udp and udp.DstPort == 9000")) {
        system.log("Network capture could not start");
    }
}

event on_network_send() {
    if (logged < 20) {
        logged += 1;
        system.log(string.format("{}:{} -> {}:{}, {} payload bytes",
            packet.src_ip, packet.src_port, packet.dst_ip, packet.dst_port, packet.payload_length));
    }
}

event on_stop() {
    system.log(string.format("Sent {} matching packets", network.sent));
}

This complete, checked example also appears in Recipes.