mhd_action.h (9367B)
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) 2024 Evgeny Grin (Karlson2k) 5 6 GNU libmicrohttpd is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Lesser General Public 8 License as published by the Free Software Foundation; either 9 version 2.1 of the License, or (at your option) any later version. 10 11 GNU libmicrohttpd is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Lesser General Public License for more details. 15 16 Alternatively, you can redistribute GNU libmicrohttpd and/or 17 modify it under the terms of the GNU General Public License as 18 published by the Free Software Foundation; either version 2 of 19 the License, or (at your option) any later version, together 20 with the eCos exception, as follows: 21 22 As a special exception, if other files instantiate templates or 23 use macros or inline functions from this file, or you compile this 24 file and link it with other works to produce a work based on this 25 file, this file does not by itself cause the resulting work to be 26 covered by the GNU General Public License. However the source code 27 for this file must still be made available in accordance with 28 section (3) of the GNU General Public License v2. 29 30 This exception does not invalidate any other reasons why a work 31 based on this file might be covered by the GNU General Public 32 License. 33 34 You should have received copies of the GNU Lesser General Public 35 License and the GNU General Public License along with this library; 36 if not, see <https://www.gnu.org/licenses/>. 37 */ 38 39 /** 40 * @file src/mhd2/mhd_action.h 41 * @brief The definition of the MHD_Action and MHD_UploadAction structures 42 * @author Karlson2k (Evgeny Grin) 43 */ 44 45 #ifndef MHD_ACTION_H 46 #define MHD_ACTION_H 1 47 48 #include "mhd_sys_options.h" 49 50 #include "sys_base_types.h" 51 52 #include "mhd_str_types.h" 53 54 #ifdef MHD_SUPPORT_POST_PARSER 55 # include "http_post_enc.h" 56 # include "mhd_bool.h" 57 # include "mhd_post_result.h" 58 #endif 59 60 struct MHD_Response; /* forward declaration */ 61 struct MHD_Request; /* forward declaration */ 62 63 /** 64 * The type of the action requested by application 65 */ 66 enum mhd_ActionType 67 { 68 /** 69 * Action has not been set yet. 70 */ 71 mhd_ACTION_NO_ACTION = 0 72 , 73 /** 74 * Start replying with the response 75 */ 76 mhd_ACTION_RESPONSE 77 , 78 /** 79 * Process clients upload by application callback 80 */ 81 mhd_ACTION_UPLOAD 82 #ifdef MHD_SUPPORT_POST_PARSER 83 , 84 /** 85 * Process POST data clients upload by POST parser 86 */ 87 mhd_ACTION_POST_PARSE 88 #endif /* MHD_SUPPORT_POST_PARSER */ 89 , 90 /** 91 * Suspend requests (connection) 92 */ 93 mhd_ACTION_SUSPEND 94 #ifdef MHD_SUPPORT_UPGRADE 95 , 96 /** 97 * Perform HTTP "upgrade" 98 */ 99 mhd_ACTION_UPGRADE 100 #endif /* MHD_SUPPORT_UPGRADE */ 101 , 102 /** 103 * Hard close request with no response 104 */ 105 mhd_ACTION_ABORT 106 }; 107 108 /** 109 * Check whether provided mhd_ActionType value is valid 110 */ 111 #define mhd_ACTION_IS_VALID(act) \ 112 ((mhd_ACTION_RESPONSE <= (act)) && (mhd_ACTION_ABORT >= (act))) 113 114 115 #ifndef MHD_UPLOADCALLBACK_DEFINED 116 117 typedef const struct MHD_UploadAction * 118 (MHD_FN_PAR_NONNULL_ (2) MHD_FN_PAR_NONNULL_IF_NONZERO_ (4, 3) 119 MHD_FN_PAR_INOUT_SIZE_ (4, 3) 120 *MHD_UploadCallback)(void *upload_cls, 121 struct MHD_Request *request, 122 size_t content_data_size, 123 void *content_data); 124 125 # define MHD_UPLOADCALLBACK_DEFINED 1 126 #endif /* ! MHD_UPLOADCALLBACK_DEFINED */ 127 128 /** 129 * Upload callback data 130 */ 131 struct mhd_UploadCallbackData 132 { 133 /** 134 * The callback 135 */ 136 MHD_UploadCallback cb; 137 138 /** 139 * The closure for @a cb 140 */ 141 void *cls; 142 }; 143 144 /** 145 * The data for upload callbacks 146 */ 147 struct mhd_UploadCallbacks 148 { 149 /** 150 * The size of the buffer for the @a full upload callback 151 */ 152 size_t large_buffer_size; 153 154 /** 155 * The data for the callback that processes only complete upload 156 */ 157 struct mhd_UploadCallbackData full; 158 159 /** 160 * The data for the callback that processes only incremental uploads 161 */ 162 struct mhd_UploadCallbackData inc; 163 }; 164 165 #ifdef MHD_SUPPORT_POST_PARSER 166 # ifndef MHD_POST_DATA_READER_DEFINED 167 168 typedef const struct MHD_UploadAction * 169 (MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_ (3) MHD_FN_PAR_NONNULL_ (4) 170 MHD_FN_PAR_NONNULL_ (5) MHD_FN_PAR_NONNULL_ (6) 171 *MHD_PostDataReader) (struct MHD_Request *req, 172 void *cls, 173 const struct MHD_String *name, 174 const struct MHD_StringNullable *filename, 175 const struct MHD_StringNullable *content_type, 176 const struct MHD_StringNullable *encoding, 177 size_t size, 178 const void *data, 179 uint_fast64_t off, 180 enum MHD_Bool final_data); 181 182 typedef const struct MHD_UploadAction * 183 (MHD_FN_PAR_NONNULL_ (1) 184 *MHD_PostDataFinished) (struct MHD_Request *req, 185 void *cls, 186 enum MHD_PostParseResult parsing_result); 187 188 # define MHD_POST_DATA_READER_DEFINED 1 189 # endif /* ! MHD_POST_DATA_READER_DEFINED */ 190 191 192 /** 193 * The data for performing POST action 194 */ 195 struct mhd_PostParseActionData 196 { 197 /** 198 * The maximum size allowed for the buffers to parse the POST data. 199 */ 200 size_t buffer_size; 201 /** 202 * The size of the field (in encoded form) above which values are not 203 * buffered and incrementally "streamed" 204 */ 205 size_t max_nonstream_size; 206 /** 207 * The data encoding to use, 208 * #MHD_HTTP_POST_ENCODING_OTHER indicates automatic detection 209 */ 210 enum MHD_HTTP_PostEncoding enc; 211 /** 212 * The callback function which process values in "streaming" way. 213 * Can be NULL. 214 */ 215 MHD_PostDataReader stream_reader; 216 /** 217 * The closure for the @a stream_reader 218 */ 219 void *reader_cls; 220 /** 221 * The "final" callback, called after all POST data has been parsed. 222 */ 223 MHD_PostDataFinished done_cb; 224 /** 225 * The closure for the @a done_cb 226 */ 227 void *done_cb_cls; 228 }; 229 230 #endif /* MHD_SUPPORT_POST_PARSER */ 231 232 233 #ifdef MHD_SUPPORT_UPGRADE 234 235 struct MHD_UpgradedHandle; /* forward declaration */ 236 237 # ifndef MHD_UPGRADEHANDLER_DEFINED 238 239 typedef void 240 (*MHD_UpgradeHandler)(void *cls, 241 struct MHD_Request *MHD_RESTRICT request, 242 struct MHD_UpgradedHandle *MHD_RESTRICT urh); 243 244 # define MHD_UPGRADEHANDLER_DEFINED 1 245 # endif /* ! MHD_UPGRADEHANDLER_DEFINED */ 246 247 248 /** 249 * The data for "Upgrade" action 250 */ 251 struct mhd_UpgradeActionData 252 { 253 /** 254 * The "upgrade" handler callback 255 */ 256 MHD_UpgradeHandler cb; 257 258 /** 259 * The closure for the @a cb callback 260 */ 261 void *cb_cls; 262 }; 263 264 #endif /* MHD_SUPPORT_UPGRADE */ 265 266 267 /** 268 * The data for the application action 269 */ 270 union mhd_ActionData 271 { 272 /** 273 * The data for the action #mhd_ACTION_RESPONSE 274 */ 275 struct MHD_Response *response; 276 277 /** 278 * The data for the action #mhd_ACTION_UPLOAD 279 */ 280 struct mhd_UploadCallbacks upload; 281 282 #ifdef MHD_SUPPORT_POST_PARSER 283 /** 284 * The data for the action #mhd_ACTION_POST_PARSE 285 */ 286 struct mhd_PostParseActionData post_parse; 287 #endif /* MHD_SUPPORT_POST_PARSER */ 288 #ifdef MHD_SUPPORT_UPGRADE 289 /** 290 * The data for "Upgrade" action 291 */ 292 struct mhd_UpgradeActionData upgrd; 293 #endif /* MHD_SUPPORT_UPGRADE */ 294 }; 295 296 297 /** 298 * The action provided after reporting all headers to application 299 */ 300 struct MHD_Action 301 { 302 /** 303 * The action 304 */ 305 enum mhd_ActionType act; 306 307 /** 308 * The data for the @a act action 309 */ 310 union mhd_ActionData data; 311 }; 312 313 /** 314 * The type of the action requested by application 315 */ 316 enum mhd_UploadActionType 317 { 318 /** 319 * Action has not been set yet. 320 */ 321 mhd_UPLOAD_ACTION_NO_ACTION = 0 322 , 323 /** 324 * Continue processing the upload 325 */ 326 mhd_UPLOAD_ACTION_CONTINUE 327 , 328 /** 329 * Start replying with the response 330 */ 331 mhd_UPLOAD_ACTION_RESPONSE 332 , 333 /** 334 * Suspend requests (connection) 335 */ 336 mhd_UPLOAD_ACTION_SUSPEND 337 #ifdef MHD_SUPPORT_UPGRADE 338 , 339 /** 340 * Perform HTTP "upgrade" 341 */ 342 mhd_UPLOAD_ACTION_UPGRADE 343 #endif /* MHD_SUPPORT_UPGRADE */ 344 , 345 /** 346 * Hard close request with no response 347 */ 348 mhd_UPLOAD_ACTION_ABORT 349 }; 350 351 /** 352 * Check whether provided mhd_UploadActionType value is valid 353 */ 354 #define mhd_UPLOAD_ACTION_IS_VALID(act) \ 355 ((mhd_UPLOAD_ACTION_CONTINUE <= (act)) && \ 356 (mhd_UPLOAD_ACTION_ABORT >= (act))) 357 358 359 /** 360 * The data for the application action 361 */ 362 union mhd_UploadActionData 363 { 364 /** 365 * The data for the action #mhd_ACTION_RESPONSE 366 */ 367 struct MHD_Response *response; 368 #ifdef MHD_SUPPORT_UPGRADE 369 /** 370 * The data for "Upgrade" action 371 */ 372 struct mhd_UpgradeActionData upgrd; 373 #endif /* MHD_SUPPORT_UPGRADE */ 374 }; 375 376 /** 377 * The action provided when consuming client's upload 378 */ 379 struct MHD_UploadAction 380 { 381 /** 382 * The action 383 */ 384 enum mhd_UploadActionType act; 385 386 /** 387 * The data for the @a act action 388 */ 389 union mhd_UploadActionData data; 390 }; 391 392 393 /** 394 * The action set by the application 395 */ 396 struct mhd_ApplicationAction 397 { 398 /** 399 * The action after header reporting 400 */ 401 struct MHD_Action head_act; 402 /** 403 * The action during upload processing 404 */ 405 struct MHD_UploadAction upl_act; 406 }; 407 408 409 #endif /* ! MHD_ACTION_H */