control_proto.h (4687B)
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) */