src/feature/control/control_proto.h

   1 /* Copyright (c) 2001 Matej Pfajfar.
   2  * Copyright (c) 2001-2004, Roger Dingledine.
   3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   4  * Copyright (c) 2007-2021, The Tor Project, Inc. */
   5 /* See LICENSE for licensing information */
   6
   7 /**
   8  * \file control_proto.h
   9  * \brief Header file for control_proto.c.
  10  *
  11  * See @ref replylines for details about the key-value abstraction for
  12  * generating reply lines.
  13  **/
  14
  15 #ifndef TOR_CONTROL_PROTO_H
  16 #define TOR_CONTROL_PROTO_H
  17
  18 #include "lib/encoding/confline.h"
  19
  20 /**
  21  * @defgroup replylines Control reply lines
  22  * @brief Key-value structures for control reply lines
  23  *
  24  * Control reply lines are config_line_t key-value structures with
  25  * some additional information to help formatting, such as the numeric
  26  * result code specified in the control protocol and flags affecting
  27  * the way kvline_encode() formats the @a kvline.
  28  *
  29  * Generally, modules implementing control commands will work with
  30  * smartlists of these structures, using functions like
  31  * control_reply_add_str() for adding a reply line consisting of a
  32  * single string, or control_reply_add_one_kv() and
  33  * control_reply_append_kv() for composing a line containing one or
  34  * more key-value pairs.
  35  *
  36  * @{
  37  */
  38 /** @brief A reply line for the control protocol.
  39  *
  40  * This wraps config_line_t with some additional information that's
  41  * useful when generating control reply lines.
  42  */
  43 typedef struct control_reply_line_t {
  44   int code;                     /**< numeric code */
  45   int flags;                    /**< kvline encoding flags */
  46   config_line_t *kvline;        /**< kvline */
  47 } control_reply_line_t;
  48
  49 void control_reply_line_free_(control_reply_line_t *line);
  50 /**
  51  * @brief Free and null a control_reply_line_t
  52  *
  53  * @param line pointer to control_reply_line_t to free
  54  */
  55 #define control_reply_line_free(line)                   \
  56   FREE_AND_NULL(control_reply_line_t,                   \
  57                 control_reply_line_free_, (line))
  58 /** @} */
  59
  60 void connection_write_str_to_buf(const char *s, control_connection_t *conn);
  61 void connection_printf_to_buf(control_connection_t *conn,
  62                                      const char *format, ...)
  63   CHECK_PRINTF(2,3);
  64
  65 size_t write_escaped_data(const char *data, size_t len, char **out);
  66 size_t read_escaped_data(const char *data, size_t len, char **out);
  67 void send_control_done(control_connection_t *conn);
  68
  69 MOCK_DECL(void, control_write_reply, (control_connection_t *conn, int code,
  70                                       int c, const char *s));
  71 void control_vprintf_reply(control_connection_t *conn, int code, int c,
  72                            const char *fmt, va_list ap)
  73   CHECK_PRINTF(4, 0);
  74 void control_write_endreply(control_connection_t *conn, int code,
  75                             const char *s);
  76 void control_printf_endreply(control_connection_t *conn, int code,
  77                              const char *fmt, ...)
  78   CHECK_PRINTF(3, 4);
  79 void control_write_midreply(control_connection_t *conn, int code,
  80                             const char *s);
  81 void control_printf_midreply(control_connection_t *conn, int code,
  82                              const char *fmt,
  83                              ...)
  84   CHECK_PRINTF(3, 4);
  85 void control_write_datareply(control_connection_t *conn, int code,
  86                              const char *s);
  87 void control_printf_datareply(control_connection_t *conn, int code,
  88                               const char *fmt,
  89                               ...)
  90   CHECK_PRINTF(3, 4);
  91 void control_write_data(control_connection_t *conn, const char *data);
  92
  93 /** @addtogroup replylines
  94  * @{
  95  */
  96 void control_write_reply_line(control_connection_t *conn,
  97                               const control_reply_line_t *line, bool lastone);
  98 void control_write_reply_lines(control_connection_t *conn, smartlist_t *lines);
  99
 100 void control_reply_add_one_kv(smartlist_t *reply, int code, int flags,
 101                               const char *key, const char *val);
 102 void control_reply_append_kv(smartlist_t *reply, const char *key,
 103                              const char *val);
 104 void control_reply_add_str(smartlist_t *reply, int code, const char *s);
 105 void control_reply_add_printf(smartlist_t *reply, int code,
 106                               const char *fmt, ...)
 107   CHECK_PRINTF(3, 4);
 108 void control_reply_add_done(smartlist_t *reply);
 109
 110 void control_reply_clear(smartlist_t *reply);
 111 void control_reply_free_(smartlist_t *reply);
 112
 113 /** @brief Free and null a smartlist of control_reply_line_t.
 114  *
 115  * @param r pointer to smartlist_t of control_reply_line_t to free */
 116 #define control_reply_free(r) \
 117   FREE_AND_NULL(smartlist_t, control_reply_free_, (r))
 118 /** @} */
 119
 120 #endif /* !defined(TOR_CONTROL_PROTO_H) */