stream_process_request.h (8833B)
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 #include "http_method.h" 60 61 struct MHD_Connection; /* forward declaration */ 62 struct MHD_UploadAction; /* forward declaration */ 63 64 /** 65 * Callback for iterating over GET parameters 66 * @param cls the iterator metadata 67 * @param name the name of the parameter 68 * @param value the value of the parameter 69 * @return bool to continue iterations, 70 * false to stop the iteration 71 */ 72 typedef bool 73 (MHD_FN_PAR_NONNULL_ (2) MHD_FN_PAR_NONNULL_ (3) 74 *mhd_GetArgumentInter)(void *restrict cls, 75 const struct MHD_String *restrict name, 76 const struct MHD_StringNullable *restrict value); 77 78 /** 79 * Parse HTTP method string. 80 * @param len the length of the @a mtd string 81 * @param mtd the method string, does not need to be zero-terminated 82 * @return enum mhd_HTTP_Method value 83 */ 84 MHD_INTERNAL enum mhd_HTTP_Method 85 mhd_parse_http_method (size_t len, 86 const char mtd[MHD_FN_PAR_DYN_ARR_SIZE_ (len)]) 87 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_IN_SIZE_(2,1) MHD_FN_PURE_; 88 89 /** 90 * Parse and unescape the arguments given by the client 91 * as part of the HTTP request URI. 92 * 93 * @param args_len the function to call on each key-value pair found 94 * @param[in,out] args argument URI string (after "?" in URI), 95 * clobbered in the process! 96 * @param cb function to call on each key-value pair found 97 * @param cls the iterator context 98 * @return false on failure 99 * true on success (parsing succeeded, @a cb always returned true) 100 */ 101 MHD_INTERNAL bool 102 mhd_parse_uri_args (size_t args_len, 103 char *restrict args, 104 mhd_GetArgumentInter cb, 105 void *restrict cls) 106 MHD_FN_PAR_NONNULL_ (2) MHD_FN_PAR_CSTR_ (2) MHD_FN_PAR_INOUT_SIZE_ (2, 1); 107 108 109 /** 110 * Find and parse the request line. 111 * @param c the connection to process 112 * @return true if request line completely processed (or unrecoverable error 113 * found) and state is changed, 114 * false if not enough data yet in the receive buffer 115 */ 116 MHD_INTERNAL bool 117 mhd_stream_get_request_line (struct MHD_Connection *restrict c) 118 MHD_FN_PAR_NONNULL_ALL_; 119 120 /** 121 * Switch to request headers (field lines) processing state. 122 * @param c the connection to process 123 */ 124 MHD_INTERNAL void 125 mhd_stream_switch_to_rq_headers_proc (struct MHD_Connection *restrict c) 126 MHD_FN_PAR_NONNULL_ALL_; 127 128 /** 129 * Reset request header processing state. 130 * 131 * This function resets the processing state before processing the header 132 * (or footer) line. 133 * @param c the connection to process 134 */ 135 MHD_INTERNAL void 136 mhd_stream_reset_rq_hdr_proc_state (struct MHD_Connection *c) 137 MHD_FN_PAR_NONNULL_ALL_; 138 139 /** 140 * Find the end of the request GET parameters. 141 * Advance to the next state when done, handle errors. 142 * @param c the connection to process 143 * @param process_footers if true then footers are processed, 144 * if false then headers are processed 145 * @return true if request headers reading finished (either successfully 146 * or with error), 147 * false if not enough data yet in the receive buffer 148 */ 149 MHD_INTERNAL bool 150 mhd_stream_get_request_headers (struct MHD_Connection *restrict c, 151 bool process_footers) 152 MHD_FN_PAR_NONNULL_ALL_; 153 154 /** 155 * Parse the various request headers; figure out the size of the upload and 156 * make sure the headers follow the protocol. 157 * Advance to the appropriate state. 158 * 159 * @param c the connection to process 160 */ 161 MHD_INTERNAL void 162 mhd_stream_parse_request_headers (struct MHD_Connection *restrict c) 163 MHD_FN_PAR_NONNULL_ALL_; 164 165 /** 166 * Call application request handling callback, process action given by app. 167 * Advance to the next state when done, handle errors. 168 * @param c the connection to process 169 * @return true if advanced to the next state and the next state could 170 * be processes right now, 171 * false if connection is suspended or aborted or more data needed 172 * to process the next state 173 */ 174 MHD_INTERNAL bool 175 mhd_stream_call_app_request_cb (struct MHD_Connection *restrict c) 176 MHD_FN_PAR_NONNULL_ALL_; 177 178 179 /** 180 * React on provided action for upload 181 * @param c the stream to use 182 * @param act the action provided by application 183 * @param final set to 'true' if this is final upload callback 184 * @return true if connection state has been changed, 185 * false otherwise 186 */ 187 MHD_INTERNAL bool 188 mhd_stream_process_upload_action (struct MHD_Connection *restrict c, 189 const struct MHD_UploadAction *act, 190 bool final) 191 MHD_FN_PAR_NONNULL_ (1); 192 193 /** 194 * Process non-chunked request body or upload chunking encoding. 195 * Call the upload handler of the application. 196 * Advance to the next state when done, handle errors. 197 * 198 * @param c the connection to process 199 * @return true if advanced to the next state, 200 * false if more data needed or connection is suspended 201 */ 202 MHD_INTERNAL bool 203 mhd_stream_process_request_body (struct MHD_Connection *restrict c) 204 MHD_FN_PAR_NONNULL_ALL_; 205 206 /** 207 * Call application final upload callback, process action given by app. 208 * Advance to the next state, handle errors. 209 * @param c the connection to process 210 * @return true if advanced to the next state, 211 * false if connection is suspended 212 */ 213 MHD_INTERNAL bool 214 mhd_stream_call_app_final_upload_cb (struct MHD_Connection *restrict c) 215 MHD_FN_PAR_NONNULL_ALL_; 216 217 /** 218 * Process finalisation of request receiving. 219 * Advance to the next state, handle errors. 220 * @param c the connection to process 221 * @return true if advanced to the next state, 222 * false if connection is suspended 223 */ 224 MHD_INTERNAL bool 225 mhd_stream_process_req_recv_finished (struct MHD_Connection *restrict c) 226 MHD_FN_PAR_NONNULL_ALL_; 227 228 /** 229 * Check whether enough space is available in the read buffer for the next 230 * operation. 231 * Handles grow of the buffer if required and error conditions (when buffer 232 * grow is required but not possible). 233 * Must be called only when processing the event loop states and when 234 * reading is required for the next phase. 235 * @param c the connection to check 236 * @return true if connection handled successfully and enough buffer 237 * is available, 238 * false if not enough buffer is available and the loop's states 239 * must be processed again as connection is in the error state. 240 */ 241 MHD_INTERNAL bool 242 mhd_stream_check_and_grow_read_buffer_space (struct MHD_Connection *restrict c) 243 MHD_FN_PAR_NONNULL_ALL_; 244 245 #endif /* ! MHD_STREAM_PROCESS_REQUEST_H */