From 1ebf33b3c9dc878e843487ef3974aa81829fbbcb Mon Sep 17 00:00:00 2001
From: Jason Ish <jason.ish@oisf.net>
Date: Thu, 29 Aug 2024 16:55:57 -0600
Subject: [PATCH] output-tx: rename and document transaction logger
 registration

Rename OutputRegisterTxLogger to SCOutputRegisterTxLogger to make it
part of the public API as well as document.

Ticket: #7227
---
 .../devguide/extending/output/index.rst       | 16 +++++++
 src/output-tx.c                               |  2 +-
 src/output-tx.h                               | 45 +++++++++++++++++--
 src/runmodes.c                                |  4 +-
 4 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/doc/userguide/devguide/extending/output/index.rst b/doc/userguide/devguide/extending/output/index.rst
index cb6315e88f..c401b3c4e7 100644
--- a/doc/userguide/devguide/extending/output/index.rst
+++ b/doc/userguide/devguide/extending/output/index.rst
@@ -46,3 +46,19 @@ function:
    :language: c
    :start-at: /** \brief Register a flow logger
    :end-at: );
+
+Transaction Logging
+~~~~~~~~~~~~~~~~~~~
+
+Transaction logger can be registered with the
+``SCOutputRegisterTxLogger`` function:
+
+.. attention:: Transaction loggers cannot be registered from a plugin
+               at this time, see
+               https://redmine.openinfosecfoundation.org/issues/7236
+               for more information.
+
+.. literalinclude:: ../../../../../src/output-tx.h
+   :language: c
+   :start-at: /** \brief Register a transaction logger
+   :end-at: );
diff --git a/src/output-tx.c b/src/output-tx.c
index 30fee3c370..3a870529c1 100644
--- a/src/output-tx.c
+++ b/src/output-tx.c
@@ -62,7 +62,7 @@ typedef struct OutputTxLogger_ {
 
 static OutputTxLogger **list = NULL;
 
-int OutputRegisterTxLogger(LoggerId id, const char *name, AppProto alproto, TxLogger LogFunc,
+int SCOutputRegisterTxLogger(LoggerId id, const char *name, AppProto alproto, TxLogger LogFunc,
         void *initdata, int tc_log_progress, int ts_log_progress, TxLoggerCondition LogCondition,
         ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit)
 {
diff --git a/src/output-tx.h b/src/output-tx.h
index 86fe437b32..8bf52d4c57 100644
--- a/src/output-tx.h
+++ b/src/output-tx.h
@@ -30,21 +30,58 @@
 #include "decode.h"
 #include "flow.h"
 
-/** tx logger function pointer type */
+/** \brief Transaction logger function pointer type. */
 typedef int (*TxLogger)(ThreadVars *, void *thread_data, const Packet *, Flow *f, void *state, void *tx, uint64_t tx_id);
 
-/** tx logger condition function pointer type,
- *  must return true for tx that should be logged
+/** \brief Transaction logger condition function pointer type.
+ *
+ * If a TxLoggerCondition is provided to the registration function,
+ * the logger function will only be called if this return true.
  */
 typedef bool (*TxLoggerCondition)(
         ThreadVars *, const Packet *, void *state, void *tx, uint64_t tx_id);
 
-int OutputRegisterTxLogger(LoggerId id, const char *name, AppProto alproto, TxLogger LogFunc,
+/** \brief Register a transaction logger.
+ *
+ * \param logger_id An ID used to distinguish this logger from others
+ *     while profiling. For transaction logging this is only used for
+ *     some internal state tracking.
+ *
+ * \param name An informational name for this logger. Used for
+ *     debugging.
+ *
+ * \param alproto The application layer protocol this logger is for,
+ *     for example ALPROTO_DNS.
+ *
+ * \param LogFunc A pointer to the logging function.
+ *
+ * \param initdata Initialization data that will be provided to the
+ *     ThreadInit callback.
+ *
+ * \param tc_log_progress The to_client progress state required for
+ *     the log function to be called.
+ *
+ * \param ts_log_progress The to_server progress state required for
+ *     the log function to be called.
+ *
+ * \param LogCondition A pointer to a function that will be called
+ *     before the log function to test if the log function should be
+ *     called.
+ *
+ * \param ThreadInitFunc Callback a thread initialization function,
+ *     initdata will be provided.
+ *
+ * \param ThreadDeinitFunc Callback to a thread de-initialization
+ *     function for cleanup.
+ */
+int SCOutputRegisterTxLogger(LoggerId id, const char *name, AppProto alproto, TxLogger LogFunc,
         void *, int tc_log_progress, int ts_log_progress, TxLoggerCondition LogCondition,
         ThreadInitFunc, ThreadDeinitFunc);
 
+/** Internal function: private API. */
 void OutputTxLoggerRegister (void);
 
+/** Internal function: private API. */
 void OutputTxShutdown(void);
 
 #endif /* SURICATA_OUTPUT_TX_H */
diff --git a/src/runmodes.c b/src/runmodes.c
index 034e0e35a7..048747b074 100644
--- a/src/runmodes.c
+++ b/src/runmodes.c
@@ -622,8 +622,8 @@ static void SetupOutput(
                 module->PacketConditionFunc, output_ctx, module->ThreadInit, module->ThreadDeinit);
     } else if (module->TxLogFunc) {
         SCLogDebug("%s is a tx logger", module->name);
-        OutputRegisterTxLogger(module->logger_id, module->name, module->alproto, module->TxLogFunc,
-                output_ctx, module->tc_log_progress, module->ts_log_progress,
+        SCOutputRegisterTxLogger(module->logger_id, module->name, module->alproto,
+                module->TxLogFunc, output_ctx, module->tc_log_progress, module->ts_log_progress,
                 module->TxLogCondition, module->ThreadInit, module->ThreadDeinit);
         /* Not used with wild card loggers */
         if (module->alproto != ALPROTO_UNKNOWN) {