reply lines structures

Part of #30984.

1 files changed, 72 insertions, 0 deletions

diff --git a/src/feature/control/control_proto.h b/src/feature/control/control_proto.h
index 3182f3d415..65c81924fd 100644
--- a/src/feature/control/control_proto.h
+++ b/src/feature/control/control_proto.h
@@ -7,11 +7,56 @@
 /**
  * \file control_proto.h
  * \brief Header file for control_proto.c.
+ *
+ * See @ref replylines for details about the key-value abstraction for
+ * generating reply lines.
  **/
 
 #ifndef TOR_CONTROL_PROTO_H
 #define TOR_CONTROL_PROTO_H
 
+#include "lib/encoding/confline.h"
+
+/**
+ * @defgroup replylines Control reply lines
+ * @brief Key-value structures for control reply lines
+ *
+ * Control reply lines are config_line_t key-value structures with
+ * some additional information to help formatting, such as the numeric
+ * result code specified in the control protocol and flags affecting
+ * the way kvline_encode() formats the @a kvline.
+ *
+ * Generally, modules implementing control commands will work with
+ * smartlists of these structures, using functions like
+ * control_reply_add_str() for adding a reply line consisting of a
+ * single string, or control_reply_add_1kv() and
+ * control_reply_append_kv() for composing a line containing one or
+ * more key-value pairs.
+ *
+ * @{
+ */
+/** @brief A reply line for the control protocol.
+ *
+ * This wraps config_line_t with some additional information that's
+ * useful when generating control reply lines.
+ */
+typedef struct control_reply_line_t {
+  int code;                     /**< numeric code */
+  int flags;                    /**< kvline encoding flags */
+  config_line_t *kvline;        /**< kvline */
+} control_reply_line_t;
+
+void control_reply_line_free_(control_reply_line_t *line);
+/**
+ * @brief Free and null a control_reply_line_t
+ *
+ * @param line pointer to control_reply_line_t to free
+ */
+#define control_reply_line_free(line)                   \
+  FREE_AND_NULL(control_reply_line_t,                   \
+                control_reply_line_free_, (line))
+/** @} */
+
 void connection_write_str_to_buf(const char *s, control_connection_t *conn);
 void connection_printf_to_buf(control_connection_t *conn,
                                      const char *format, ...)
@@ -45,4 +90,31 @@ void control_printf_datareply(control_connection_t *conn, int code,
   CHECK_PRINTF(3, 4);
 void control_write_data(control_connection_t *conn, const char *data);
 
+/** @addtogroup replylines
+ * @{
+ */
+void control_write_reply_line(control_connection_t *conn,
+                              const control_reply_line_t *line, bool lastone);
+void control_write_reply_lines(control_connection_t *conn, smartlist_t *lines);
+
+void control_reply_add_1kv(smartlist_t *reply, int code, int flags,
+                           const char *key, const char *val);
+void control_reply_append_kv(smartlist_t *reply, const char *key,
+                             const char *val);
+void control_reply_add_str(smartlist_t *reply, int code, const char *s);
+void control_reply_add_printf(smartlist_t *reply, int code,
+                              const char *fmt, ...)
+  CHECK_PRINTF(3, 4);
+void control_reply_add_done(smartlist_t *reply);
+
+void control_reply_clear(smartlist_t *reply);
+void control_reply_free_(smartlist_t *reply);
+
+/** @brief Free and null a smartlist of control_reply_line_t.
+ *
+ * @param r pointer to smartlist_t of control_reply_line_t to free */
+#define control_reply_free(r) \
+  FREE_AND_NULL(smartlist_t, control_reply_free_, (r))
+/** @} */
+
 #endif /* !defined(TOR_CONTROL_PROTO_H) */