Tor  0.4.7.0-alpha-dev
control_proto.h
Go to the documentation of this file.
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 */
48 
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);
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);
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);
77  const char *fmt, ...)
78  CHECK_PRINTF(3, 4);
79 void control_write_midreply(control_connection_t *conn, int code,
80  const char *s);
82  const char *fmt,
83  ...)
84  CHECK_PRINTF(3, 4);
86  const char *s);
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  */
97  const control_reply_line_t *line, bool lastone);
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);
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) */
Header for confline.c.
void control_write_data(control_connection_t *conn, const char *data)
void control_printf_datareply(control_connection_t *conn, int code, const char *fmt,...)
void control_write_endreply(control_connection_t *conn, int code, const char *s)
void control_printf_midreply(control_connection_t *conn, int code, const char *fmt,...)
void control_write_midreply(control_connection_t *conn, int code, const char *s)
void send_control_done(control_connection_t *conn)
void control_vprintf_reply(control_connection_t *conn, int code, int c, const char *fmt, va_list ap)
void control_write_reply(control_connection_t *conn, int code, int c, const char *s)
void control_printf_endreply(control_connection_t *conn, int code, const char *fmt,...)
size_t read_escaped_data(const char *data, size_t len, char **out)
void connection_write_str_to_buf(const char *s, control_connection_t *conn)
Definition: control_proto.c:32
void control_write_datareply(control_connection_t *conn, int code, const char *s)
size_t write_escaped_data(const char *data, size_t len, char **out)
Definition: control_proto.c:71
void connection_printf_to_buf(control_connection_t *conn, const char *format,...)
Definition: control_proto.c:41
void control_reply_append_kv(smartlist_t *reply, const char *key, const char *val)
void control_write_reply_lines(control_connection_t *conn, smartlist_t *lines)
void control_reply_clear(smartlist_t *reply)
void control_reply_add_printf(smartlist_t *reply, int code, const char *fmt,...)
void control_reply_add_one_kv(smartlist_t *reply, int code, int flags, const char *key, const char *val)
void control_reply_line_free_(control_reply_line_t *line)
void control_reply_add_str(smartlist_t *reply, int code, const char *s)
void control_reply_add_done(smartlist_t *reply)
void control_write_reply_line(control_connection_t *conn, const control_reply_line_t *line, bool lastone)
void control_reply_free_(smartlist_t *reply)
A reply line for the control protocol.
Definition: control_proto.h:43
config_line_t * kvline
Definition: control_proto.h:46
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127