output-eve: doxygen docs for SCEveFileType

Add documentation for the SCEveFileType in Doxygen format.

diff --git a/src/output-eve.h b/src/output-eve.h
index e8c41996229e77fd7676c5c3d9a16aeb4232271e..385ecbf4581669a3040bb1df2ac16513cd60d0a2 100644 (file)
--- a/src/output-eve.h
+++ b/src/output-eve.h
@@ -36,23 +36,137 @@
 typedef uint32_t ThreadId;
 
 /**
- * Structure used to define an Eve output file type plugin.
+ * \brief Structure used to define an EVE output file type plugin.
+ *
+ * EVE filetypes implement an object with a file-like interface and
+ * are used to output EVE log records to files, syslog, or
+ * database. They can be built-in such as the syslog (see
+ * SyslogInitialize()) and nullsink (see NullLogInitialize()) outputs,
+ * registered by a library user or dynamically loaded as a plugin.
+ *
+ * The life cycle of an EVE filetype is:
+ *   - Init: called once for each EVE instance using this filetype
+ *   - ThreadInit: called once for each output thread
+ *   - Write: called for each log record
+ *   - ThreadInit: called once for each output thread on exit
+ *   - Deinit: called once for each EVE instance using this filetype on exit
+ *
+ * Examples:
+ * - built-in syslog: \ref src/output-eve-syslog.c
+ * - built-in nullsink: \ref src/output-eve-null.c
+ * - example plugin: \ref examples/plugins/c-json-filetype/filetype.c
+ *
+ * ### Multi-Threaded Note:
+ *
+ * The EVE logging system can be configured by the Suricata user to
+ * run in threaded or non-threaded modes. In the default non-threaded
+ * mode, ThreadInit will only be called once and the filetype does not
+ * need to be concerned with threads.
+ *
+ * However, in **threaded** mode, ThreadInit will be called multiple
+ * times and the filetype needs to be thread aware and thread-safe. If
+ * utilizing a unique resource such as a file for each thread then you
+ * may be naturally thread safe. However, if sharing a single file
+ * handle across all threads then your filetype will have to take care
+ * of locking, etc.
  */
 typedef struct SCEveFileType_ {
-    /* The name of the output, used to specify the output in the filetype section
-     * of the eve-log configuration. */
+    /**
+     * \brief The name of the output, used in the configuration.
+     *
+     * This name is used by the configuration file to specify the EVE
+     * filetype used.
+     *
+     * For example:
+     *
+     * \code{.yaml}
+     * outputs:
+     *   - eve-log:
+     *       filetype: my-output-name
+     * \endcode
+     */
     const char *name;
-    /* Init Called on first access */
+
+    /**
+     * \brief Function to initialize this filetype.
+     *
+     * \param conf The ConfNode of the `eve-log` configuration
+     *     section this filetype is being initialized for
+     *
+     * \param threaded Flag to specify if the EVE sub-systems is in
+     *     threaded mode or not
+     *
+     * \param init_data An output pointer for filetype specific data
+     *
+     * \retval 0 on success, -1 on failure
+     */
     int (*Init)(ConfNode *conf, bool threaded, void **init_data);
-    /* Write - Called on each write to the object */
+
+    /**
+     * \brief Called for each EVE log record.
+     *
+     * The Write function is called for each log EVE log record. The
+     * provided buffer contains a fully formatted EVE record in JSON
+     * format.
+     *
+     * \param buffer The fully formatted JSON EVE log record
+     *
+     * \param buffer_len The length of the buffer
+     *
+     * \param init_data The data setup in the call to Init
+     *
+     * \param thread_data The data setup in the call to ThreadInit
+     *
+     * \retval 0 on success, -1 on failure
+     */
     int (*Write)(const char *buffer, int buffer_len, void *init_data, void *thread_data);
-    /* Close - Called on final close */
+
+    /**
+     * \brief Final call to deinitialize this filetype.
+     *
+     * Called, usually on exit to deinitialize and free any resources
+     * allocated during Init.
+     *
+     * \param init_data Data setup in the call to Init.
+     */
     void (*Deinit)(void *init_data);
-    /* ThreadInit - Called for each thread using file object; non-zero thread_ids correlate
-     * to Suricata's worker threads; 0 correlates to the Suricata main thread */
+
+    /**
+     * \brief Initialize thread specific data.
+     *
+     * Initialize any thread specific data. For example, if
+     * implementing a file output you might open the files here, so
+     * you have one output file per thread.
+     *
+     * \param init_data Data setup during Init
+     *
+     * \param thread_id A unique ID to differentiate this thread from
+     *     others. If EVE is not in threaded mode this will be called
+     *     one with a ThreadId of 0. In threaded mode the ThreadId of
+     *     0 correlates to the main Suricata thread.
+     *
+     * \param thread_data Output pointer for any data required by this
+     *     thread.
+     *
+     * \retval 0 on success, -1 on failure
+     */
     int (*ThreadInit)(void *init_data, ThreadId thread_id, void **thread_data);
-    /* ThreadDeinit - Called for each thread using file object */
+
+    /**
+     * \brief Called to deinitialize each thread.
+     *
+     * This function will be called for each thread. It is where any
+     * resources allocated in ThreadInit should be released.
+     *
+     * \param init_data The data setup in Init
+     *
+     * \param thread_data The data setup in ThreadInit
+     *
+     * \retval 0 on success, -1 on failure
+     */
     int (*ThreadDeinit)(void *init_data, void *thread_data);
+
+    /* Internal list management. */
     TAILQ_ENTRY(SCEveFileType_) entries;
 } SCEveFileType;