h2_req_items_funcs.h (8697B)
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) 2025 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/h2/h2_req_items_funcs.h 41 * @brief Declarations of the request items (headers, URI params) functions 42 * @author Karlson2k (Evgeny Grin) 43 */ 44 45 #ifndef MHD_H2_REQ_ITEMS_FUNCS_H 46 #define MHD_H2_REQ_ITEMS_FUNCS_H 1 47 48 #include "mhd_sys_options.h" 49 50 #include "sys_base_types.h" 51 #include "sys_bool_type.h" 52 53 #include "h2_req_item_kinds.h" 54 55 struct mhd_H2ReqItem; /* Forward declaration */ 56 struct mhd_H2ReqItemsBlock; /* Forward declaration */ 57 struct mhd_Buffer; /* Forward declaration */ 58 struct MHD_String; /* Forward declaration */ 59 60 61 MHD_INTERNAL void 62 mhd_h2_items_block_destroy (struct mhd_H2ReqItemsBlock *ib) 63 MHD_FN_PAR_NONNULL_ALL_; 64 65 /** 66 * Create request items block 67 * @param buffer_size the minimal size of the items block, 68 * must be less than UINT32_MAX minus 32, the real space 69 * in the allocated block could be rounded up 70 * @return the pointer to the new request items block if succeed, 71 * NULL if failed (out of memory, too large @p buffer_size) 72 */ 73 MHD_INTERNAL struct mhd_H2ReqItemsBlock * 74 mhd_h2_items_block_create (size_t buffer_size) 75 mhd_FN_RET_UNALIASED mhd_FN_OBJ_CONSTRUCTOR (mhd_h2_items_block_destroy); 76 77 78 /** 79 * Reset request items block 80 * @param ib the pointer to the previously initialised items block to reset 81 */ 82 MHD_INTERNAL void 83 mhd_h2_items_block_reset (struct mhd_H2ReqItemsBlock *restrict ib) 84 MHD_FN_PAR_INOUT_ (1) MHD_FN_PAR_NONNULL_ALL_; 85 86 /** 87 * Allocates the buffer space for a new item. 88 * 89 * This function gives all available buffer space, excluding space for the 90 * new item header. 91 * 92 * It must be finally followed by a single call of one of the 93 * #mhd_h2_items_add_new_item_buff() or #mhd_h2_items_cancel_new_item_buff(). 94 * @param ib the pointer to items block data 95 * @param[out] buff set to the available space in the buffer 96 * @return 'true' if succeed, 97 * 'false' if no space for a new item is available 98 */ 99 MHD_INTERNAL bool 100 mhd_h2_items_get_buff_new_item (struct mhd_H2ReqItemsBlock *restrict ib, 101 struct mhd_Buffer *restrict buff) 102 MHD_FN_PAR_INOUT_ (1) MHD_FN_PAR_OUT_ (2) MHD_FN_PAR_NONNULL_ALL_; 103 104 /** 105 * Allocates the buffer space for a new item header, assuming that strings 106 * will be placed over other allocated and then reduced item. 107 * 108 * It must be finally followed by a single call of one of the 109 * #mhd_h2_mhd_h2_items_add_new_item_reserved() or 110 * #mhd_h2_items_cancel_new_item_buff(). 111 * @param ib the pointer to items block data 112 * @return 'true' if succeed, 113 * 'false' if no space for a new item is available 114 */ 115 MHD_INTERNAL bool 116 mhd_h2_items_reserve_new_item (struct mhd_H2ReqItemsBlock *restrict ib) 117 MHD_FN_PAR_INOUT_ (1) MHD_FN_PAR_NONNULL_ALL_; 118 119 /** 120 * Add a new item to the items block based on previously allocated space 121 * 122 * The new item must be located at the start of the buffer which must be 123 * previously allocated by calling #mhd_h2_items_get_new_item_buff() function. 124 * 125 * The name string must be at zero position and must be zero-terminated. 126 * The value string must start immediately after zero-termination of the name 127 * string and must be zero-terminated too (the form is "name\0value\0"). 128 * 129 * The strings must fit the buffer. 130 * @param ib the pointer to items block data 131 * @param name_len the length of the name string, not including mandatory 132 * zero termination 133 * @param val_len the length of the value string, not including mandatory 134 * zero termination 135 */ 136 MHD_INTERNAL void 137 mhd_h2_items_add_new_item_buff (struct mhd_H2ReqItemsBlock *restrict ib, 138 size_t name_len, 139 size_t val_len, 140 enum mhd_H2RequestItemKind kind) 141 MHD_FN_PAR_INOUT_ (1) MHD_FN_PAR_NONNULL_ALL_; 142 143 MHD_INTERNAL void 144 mhd_h2_items_add_new_item_reserved (struct mhd_H2ReqItemsBlock *restrict ib, 145 size_t name_start, 146 size_t name_len, 147 size_t val_len, 148 enum mhd_H2RequestItemKind kind) 149 MHD_FN_PAR_INOUT_ (1) MHD_FN_PAR_NONNULL_ALL_; 150 151 152 #ifndef NDEBUG 153 MHD_INTERNAL void 154 mhd_h2_items_cancel_new_item_buff (struct mhd_H2ReqItemsBlock *restrict ib) 155 MHD_FN_PAR_INOUT_ (1) MHD_FN_PAR_NONNULL_ALL_; 156 157 #else /* NDEBUG */ 158 # define mhd_h2_items_cancel_new_item_buff(ib) ((void) 0) /* do nothing */ 159 #endif /* NDEBUG */ 160 161 MHD_INTERNAL char * 162 mhd_h2_items_get_strings_buff (struct mhd_H2ReqItemsBlock *restrict ib) 163 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_RETURNS_NONNULL_ MHD_FN_PURE_; 164 165 MHD_INTERNAL const char * 166 mhd_h2_items_get_strings_buffc (const struct mhd_H2ReqItemsBlock *restrict ib) 167 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_RETURNS_NONNULL_ MHD_FN_PURE_; 168 169 /* return NULL if 'pos' does not exist */ 170 MHD_INTERNAL struct mhd_H2ReqItem * 171 mhd_h2_items_get_item_n (struct mhd_H2ReqItemsBlock *restrict ib, 172 size_t pos) 173 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PURE_; 174 175 /* return NULL if 'pos' does not exist */ 176 MHD_INTERNAL const struct mhd_H2ReqItem * 177 mhd_h2_items_get_item_nc (const struct mhd_H2ReqItemsBlock *restrict ib, 178 size_t pos) 179 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PURE_; 180 181 MHD_INTERNAL bool 182 mhd_h2_items_get_item_name (struct mhd_H2ReqItemsBlock *restrict ib, 183 size_t pos, 184 struct MHD_String *restrict name) 185 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 186 187 MHD_INTERNAL bool 188 mhd_h2_items_get_item_value (struct mhd_H2ReqItemsBlock *restrict ib, 189 size_t pos, 190 struct MHD_String *restrict value) 191 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 192 193 MHD_INTERNAL bool 194 mhd_h2_items_get_item_kind (struct mhd_H2ReqItemsBlock *restrict ib, 195 size_t pos, 196 enum mhd_H2RequestItemKind *restrict kind) 197 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (3); 198 199 MHD_INTERNAL bool 200 mhd_h2_items_get_item_full (struct mhd_H2ReqItemsBlock *restrict ib, 201 size_t pos, 202 struct MHD_String *restrict name, 203 struct MHD_String *restrict value, 204 enum mhd_H2RequestItemKind *restrict kind) 205 MHD_FN_PAR_NONNULL_ALL_ 206 MHD_FN_PAR_OUT_ (3) MHD_FN_PAR_OUT_ (4) MHD_FN_PAR_OUT_ (5); 207 208 #ifndef NDEBUG 209 MHD_INTERNAL void 210 mhd_h2_items_debug_set_streamid (struct mhd_H2ReqItemsBlock *restrict ib, 211 uint_least32_t stream_id) 212 MHD_FN_PAR_NONNULL_ALL_; 213 214 MHD_INTERNAL uint_least32_t 215 mhd_h2_items_debug_get_streamid (struct mhd_H2ReqItemsBlock *restrict ib) 216 MHD_FN_PAR_NONNULL_ALL_; 217 218 #else /* NDEBUG */ 219 # define mhd_h2_items_debug_set_streamid(ib, stream_id) ((void) 0) 220 # define mhd_h2_items_debug_get_streamid(ib) ((void) 0) 221 #endif 222 223 #endif /* ! MHD_H2_REQ_ITEMS_FUNCS_H */