mhd_action.h (9309B)
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_INOUT_SIZE_ (4,3) 119 *MHD_UploadCallback)(void *upload_cls, 120 struct MHD_Request *request, 121 size_t content_data_size, 122 void *content_data); 123 124 #define MHD_UPLOADCALLBACK_DEFINED 1 125 #endif /* ! MHD_UPLOADCALLBACK_DEFINED */ 126 127 /** 128 * Upload callback data 129 */ 130 struct mhd_UploadCallbackData 131 { 132 /** 133 * The callback 134 */ 135 MHD_UploadCallback cb; 136 137 /** 138 * The closure for @a cb 139 */ 140 void *cls; 141 }; 142 143 /** 144 * The data for upload callbacks 145 */ 146 struct mhd_UploadCallbacks 147 { 148 /** 149 * The size of the buffer for the @a full upload callback 150 */ 151 size_t large_buffer_size; 152 153 /** 154 * The data for the callback that processes only complete upload 155 */ 156 struct mhd_UploadCallbackData full; 157 158 /** 159 * The data for the callback that processes only incremental uploads 160 */ 161 struct mhd_UploadCallbackData inc; 162 }; 163 164 #ifdef MHD_SUPPORT_POST_PARSER 165 #ifndef MHD_POST_DATA_READER_DEFINED 166 167 typedef const struct MHD_UploadAction * 168 (MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_ (3) MHD_FN_PAR_NONNULL_ (4) 169 MHD_FN_PAR_NONNULL_ (5) MHD_FN_PAR_NONNULL_ (6) 170 *MHD_PostDataReader) (struct MHD_Request *req, 171 void *cls, 172 const struct MHD_String *name, 173 const struct MHD_StringNullable *filename, 174 const struct MHD_StringNullable *content_type, 175 const struct MHD_StringNullable *encoding, 176 size_t size, 177 const void *data, 178 uint_fast64_t off, 179 enum MHD_Bool final_data); 180 181 typedef const struct MHD_UploadAction * 182 (MHD_FN_PAR_NONNULL_ (1) 183 *MHD_PostDataFinished) (struct MHD_Request *req, 184 void *cls, 185 enum MHD_PostParseResult parsing_result); 186 187 #define MHD_POST_DATA_READER_DEFINED 1 188 #endif /* ! MHD_POST_DATA_READER_DEFINED */ 189 190 191 /** 192 * The data for performing POST action 193 */ 194 struct mhd_PostParseActionData 195 { 196 /** 197 * The maximum size allowed for the buffers to parse the POST data. 198 */ 199 size_t buffer_size; 200 /** 201 * The size of the field (in encoded form) above which values are not 202 * buffered and incrementally "streamed" 203 */ 204 size_t max_nonstream_size; 205 /** 206 * The data encoding to use, 207 * #MHD_HTTP_POST_ENCODING_OTHER indicates automatic detection 208 */ 209 enum MHD_HTTP_PostEncoding enc; 210 /** 211 * The callback function which process values in "streaming" way. 212 * Can be NULL. 213 */ 214 MHD_PostDataReader stream_reader; 215 /** 216 * The closure for the @a stream_reader 217 */ 218 void *reader_cls; 219 /** 220 * The "final" callback, called after all POST data has been parsed. 221 */ 222 MHD_PostDataFinished done_cb; 223 /** 224 * The closure for the @a done_cb 225 */ 226 void *done_cb_cls; 227 }; 228 229 #endif /* MHD_SUPPORT_POST_PARSER */ 230 231 232 #ifdef MHD_SUPPORT_UPGRADE 233 234 struct MHD_UpgradedHandle; /* forward declaration */ 235 236 #ifndef MHD_UPGRADEHANDLER_DEFINED 237 238 typedef void 239 (*MHD_UpgradeHandler)(void *cls, 240 struct MHD_Request *MHD_RESTRICT request, 241 struct MHD_UpgradedHandle *MHD_RESTRICT urh); 242 243 #define MHD_UPGRADEHANDLER_DEFINED 1 244 #endif /* ! MHD_UPGRADEHANDLER_DEFINED */ 245 246 247 /** 248 * The data for "Upgrade" action 249 */ 250 struct mhd_UpgradeActionData 251 { 252 /** 253 * The "upgrade" handler callback 254 */ 255 MHD_UpgradeHandler cb; 256 257 /** 258 * The closure for the @a cb callback 259 */ 260 void *cb_cls; 261 }; 262 263 #endif /* MHD_SUPPORT_UPGRADE */ 264 265 266 /** 267 * The data for the application action 268 */ 269 union mhd_ActionData 270 { 271 /** 272 * The data for the action #mhd_ACTION_RESPONSE 273 */ 274 struct MHD_Response *response; 275 276 /** 277 * The data for the action #mhd_ACTION_UPLOAD 278 */ 279 struct mhd_UploadCallbacks upload; 280 281 #ifdef MHD_SUPPORT_POST_PARSER 282 /** 283 * The data for the action #mhd_ACTION_POST_PARSE 284 */ 285 struct mhd_PostParseActionData post_parse; 286 #endif /* MHD_SUPPORT_POST_PARSER */ 287 #ifdef MHD_SUPPORT_UPGRADE 288 /** 289 * The data for "Upgrade" action 290 */ 291 struct mhd_UpgradeActionData upgrd; 292 #endif /* MHD_SUPPORT_UPGRADE */ 293 }; 294 295 296 /** 297 * The action provided after reporting all headers to application 298 */ 299 struct MHD_Action 300 { 301 /** 302 * The action 303 */ 304 enum mhd_ActionType act; 305 306 /** 307 * The data for the @a act action 308 */ 309 union mhd_ActionData data; 310 }; 311 312 /** 313 * The type of the action requested by application 314 */ 315 enum mhd_UploadActionType 316 { 317 /** 318 * Action has not been set yet. 319 */ 320 mhd_UPLOAD_ACTION_NO_ACTION = 0 321 , 322 /** 323 * Continue processing the upload 324 */ 325 mhd_UPLOAD_ACTION_CONTINUE 326 , 327 /** 328 * Start replying with the response 329 */ 330 mhd_UPLOAD_ACTION_RESPONSE 331 , 332 /** 333 * Suspend requests (connection) 334 */ 335 mhd_UPLOAD_ACTION_SUSPEND 336 #ifdef MHD_SUPPORT_UPGRADE 337 , 338 /** 339 * Perform HTTP "upgrade" 340 */ 341 mhd_UPLOAD_ACTION_UPGRADE 342 #endif /* MHD_SUPPORT_UPGRADE */ 343 , 344 /** 345 * Hard close request with no response 346 */ 347 mhd_UPLOAD_ACTION_ABORT 348 }; 349 350 /** 351 * Check whether provided mhd_UploadActionType value is valid 352 */ 353 #define mhd_UPLOAD_ACTION_IS_VALID(act) \ 354 ((mhd_UPLOAD_ACTION_CONTINUE <= (act)) && \ 355 (mhd_UPLOAD_ACTION_ABORT >= (act))) 356 357 358 /** 359 * The data for the application action 360 */ 361 union mhd_UploadActionData 362 { 363 /** 364 * The data for the action #mhd_ACTION_RESPONSE 365 */ 366 struct MHD_Response *response; 367 #ifdef MHD_SUPPORT_UPGRADE 368 /** 369 * The data for "Upgrade" action 370 */ 371 struct mhd_UpgradeActionData upgrd; 372 #endif /* MHD_SUPPORT_UPGRADE */ 373 }; 374 375 /** 376 * The action provided when consuming client's upload 377 */ 378 struct MHD_UploadAction 379 { 380 /** 381 * The action 382 */ 383 enum mhd_UploadActionType act; 384 385 /** 386 * The data for the @a act action 387 */ 388 union mhd_UploadActionData data; 389 }; 390 391 392 /** 393 * The action set by the application 394 */ 395 struct mhd_ApplicationAction 396 { 397 /** 398 * The action after header reporting 399 */ 400 struct MHD_Action head_act; 401 /** 402 * The action during upload processing 403 */ 404 struct MHD_UploadAction upl_act; 405 }; 406 407 408 #endif /* ! MHD_ACTION_H */