connection.h (5955B)
1 /* 2 This file is part of libmicrohttpd 3 Copyright (C) 2007 Daniel Pittman and Christian Grothoff 4 Copyright (C) 2015-2023 Evgeny Grin (Karlson2k) 5 6 This library 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 This library 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 You should have received a copy of the GNU Lesser General Public 17 License along with this library; if not, write to the Free Software 18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21 /** 22 * @file connection.h 23 * @brief Methods for managing connections 24 * @author Daniel Pittman 25 * @author Christian Grothoff 26 * @author Karlson2k (Evgeny Grin) 27 */ 28 29 #ifndef CONNECTION_H 30 #define CONNECTION_H 31 32 #include "internal.h" 33 34 /** 35 * Error code similar to EGAIN or EINTR 36 */ 37 #define MHD_ERR_AGAIN_ (-3073) 38 39 /** 40 * Connection was hard-closed by remote peer. 41 */ 42 #define MHD_ERR_CONNRESET_ (-3074) 43 44 /** 45 * Connection is not connected anymore due to 46 * network error or any other reason. 47 */ 48 #define MHD_ERR_NOTCONN_ (-3075) 49 50 /** 51 * "Not enough memory" error code 52 */ 53 #define MHD_ERR_NOMEM_ (-3076) 54 55 /** 56 * "Bad FD" error code 57 */ 58 #define MHD_ERR_BADF_ (-3077) 59 60 /** 61 * Error code similar to EINVAL 62 */ 63 #define MHD_ERR_INVAL_ (-3078) 64 65 /** 66 * Argument values are not supported 67 */ 68 #define MHD_ERR_OPNOTSUPP_ (-3079) 69 70 /** 71 * Socket is shut down for writing or no longer connected 72 */ 73 #define MHD_ERR_PIPE_ (-3080) 74 75 /** 76 * General TLS encryption or decryption error 77 */ 78 #define MHD_ERR_TLS_ (-4097) 79 80 81 /** 82 * Set callbacks for this connection to those for HTTP. 83 * 84 * @param connection connection to initialize 85 */ 86 void 87 MHD_set_http_callbacks_ (struct MHD_Connection *connection); 88 89 90 /** 91 * Set initial internal states for the connection to start reading and 92 * processing incoming data. 93 * @param c the connection to process 94 */ 95 void 96 MHD_connection_set_initial_state_ (struct MHD_Connection *c); 97 98 /** 99 * This function handles a particular connection when it has been 100 * determined that there is data to be read off a socket. All 101 * implementations (multithreaded, external polling, internal polling) 102 * call this function to handle reads. 103 * 104 * @param connection connection to handle 105 * @param socket_error set to true if socket error was detected 106 */ 107 void 108 MHD_connection_handle_read (struct MHD_Connection *connection, 109 bool socket_error); 110 111 112 /** 113 * This function was created to handle writes to sockets when it has 114 * been determined that the socket can be written to. All 115 * implementations (multithreaded, external select, internal select) 116 * call this function 117 * 118 * @param connection connection to handle 119 */ 120 void 121 MHD_connection_handle_write (struct MHD_Connection *connection); 122 123 124 /** 125 * This function was created to handle per-connection processing that 126 * has to happen even if the socket cannot be read or written to. 127 * All implementations (multithreaded, external select, internal select) 128 * call this function. 129 * @remark To be called only from thread that process connection's 130 * recv(), send() and response. 131 * 132 * @param connection connection to handle 133 * @return #MHD_YES if we should continue to process the 134 * connection (not dead yet), #MHD_NO if it died 135 */ 136 enum MHD_Result 137 MHD_connection_handle_idle (struct MHD_Connection *connection); 138 139 140 /** 141 * Mark connection as "closed". 142 * @remark To be called from any thread. 143 * 144 * @param connection connection to close 145 */ 146 void 147 MHD_connection_mark_closed_ (struct MHD_Connection *connection); 148 149 150 /** 151 * Close the given connection and give the 152 * specified termination code to the user. 153 * @remark To be called only from thread that 154 * process connection's recv(), send() and response. 155 * 156 * @param connection connection to close 157 * @param termination_code termination reason to give 158 */ 159 void 160 MHD_connection_close_ (struct MHD_Connection *connection, 161 enum MHD_RequestTerminationCode termination_code); 162 163 164 #ifdef HTTPS_SUPPORT 165 /** 166 * Stop TLS forwarding on upgraded connection and 167 * reflect remote disconnect state to socketpair. 168 * @param connection the upgraded connection 169 */ 170 void 171 MHD_connection_finish_forward_ (struct MHD_Connection *connection); 172 173 #else /* ! HTTPS_SUPPORT */ 174 #define MHD_connection_finish_forward_(conn) (void) conn 175 #endif /* ! HTTPS_SUPPORT */ 176 177 178 #ifdef EPOLL_SUPPORT 179 /** 180 * Perform epoll processing, possibly moving the connection back into 181 * the epoll set if needed. 182 * 183 * @param connection connection to process 184 * @return #MHD_YES if we should continue to process the 185 * connection (not dead yet), #MHD_NO if it died 186 */ 187 enum MHD_Result 188 MHD_connection_epoll_update_ (struct MHD_Connection *connection); 189 190 #endif 191 192 /** 193 * Update the 'last_activity' field of the connection to the current time 194 * and move the connection to the head of the 'normal_timeout' list if 195 * the timeout for the connection uses the default value. 196 * 197 * @param connection the connection that saw some activity 198 */ 199 void 200 MHD_update_last_activity_ (struct MHD_Connection *connection); 201 202 203 /** 204 * Allocate memory from connection's memory pool. 205 * If memory pool doesn't have enough free memory but read or write buffer 206 * have some unused memory, the size of the buffer will be reduced as needed. 207 * @param connection the connection to use 208 * @param size the size of allocated memory area 209 * @return pointer to allocated memory region in the pool or 210 * NULL if no memory is available 211 */ 212 void * 213 MHD_connection_alloc_memory_ (struct MHD_Connection *connection, 214 size_t size); 215 216 #endif