output-streaming: rename and document registration

Prefix the registration function and types with "SC", and add function
documentation.

Ticket: #7227

diff --git a/doc/userguide/devguide/extending/output/index.rst b/doc/userguide/devguide/extending/output/index.rst
index c401b3c4e7bbd2c4863e1bb4793b94292577858f..e5b22192ef07e7abfa70b76f8cf91fe83ac60f00 100644 (file)
--- a/doc/userguide/devguide/extending/output/index.rst
+++ b/doc/userguide/devguide/extending/output/index.rst
@@ -62,3 +62,18 @@ Transaction logger can be registered with the
    :language: c
    :start-at: /** \brief Register a transaction logger
    :end-at: );
+
+Stream Logging
+~~~~~~~~~~~~~~
+
+Stream logging allows for the logging of streaming data such as TCP
+reassembled data and HTTP body data. The provided log function will be
+called each time a new chunk of data is available.
+
+Stream loggers can be registered with the
+``SCOutputRegisterStreamingLogger`` function:
+
+.. literalinclude:: ../../../../../src/output-streaming.h
+   :language: c
+   :start-at: /** \brief Register a streaming logger
+   :end-at: );

diff --git a/src/log-tcp-data.c b/src/log-tcp-data.c
index a801c899787fd008edab812f661a4558e8a568c9..b4e8b18a86d0e9caad2c57d28747de6996719597 100644 (file)
--- a/src/log-tcp-data.c
+++ b/src/log-tcp-data.c
@@ -54,7 +54,7 @@ void LogTcpDataLogRegister (void) {
 
 typedef struct LogTcpDataFileCtx_ {
     LogFileCtx *file_ctx;
-    enum OutputStreamingType type;
+    enum SCOutputStreamingType type;
     const char *log_dir;
     int file;
     int dir;

diff --git a/src/output-streaming.c b/src/output-streaming.c
index a2e3067b081c1adbc0a6f22333c415f0bebe37eb..c81fbbc9ee3fc73b2114b9edc8933ea4b439f5ca 100644 (file)
--- a/src/output-streaming.c
+++ b/src/output-streaming.c
@@ -48,20 +48,20 @@ typedef struct OutputStreamingLoggerThreadData_ {
  * it's perfectly valid that have multiple instances of the same
  * log module (e.g. http.log) with different output ctx'. */
 typedef struct OutputStreamingLogger_ {
-    StreamingLogger LogFunc;
+    SCStreamingLogger LogFunc;
     void *initdata;
     struct OutputStreamingLogger_ *next;
     const char *name;
     LoggerId logger_id;
-    enum OutputStreamingType type;
+    enum SCOutputStreamingType type;
     ThreadInitFunc ThreadInit;
     ThreadDeinitFunc ThreadDeinit;
 } OutputStreamingLogger;
 
 static OutputStreamingLogger *list = NULL;
 
-int OutputRegisterStreamingLogger(LoggerId id, const char *name, StreamingLogger LogFunc,
-        void *initdata, enum OutputStreamingType type, ThreadInitFunc ThreadInit,
+int SCOutputRegisterStreamingLogger(LoggerId id, const char *name, SCStreamingLogger LogFunc,
+        void *initdata, enum SCOutputStreamingType type, ThreadInitFunc ThreadInit,
         ThreadDeinitFunc ThreadDeinit)
 {
     OutputStreamingLogger *op = SCCalloc(1, sizeof(*op));
@@ -98,7 +98,7 @@ typedef struct StreamerCallbackData_ {
     OutputLoggerThreadStore *store;
     ThreadVars *tv;
     Packet *p;
-    enum OutputStreamingType type;
+    enum SCOutputStreamingType type;
 } StreamerCallbackData;
 
 static int Streamer(void *cbdata, Flow *f, const uint8_t *data, uint32_t data_len, uint64_t tx_id, uint8_t flags)

diff --git a/src/output-streaming.h b/src/output-streaming.h
index 1af4058fe4bb30b1192a78bb5a6a11058b4370a8..c09f544371a35a4a5d0b322b66dd5258666ed914 100644 (file)
--- a/src/output-streaming.h
+++ b/src/output-streaming.h
@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2022 Open Information Security Foundation
+/* Copyright (C) 2007-2024 Open Information Security Foundation
  *
  * You can copy, redistribute or modify this Program under the terms of
  * the GNU General Public License version 2 as published by the Free
@@ -32,22 +32,41 @@
 #define OUTPUT_STREAMING_FLAG_TOCLIENT      0x08
 #define OUTPUT_STREAMING_FLAG_TRANSACTION   0x10
 
-enum OutputStreamingType {
+enum SCOutputStreamingType {
     STREAMING_TCP_DATA,
     STREAMING_HTTP_BODIES,
 };
 
 /** streaming logger function pointer type */
-typedef int (*StreamingLogger)(ThreadVars *, void *thread_data,
-        const Flow *f, const uint8_t *data, uint32_t data_len,
-        uint64_t tx_id, uint8_t flags);
+typedef int (*SCStreamingLogger)(ThreadVars *, void *thread_data, const Flow *f,
+        const uint8_t *data, uint32_t data_len, uint64_t tx_id, uint8_t flags);
 
-int OutputRegisterStreamingLogger(LoggerId id, const char *name, StreamingLogger LogFunc,
-        void *initdata, enum OutputStreamingType, ThreadInitFunc ThreadInit,
+/** \brief Register a streaming logger.
+ *
+ * \param logger_id An ID to uniquely identify this logger.
+ *
+ * \param name An informational name for this logger.
+ *
+ * \param LogFunc Pointer to logging function.
+ *
+ * \param initdata Initialization data that will be passed the
+ *     ThreadInit.
+ *
+ * \param stream_type Type of stream to log, see
+ *     SCOutputStreamingType.
+ *
+ * \param ThreadInit Pointer to thread initialization function.
+ *
+ * \param ThreadDeinit Pointer to thread de-initialization function.
+ */
+int SCOutputRegisterStreamingLogger(LoggerId logger_id, const char *name, SCStreamingLogger LogFunc,
+        void *initdata, enum SCOutputStreamingType stream_type, ThreadInitFunc ThreadInit,
         ThreadDeinitFunc ThreadDeinit);
 
+/** Internal function: private API. */
 void OutputStreamingLoggerRegister (void);
 
+/** Internal function: private API. */
 void OutputStreamingShutdown(void);
 
 #endif /* SURICATA_OUTPUT_STREAMING_H */

diff --git a/src/output.c b/src/output.c
index db399e25a65594aad55a05fc8f025a2227d74afb..46e7f808a830545d1768d4f6c94674868de6ae5b 100644 (file)
--- a/src/output.c
+++ b/src/output.c
@@ -501,8 +501,8 @@ error:
  * \retval Returns 0 on success, -1 on failure.
  */
 void OutputRegisterStreamingModule(LoggerId id, const char *name, const char *conf_name,
-        OutputInitFunc InitFunc, StreamingLogger StreamingLogFunc,
-        enum OutputStreamingType stream_type, ThreadInitFunc ThreadInit,
+        OutputInitFunc InitFunc, SCStreamingLogger StreamingLogFunc,
+        enum SCOutputStreamingType stream_type, ThreadInitFunc ThreadInit,
         ThreadDeinitFunc ThreadDeinit)
 {
     if (unlikely(StreamingLogFunc == NULL)) {

diff --git a/src/output.h b/src/output.h
index a7652f8d9d0fd09b3620324c3131101b3f7c1501..abbd907a1e47f2ecf6ca92c79370e008bc0bb41e 100644 (file)
--- a/src/output.h
+++ b/src/output.h
@@ -71,10 +71,10 @@ typedef struct OutputModule_ {
     FileLogger FileLogFunc;
     FiledataLogger FiledataLogFunc;
     FlowLogger FlowLogFunc;
-    StreamingLogger StreamingLogFunc;
+    SCStreamingLogger StreamingLogFunc;
     StatsLogger StatsLogFunc;
     AppProto alproto;
-    enum OutputStreamingType stream_type;
+    enum SCOutputStreamingType stream_type;
     int tc_log_progress;
     int ts_log_progress;
 
@@ -128,8 +128,8 @@ void OutputRegisterFlowSubModule(LoggerId id, const char *parent_name, const cha
         ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit);
 
 void OutputRegisterStreamingModule(LoggerId id, const char *name, const char *conf_name,
-        OutputInitFunc InitFunc, StreamingLogger StreamingLogFunc,
-        enum OutputStreamingType stream_type, ThreadInitFunc ThreadInit,
+        OutputInitFunc InitFunc, SCStreamingLogger StreamingLogFunc,
+        enum SCOutputStreamingType stream_type, ThreadInitFunc ThreadInit,
         ThreadDeinitFunc ThreadDeinit);
 
 void OutputRegisterStatsModule(LoggerId id, const char *name, const char *conf_name,

diff --git a/src/runmodes.c b/src/runmodes.c
index 9a2f20d5e81eb79d07b6b17eec0fa4c3ff8aabc8..eb4cfa879e89b38a5ba02842c9915b095c3ccc54 100644 (file)
--- a/src/runmodes.c
+++ b/src/runmodes.c
@@ -640,7 +640,7 @@ static void SetupOutput(
         file_logger_count++;
     } else if (module->StreamingLogFunc) {
         SCLogDebug("%s is a streaming logger", module->name);
-        OutputRegisterStreamingLogger(module->logger_id, module->name, module->StreamingLogFunc,
+        SCOutputRegisterStreamingLogger(module->logger_id, module->name, module->StreamingLogFunc,
                 output_ctx, module->stream_type, module->ThreadInit, module->ThreadDeinit);
     } else {
         SCLogError("Unknown logger type: name=%s", module->name);