doc/devguide: document eve callback

Document the callback for adding additional data to EVE.

Ticket: #4708

diff --git a/doc/userguide/devguide/extending/index.rst b/doc/userguide/devguide/extending/index.rst
index 0505f1625b055f6d5c49954e9065593ef41356a8..e2d56bdf07be47c54dc43952281dc6541da06c7b 100644 (file)
--- a/doc/userguide/devguide/extending/index.rst
+++ b/doc/userguide/devguide/extending/index.rst
@@ -10,3 +10,4 @@ Extending Suricata
    detect/index.rst
    output/index.rst
    output/eve-filetypes.rst
+   output/eve-hooks.rst

diff --git a/doc/userguide/devguide/extending/output/eve-hooks.rst b/doc/userguide/devguide/extending/output/eve-hooks.rst
new file mode 100644 (file)
index 0000000..f130f1e
--- /dev/null
+++ b/doc/userguide/devguide/extending/output/eve-hooks.rst
@@ -0,0 +1,43 @@
+EVE Hooks
+#########
+
+The EVE output provides a callback for additional data to be added to
+an EVE record before it is written.
+
+It is important to note that it does not allow for modification of the
+EVE record due to the append only nature of Suricata's EVE output.
+
+Registration
+************
+
+Registering the callback is done with ``SCEveRegisterCallback``.
+
+.. literalinclude:: ../../../../../src/output-eve.h
+   :language: c
+   :start-at: /** \brief Register a callback for adding extra information to EVE
+   :end-at: );
+
+Callback
+********
+
+The callback function is provided with an open ``SCJsonBuilder``
+instance just before being closed out with a final ``}``. Additional
+fields can be added with the ``SCJsonBuilder`` API.
+
+.. literalinclude:: ../../../../../src/output-eve.h
+   :language: c
+   :start-at: /** \brief Function type for EVE callbacks
+   :end-at: );
+
+Example
+*******
+
+For a real-life example, see the ``ndpi`` plugin included in the
+Suricata source.
+
+The example demonstrates:
+
+- Registering an EVE callback during plugin initialization
+- Using thread-local storage to maintain state
+- Adding protocol-specific information to EVE records
+- Properly checking for NULL pointers before accessing data