From 3cbdb28d30aa5c44ee798c9adf76176a0358f796 Mon Sep 17 00:00:00 2001 From: Robin Sommer Date: Mon, 6 May 2024 10:40:20 +0200 Subject: [PATCH] Regenerate Spicy docs. This goes with https://github.com/zeek/zeek/pull/3719. --- devel/spicy/autogen/zeek-functions.spicy | 74 +++++++++++++++++++----- 1 file changed, 58 insertions(+), 16 deletions(-) diff --git a/devel/spicy/autogen/zeek-functions.spicy b/devel/spicy/autogen/zeek-functions.spicy index a2cfb751e..603f85af5 100644 --- a/devel/spicy/autogen/zeek-functions.spicy +++ b/devel/spicy/autogen/zeek-functions.spicy @@ -61,49 +61,88 @@ Returns the number of packets seen so far on the current side of the current con .. _spicy_protocol_begin: -.. rubric:: ``function zeek::protocol_begin(analyzer: optional = Null)`` +.. rubric:: ``function zeek::protocol_begin(analyzer: optional, protocol: spicy::Protocol = spicy::Protocol::TCP)`` Adds a Zeek-side child protocol analyzer to the current connection. -If the same analyzer was added previously with protocol_handle_get_or_create or -protocol_begin with same argument, and not closed with protocol_handle_close -or protocol_end, no new analyzer will be added. +If the same analyzer was added previously with `protocol_handle_get_or_create` or +`protocol_begin` with same argument, and not closed with `protocol_handle_close` +or `protocol_end`, no new analyzer will be added. See `protocol_handle_get_or_create` for the error semantics of this function. analyzer: type of analyzer to instantiate, specified through its Zeek-side -name (similar to what Zeek's signature action `enable` takes); if not -specified, Zeek will perform its usual dynamic protocol detection to figure -out how to parse the data (the latter will work only for TCP protocols, though.) +name (similar to what Zeek's signature action `enable` takes) + +protocol: the transport-layer protocol that the analyzer uses; only TCP is +currently supported here + +Note: For backwards compatibility, the analyzer argument can be left unset to add +a DPD analyzer. This use is deprecated, though; use the single-argument version of +`protocol_begin` for that instead. + +.. _spicy_protocol_begin_2: + +.. rubric:: ``function zeek::protocol_begin(protocol: spicy::Protocol = spicy::Protocol::TCP)`` + +Adds a Zeek-side DPD child protocol analyzer performing dynamic protocol detection +on subsequently provided data. + +If the same DPD analyzer was added previously with `protocol_handle_get_or_create` or +`protocol_begin` with same argument, and not closed with `protocol_handle_close` +or `protocol_end`, no new analyzer will be added. + +See `protocol_handle_get_or_create` for the error semantics of this function. + +protocol: the transport-layer protocol on which to perform protocol detection; +only TCP is currently supported here .. _spicy_protocol_handle_get_or_create: -.. rubric:: ``function zeek::protocol_handle_get_or_create(analyzer: string) : ProtocolHandle`` +.. rubric:: ``function zeek::protocol_handle_get_or_create(analyzer: string, protocol: spicy::Protocol = spicy::Protocol::TCP) : ProtocolHandle`` Gets a handle to a Zeek-side child protocol analyzer for the current connection. -If no such child exists it will be added; otherwise a handle to the +If no such child exists yet it will be added; otherwise a handle to the existing child protocol analyzer will be returned. -This function will return an error +This function will return an error if: -- if not called from a protocol analyzer, or -- the requested child protocol analyzer is unknown, or +- not called from a protocol analyzer, or +- the requested child protocol analyzer is of unknown type or not support by the requested transport protocol, or - creation of a child analyzer of the requested type was prevented by a previous call of `disable_analyzer` with `prevent=T` -analyzer: type of analyzer to instantiate, specified through its Zeek-side +analyzer: type of analyzer to get or instantiate, specified through its Zeek-side name (similar to what Zeek's signature action `enable` takes). +protocol: the transport-layer protocol that the analyser uses; only TCP is +currently supported here + + .. _spicy_protocol_data_in: -.. rubric:: ``function zeek::protocol_data_in(is_orig: bool, data: bytes, h: optional = Null)`` +.. rubric:: ``function zeek::protocol_data_in(is_orig: bool, data: bytes, protocol: spicy::Protocol = spicy::Protocol::TCP)`` -Forwards protocol data to all previously instantiated Zeek-side child protocol analyzers. +Forwards protocol data to all previously instantiated Zeek-side child protocol analyzers of a given transport-layer. is_orig: true to feed the data to the child's originator side, false for the responder + data: chunk of data to forward to child analyzer -h: optional handle to the child analyzer to forward data into, else forward to all child analyzers + +protocol: the transport-layer protocol of the children to forward to; only TCP is currently supported here + +.. _spicy_protocol_data_in_2: + +.. rubric:: ``function zeek::protocol_data_in(is_orig: bool, data: bytes, h: ProtocolHandle)`` + +Forwards protocol data to a specific previously instantiated Zeek-side child analyzer. + +is_orig: true to feed the data to the child's originator side, false for the responder + +data: chunk of data to forward to child analyzer + +h: handle to the child analyzer to forward data into .. _spicy_protocol_gap: @@ -112,8 +151,11 @@ h: optional handle to the child analyzer to forward data into, else forward to a Signals a gap in input data to all previously instantiated Zeek-side child protocol analyzers. is_orig: true to signal gap to the child's originator side, false for the responder + offset: start offset of gap in input stream + len: size of gap + h: optional handle to the child analyzer signal a gap to, else signal to all child analyzers .. _spicy_protocol_end: