base64: Use para_isspace() everywhere.
[paraslash.git] / sideband.h
1 /*
2 * Copyright (C) 2012 Andre Noll <maan@tuebingen.mpg.de>
3 *
4 * Licensed under the GPL v2. For licencing details see COPYING.
5 */
6
7 /** \file sideband.h exported symbols from sideband.c */
8
9 /**
10 * The valid sideband designators.
11 *
12 * A sideband packet consists of a header and a body. The header is sent prior
13 * to the data and contains the length of the buffer and the sideband
14 * designator, an integer. This scheme allows receivers to never read more data
15 * than what was specified in the header.
16 *
17 * The sideband designator indicates the type of the data. The authentication
18 * handshake between the command handler (child of para_server) and the client
19 * requires to exchange several small packages. Each such package is sent as a
20 * sideband package with a dedicated designator.
21 *
22 * Other designators are employed for normal command output and for log
23 * messages, where each loglevel corresponds to a sideband designator.
24 *
25 * Note that the values of this enum are part of the ABI, so never change
26 * or remove entries. Appending is OK though.
27 */
28 #define SB_DESIGNATORS \
29 /* Special value for receiving only: Accept any band. */ \
30 DESIGNATOR(ANY), \
31 /* This packet contains the authentication challenge. */ \
32 DESIGNATOR(CHALLENGE), \
33 /* I solved your challenge and here is the proof. */ \
34 DESIGNATOR(CHALLENGE_RESPONSE), \
35 /* Congratulations, you are authenticated. */ \
36 DESIGNATOR(PROCEED), \
37 /* This is the command I want you to execute. */ \
38 DESIGNATOR(COMMAND), \
39 /* Ready to receive a blob (addblob commands only). */ \
40 DESIGNATOR(AWAITING_DATA), \
41 /* Normal command output (default). */ \
42 DESIGNATOR(OUTPUT), \
43 /* LL_DEBUG. */ \
44 DESIGNATOR(DEBUG_LOG), \
45 /* LL_INFO. */ \
46 DESIGNATOR(INFO_LOG), \
47 /* LL_NOTICE. */ \
48 DESIGNATOR(NOTICE_LOG), \
49 /* LL_WARNING, */ \
50 DESIGNATOR(WARNING_LOG), \
51 /* LL_ERROR. */ \
52 DESIGNATOR(ERROR_LOG), \
53 /* LL_CRIT. */ \
54 DESIGNATOR(CRIT_LOG), \
55 /* LL_EMERG. */ \
56 DESIGNATOR(EMERG_LOG), \
57 /* Command terminated successfully. */ \
58 DESIGNATOR(EXIT__SUCCESS), \
59 /* Command failed. */ \
60 DESIGNATOR(EXIT__FAILURE), \
61 /* The next chunk of the blob (addblob commands only) */ \
62 DESIGNATOR(BLOB_DATA), \
63 /* An afs callback failed. */ \
64 DESIGNATOR(AFS_CB_FAILURE), \
65
66 /** Just prefix with \p SBD_. */
67 #define DESIGNATOR(x) SBD_ ## x
68
69 /** All valid sideband designators. */
70 enum sb_designator {SB_DESIGNATORS NUM_SB_DESIGNATORS};
71 #undef DESIGNATOR
72 /** One stringified sideband designator. */
73 #define DESIGNATOR(x) #x
74 /** List of stringified sidedband designators. */
75 #define SB_DESIGNATORS_ARRAY SB_DESIGNATORS
76
77 /**
78 * The information contained in a sideband buffer.
79 *
80 * This structure is used for both sending and receiving data through a
81 * sideband channel. A pointer to a sideband buffer is passed to the sending
82 * side of a sideband while the receiving end yields a filled out structure
83 * once all data has been received.
84 */
85 struct sb_buffer {
86 /** Data and length. */
87 struct iovec iov;
88 /** The band designator. */
89 uint8_t band;
90 };
91
92 /**
93 * The opaque sideband context structure.
94 *
95 * A pointer to a structure of this type is returned by the two \a sb_new_xxx
96 * functions as an opaque handle. Other public functions of the sideband API
97 * take such a handle as a parameter.
98 */
99 struct sb_context;
100
101 /**
102 * The type of a sideband transformation.
103 *
104 * The sideband API allows to filter all data through an arbitrary
105 * transformation, which is useful for crypto purposes. The transformation may
106 * either transform the data in place, or return a pointer to a new buffer
107 * which contains the transformed source buffer. The internal sideband
108 * functions can tell the two types of transformations apart by checking
109 * whether the destination buffer coincides with the source buffer.
110 *
111 * If the transformation allocates a new buffer, it _must_ allocate one extra
112 * byte for \p NULL termination.
113 */
114 typedef void (*sb_transformation)(struct iovec *src, struct iovec *dst,
115 void *trafo_context);
116
117
118 /** Initialize a sideband buffer. */
119 #define SBB_INIT(_band, _buf, _numbytes) \
120 { \
121 .band = _band, \
122 .iov = { \
123 .iov_base = _buf, \
124 .iov_len = _numbytes \
125 } \
126 };
127
128 /* receiving */
129 struct sb_context *sb_new_recv(size_t max_size, sb_transformation t,
130 void *trafo_context);
131 void sb_get_recv_buffer(struct sb_context *c, struct iovec *iov);
132 int sb_received(struct sb_context *c, size_t nbytes, struct sb_buffer *result);
133
134 /* sending */
135 struct sb_context *sb_new_send(struct sb_buffer *sbb, bool dont_free,
136 sb_transformation t, void *trafo_context);
137 int sb_get_send_buffers(struct sb_context *c, struct iovec iov[2]);
138 bool sb_sent(struct sb_context *c, size_t nbytes);
139
140 void sb_free(struct sb_context *c);