libmicrohttpd2

HTTP server C library (MHD 2.x, alpha)
Log | Files | Refs | README | LICENSE

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 */