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