h2_proc_out.h (8865B)
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_proc_out.h 41 * @brief Declarations of HTTP/2 connection outgoing data processing functions 42 * @author Karlson2k (Evgeny Grin) 43 */ 44 45 #ifndef MHD_H2_PROC_OUT_H 46 #define MHD_H2_PROC_OUT_H 1 47 48 #include "mhd_sys_options.h" 49 50 #include "sys_bool_type.h" 51 #include "sys_base_types.h" 52 53 #include "h2_err_codes.h" 54 55 struct MHD_Connection; /* forward declaration */ 56 struct mhd_Buffer; /* forward declaration */ 57 union mhd_H2FrameUnion; /* forward declaration */ 58 59 /** 60 * Check whether the output buffer has at least specified free space. 61 * @param c the connection to check 62 * @param space_needed the amount of free space needed 63 * @return 'true' if output buffer has enough space, 64 * 'false' otherwise 65 */ 66 MHD_INTERNAL bool 67 mhd_h2_out_buff_has_space_sz (struct MHD_Connection *restrict c, 68 size_t space_needed) 69 MHD_FN_PAR_NONNULL_ALL_; 70 71 /** 72 * Check whether the output buffer has enough space to add the frame (together 73 * with optional payload). 74 * @param c the connection to check 75 * @param h2frame the frame to use, the 'type', all flags and the 'length' 76 * must be set 77 * @return 'true' if output buffer has enough space, 78 * 'false' otherwise 79 */ 80 MHD_INTERNAL bool 81 mhd_h2_out_buff_has_space_fr (struct MHD_Connection *restrict c, 82 union mhd_H2FrameUnion *restrict h2frame) 83 MHD_FN_PAR_NONNULL_ALL_; 84 85 86 /** 87 * Acquire the output buffer for specified frame with undefined payload size. 88 * 89 * The @a h2frame must have all information set except the length of the frame. 90 * The provided @a buff is not larger than maximum frame size allowed for 91 * connection. If @a h2frame has padding, then the size for the padding is 92 * reserved at the end of the @a buff (but not included to the @a buff size). 93 * 94 * In the debug builds this function "locks" the output buffer if succeed. 95 * The caller must always call #mhd_h2_out_buff_unlock() after finishing 96 * working with the buffer even if nothing is written to the buffer. 97 * 98 * @param c the connection to use 99 * @param h2frame the frame to use, the 'type' and all flags must be set, 100 * the 'length' is ignored 101 * @param[out] buff set to the acquired space in the buffer, the size is always 102 * larger than the basic header and the extra header; 103 * the space reserved for the padding is not included 104 * @param[out] payload_offset set to the offset where to put the frame payload 105 * @return 'true' if output buffer has enough space for the frame header and at 106 * least one byte for the payload, 107 * 'false' otherwise 108 */ 109 MHD_INTERNAL bool 110 mhd_h2_out_buff_acquire_fr_w_payload ( 111 struct MHD_Connection *restrict c, 112 const union mhd_H2FrameUnion *restrict h2frame, 113 struct mhd_Buffer *restrict buff, 114 size_t *restrict payload_offset) 115 MHD_FN_PAR_NONNULL_ALL_; 116 117 /** 118 * Acquire the output buffer for specified frame with undefined payload size. 119 * 120 * Version of #mhd_h2_out_buff_acquire_fr_w_payload() with predefined limit 121 * for the frame full payload size. 122 * 123 * @param c the connection to use 124 * @param h2frame the frame to use, the 'type' and all flags must be set, 125 * the 'length' is ignored 126 * @param full_payload_limit the maximum size of the frame (excluding base 127 * frame header) 128 * @param[out] buff set to the acquired space in the buffer, the size is always 129 * larger than the basic header and the extra header; 130 * the space reserved for the padding is not included 131 * @param[out] payload_offset set to the offset where to put the frame payload 132 * @return 'true' if output buffer has enough space for the frame header and at 133 * least one byte for the payload, 134 * 'false' otherwise 135 */ 136 MHD_INTERNAL bool 137 mhd_h2_out_buff_acquire_fr_w_payload_l ( 138 struct MHD_Connection *restrict c, 139 const union mhd_H2FrameUnion *restrict h2frame, 140 uint_least32_t full_payload_limit, 141 struct mhd_Buffer *restrict buff, 142 size_t *restrict payload_offset) 143 MHD_FN_PAR_NONNULL_ALL_; 144 145 146 /** 147 * Finish writing the data to the output buffer. 148 * The output buffer must be previously acquired by calling 149 * #mhd_h2_out_buff_acquire_fr_w_payload(). 150 * @param c the connection to use 151 * @param size_used the size of the frame written; if frame had padding then 152 * it could be larger (by the padding size) than the size of 153 * the buffer provided by #mhd_h2_out_buff_acquire_fr_w_payload() 154 */ 155 MHD_INTERNAL void 156 mhd_h2_out_buff_unlock (struct MHD_Connection *restrict c, 157 size_t size_used) 158 MHD_FN_PAR_NONNULL_ALL_; 159 160 /** 161 * Queue to the sending buffer a frame without payload 162 * @param c the connection to use 163 * @param h2frame the frame to queue 164 * @return 'true' if the frame is successfully added, 165 * 'false' if sending buffer has not enough space 166 */ 167 MHD_INTERNAL bool 168 mhd_h2_q_frame_no_payload (struct MHD_Connection *restrict c, 169 union mhd_H2FrameUnion *restrict h2frame) 170 MHD_FN_PAR_NONNULL_ALL_; 171 172 /** 173 * Queue to the sending buffer a RST_STREAM frame 174 * @param c the connection to use 175 * @param stream_id the stream ID for the frame 176 * @param err the HTTP/2 error code 177 * @return 'true' if the frame is successfully added, 178 * 'false' if sending buffer has not enough space 179 */ 180 MHD_INTERNAL bool 181 mhd_h2_q_rst_stream (struct MHD_Connection *restrict c, 182 uint_least32_t stream_id, 183 enum mhd_H2ErrorCode err) 184 MHD_FN_PAR_NONNULL_ALL_; 185 186 /** 187 * Queue to the sending buffer a PING frame 188 * @param c the connection to use 189 * @param ack the value of the ACK flag in the frame 190 * @param opaque the PING opaque data 191 * @return 'true' if the frame is successfully added, 192 * 'false' if sending buffer has not enough space 193 */ 194 MHD_INTERNAL bool 195 mhd_h2_q_ping (struct MHD_Connection *restrict c, 196 bool ack, 197 const uint8_t opaque[MHD_FN_PAR_FIX_ARR_SIZE_ (8)]) 198 MHD_FN_PAR_NONNULL_ALL_; 199 200 201 /** 202 * Queue to the sending buffer a GOAWAY frame without additional debug info 203 * @param c the connection to use 204 * @param err the HTTP/2 error code 205 * @return 'true' if the frame is successfully added, 206 * 'false' if sending buffer has not enough space 207 */ 208 MHD_INTERNAL bool 209 mhd_h2_q_goaway (struct MHD_Connection *restrict c, 210 enum mhd_H2ErrorCode err) 211 MHD_FN_PAR_NONNULL_ALL_; 212 213 /** 214 * Queue to the sending buffer a WINDOW_UPDATE frame 215 * @param c the connection to use 216 * @param stream_id the stream ID for the frame 217 * @param win_size_incr the Window Size Increment value; 218 * must not be zero, must fit 31 bits 219 * @return 'true' if the frame is successfully added, 220 * 'false' if sending buffer has not enough space 221 */ 222 MHD_INTERNAL bool 223 mhd_h2_q_window_update (struct MHD_Connection *restrict c, 224 uint_least32_t stream_id, 225 uint_least32_t win_size_incr) 226 MHD_FN_PAR_NONNULL_ALL_; 227 228 #endif /* ! MHD_H2_PROC_OUT_H */