stream_process_request.h (8724B)
1 /* SPDX-License-Identifier: LGPL-2.1-or-later OR (GPL-2.0-or-later WITH eCos-exception-2.0) */ 2 /* 3 This file is part of GNU libmicrohttpd. 4 Copyright (C) 2014-2024 Evgeny Grin (Karlson2k) 5 Copyright (C) 2007-2020 Daniel Pittman and Christian Grothoff 6 7 GNU libmicrohttpd is free software; you can redistribute it and/or 8 modify it under the terms of the GNU Lesser General Public 9 License as published by the Free Software Foundation; either 10 version 2.1 of the License, or (at your option) any later version. 11 12 GNU libmicrohttpd is distributed in the hope that it will be useful, 13 but WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 Lesser General Public License for more details. 16 17 Alternatively, you can redistribute GNU libmicrohttpd and/or 18 modify it under the terms of the GNU General Public License as 19 published by the Free Software Foundation; either version 2 of 20 the License, or (at your option) any later version, together 21 with the eCos exception, as follows: 22 23 As a special exception, if other files instantiate templates or 24 use macros or inline functions from this file, or you compile this 25 file and link it with other works to produce a work based on this 26 file, this file does not by itself cause the resulting work to be 27 covered by the GNU General Public License. However the source code 28 for this file must still be made available in accordance with 29 section (3) of the GNU General Public License v2. 30 31 This exception does not invalidate any other reasons why a work 32 based on this file might be covered by the GNU General Public 33 License. 34 35 You should have received copies of the GNU Lesser General Public 36 License and the GNU General Public License along with this library; 37 if not, see <https://www.gnu.org/licenses/>. 38 */ 39 40 /** 41 * @file src/mhd2/stream_process_request.h 42 * @brief The declarations of internal functions for requests parsing 43 * and processing 44 * @author Karlson2k (Evgeny Grin) 45 * 46 * Based on the MHD v0.x code by Daniel Pittman, Christian Grothoff and other 47 * contributors. 48 */ 49 50 #ifndef MHD_STREAM_PROCESS_REQUEST_H 51 #define MHD_STREAM_PROCESS_REQUEST_H 1 52 53 #include "mhd_sys_options.h" 54 55 #include "sys_bool_type.h" 56 #include "sys_base_types.h" 57 58 #include "mhd_str_types.h" 59 60 struct MHD_Connection; /* forward declaration */ 61 struct MHD_UploadAction; /* forward declaration */ 62 63 /** 64 * Callback for iterating over GET parameters 65 * @param cls the iterator metadata 66 * @param name the name of the parameter 67 * @param value the value of the parameter 68 * @return bool to continue iterations, 69 * false to stop the iteration 70 */ 71 typedef bool 72 (MHD_FN_PAR_NONNULL_ (2) MHD_FN_PAR_NONNULL_ (3) 73 *mhd_GetArgumentInter)(void *restrict cls, 74 const struct MHD_String *restrict name, 75 const struct MHD_StringNullable *restrict value); 76 77 /** 78 * Parse and unescape the arguments given by the client 79 * as part of the HTTP request URI. 80 * 81 * @param args_len the function to call on each key-value pair found 82 * @param[in,out] args argument URI string (after "?" in URI), 83 * clobbered in the process! 84 * @param cb function to call on each key-value pair found 85 * @param cls the iterator context 86 * @return false on failure 87 * true on success (parsing succeeded, @a cb always returned true) 88 */ 89 MHD_INTERNAL bool 90 mhd_parse_uri_args (size_t args_len, 91 char *restrict args, 92 mhd_GetArgumentInter cb, 93 void *restrict cls) 94 MHD_FN_PAR_NONNULL_ (2) MHD_FN_PAR_CSTR_ (2) MHD_FN_PAR_INOUT_SIZE_ (2, 1); 95 96 97 /** 98 * Find and parse the request line. 99 * @param c the connection to process 100 * @return true if request line completely processed (or unrecoverable error 101 * found) and state is changed, 102 * false if not enough data yet in the receive buffer 103 */ 104 MHD_INTERNAL bool 105 mhd_stream_get_request_line (struct MHD_Connection *restrict c) 106 MHD_FN_PAR_NONNULL_ALL_; 107 108 /** 109 * Switch to request headers (field lines) processing state. 110 * @param c the connection to process 111 */ 112 MHD_INTERNAL void 113 mhd_stream_switch_to_rq_headers_proc (struct MHD_Connection *restrict c) 114 MHD_FN_PAR_NONNULL_ALL_; 115 116 /** 117 * Reset request header processing state. 118 * 119 * This function resets the processing state before processing the header 120 * (or footer) line. 121 * @param c the connection to process 122 */ 123 MHD_INTERNAL void 124 mhd_stream_reset_rq_hdr_proc_state (struct MHD_Connection *c) 125 MHD_FN_PAR_NONNULL_ALL_; 126 127 /** 128 * Find the end of the request GET parameters. 129 * Advance to the next state when done, handle errors. 130 * @param c the connection to process 131 * @param process_footers if true then footers are processed, 132 * if false then headers are processed 133 * @return true if request headers reading finished (either successfully 134 * or with error), 135 * false if not enough data yet in the receive buffer 136 */ 137 MHD_INTERNAL bool 138 mhd_stream_get_request_headers (struct MHD_Connection *restrict c, 139 bool process_footers) 140 MHD_FN_PAR_NONNULL_ALL_; 141 142 /** 143 * Parse the various request headers; figure out the size of the upload and 144 * make sure the headers follow the protocol. 145 * Advance to the appropriate state. 146 * 147 * @param c the connection to process 148 */ 149 MHD_INTERNAL void 150 mhd_stream_parse_request_headers (struct MHD_Connection *restrict c) 151 MHD_FN_PAR_NONNULL_ALL_; 152 153 /** 154 * Call application request handling callback, process action given by app. 155 * Advance to the next state when done, handle errors. 156 * @param c the connection to process 157 * @return true if advanced to the next state and the next state could 158 * be processes right now, 159 * false if connection is suspended or aborted or more data needed 160 * to process the next state 161 */ 162 MHD_INTERNAL bool 163 mhd_stream_call_app_request_cb (struct MHD_Connection *restrict c) 164 MHD_FN_PAR_NONNULL_ALL_; 165 166 167 /** 168 * React on provided action for upload 169 * @param c the stream to use 170 * @param act the action provided by application 171 * @param final set to 'true' if this is final upload callback 172 * @return true if connection state has been changed, 173 * false otherwise 174 */ 175 MHD_INTERNAL bool 176 mhd_stream_process_upload_action (struct MHD_Connection *restrict c, 177 const struct MHD_UploadAction *act, 178 bool final) 179 MHD_FN_PAR_NONNULL_ (1); 180 181 /** 182 * Process non-chunked request body or upload chunking encoding. 183 * Call the upload handler of the application. 184 * Advance to the next state when done, handle errors. 185 * 186 * @param c the connection to process 187 * @return true if advanced to the next state, 188 * false if more data needed or connection is suspended 189 */ 190 MHD_INTERNAL bool 191 mhd_stream_process_request_body (struct MHD_Connection *restrict c) 192 MHD_FN_PAR_NONNULL_ALL_; 193 194 /** 195 * Call application final upload callback, process action given by app. 196 * Advance to the next state, handle errors. 197 * @param c the connection to process 198 * @return true if advanced to the next state, 199 * false if connection is suspended 200 */ 201 MHD_INTERNAL bool 202 mhd_stream_call_app_final_upload_cb (struct MHD_Connection *restrict c) 203 MHD_FN_PAR_NONNULL_ALL_; 204 205 /** 206 * Process finalisation of request receiving. 207 * Advance to the next state, handle errors. 208 * @param c the connection to process 209 * @return true if advanced to the next state, 210 * false if connection is suspended 211 */ 212 MHD_INTERNAL bool 213 mhd_stream_process_req_recv_finished (struct MHD_Connection *restrict c) 214 MHD_FN_PAR_NONNULL_ALL_; 215 216 /** 217 * Result of the connection buffer growing 218 */ 219 enum mhd_ConnectionBufferGrowResult 220 { 221 /** 222 * No error 223 */ 224 mhd_CONN_BUFF_GROW_OK = 0u, 225 /** 226 * Failed to grow buffer, the connection is closing 227 */ 228 mhd_CONN_BUFF_GROW_ERR_CONN_CLOSE, 229 /** 230 * Failed to grow buffer, the error reply is pending 231 */ 232 mhd_CONN_BUFF_GROW_ERR_REPLY 233 }; 234 235 /** 236 * Check whether enough space is available in the read buffer for the next 237 * operation. 238 * Handles grow of the buffer if required and error conditions (when buffer 239 * grow is required but not possible). 240 * Must be called only when processing the event loop states and when 241 * reading is required for the next phase. 242 * @param c the connection to check 243 * @return #mhd_CONN_BUFF_GROW_OK if connection handled successfully and 244 * enough buffer is available, 245 * error code otherwise. 246 */ 247 MHD_INTERNAL enum mhd_ConnectionBufferGrowResult 248 mhd_stream_check_and_grow_read_buffer_space (struct MHD_Connection *restrict c) 249 MHD_FN_PAR_NONNULL_ALL_; 250 251 #endif /* ! MHD_STREAM_PROCESS_REQUEST_H */