response_options.inc (8943B)
1 @node libmicrohttpd-response-performance 2 @subsection Response options for performance optimization 3 4 @anchor{MHD_R_OPTION_REUSABLE} 5 @deftypefun {struct MHD_ResponseOptionAndValue} MHD_R_OPTION_REUSABLE () 6 7 Make the response object re-usable. 8 The response will not be consumed by 9 @ref{MHD_action_from_response,,@code{MHD_action_from_response()}} 10 and must be destroyed by 11 @ref{MHD_response_destroy,,@code{MHD_response_destroy()}} 12 Useful if the same response is repeatedly used. 13 @table @var 14 @end table 15 16 Returns the option to pass to @code{MHD_response_set_options()}. 17 @end deftypefun 18 19 @anchor{MHD_R_OPTION_HEAD_ONLY_RESPONSE} 20 @deftypefun {struct MHD_ResponseOptionAndValue} MHD_R_OPTION_HEAD_ONLY_RESPONSE () 21 22 Enable special processing of the response as body-less (with undefined 23 body size). No automatic "Content-Length" or "Transfer-Encoding: 24 chunked" headers are added when the response is used with 25 @code{MHD_HTTP_STATUS_NOT_MODIFIED} code or to respond to HEAD 26 requests. 27 28 The flag also allows applications to set an arbitrary "Content-Length" 29 header using 30 @ref{MHD_response_add_header,,@code{MHD_response_add_header()}}. 31 This flag value can be used only with responses created with a body of 32 zero length. 33 34 Responses with this flag enabled cannot be used in situations where a 35 response body must be sent to the client. This flag is primarily 36 intended to be used when automatic "Content-Length" header computation 37 by MHD is undesirable in response to HEAD requests. 38 39 Returns the option to pass to @code{MHD_response_set_options()}. 40 @end deftypefun 41 42 43 44 @node libmicrohttpd-response-compatibility 45 @subsection Response options to help with compatibility 46 47 48 @anchor{MHD_R_OPTION_CONN_CLOSE} 49 @deftypefun {struct MHD_ResponseOptionAndValue} MHD_R_OPTION_CONN_CLOSE () 50 51 Force MHD to close the connection after sending the response, 52 prevents keeping connections alive and adds a "Connection: close" header. 53 54 Returns the option to pass to @code{MHD_response_set_options()} 55 @end deftypefun 56 57 @deftypefun {struct MHD_ResponseOptionAndValue} MHD_R_OPTION_HTTP_1_0_COMPATIBLE_STRICT () 58 59 Only respond in conservative (dumb) HTTP/1.0-compatible mode. 60 Response still use HTTP/1.1 version in header, but always close the 61 connection after sending the response and do not use chunked encoding 62 for the response. You can also set the #MHD_R_O_HTTP_1_0_SERVER flag 63 to force HTTP/1.0 version in the response. Responses are still 64 compatible with HTTP/1.1. This option thus ensures: 65 66 @itemize 67 @item declared reply version: HTTP/1.1 68 @item keep-alive: no 69 @item chunked encoding: no 70 @end itemize 71 72 This option can be used to communicate with some broken client 73 which does not implement HTTP/1.1 features but (falsely) advertises 74 support for HTTP/1.1. 75 @table @var 76 @end table 77 78 Returns the option to pass to @code{MHD_response_set_options()} 79 @end deftypefun 80 81 82 @anchor{MHD_R_OPTION_HTTP_1_0_SERVER} 83 @deftypefun {struct MHD_ResponseOptionAndValue} MHD_R_OPTION_HTTP_1_0_SERVER () 84 85 Only respond in HTTP/1.0-mode. 86 Contrary to the 87 @code{MHD_R_O_HTTP_1_0_COMPATIBLE_STRICT} flag, the 88 response's HTTP version will always be set to 1.0 89 and keep-alive connections will be used only if explicitly requested by the client. 90 The "Connection:" header will be added for both "close" and "keep-alive" connections. 91 Chunked encoding will not be used for the response. 92 Due to backward compatibility, HTTP/1.0-responses still can be used with HTTP/1.1 clients. 93 This option can be used to emulate an HTTP/1.0 server for a specific response 94 (for the response part only, as chunked encoding in requests (if any) is processed by 95 MHD before the application selects a response). 96 This option thus ensures: 97 98 @itemize 99 @item declared reply version: HTTP/1.0 100 @item keep-alive: possible 101 @item chunked encoding: no 102 @end itemize 103 104 With this option an HTTP/1.0 server is emulated (with support for "keep-alive" connections). 105 @table @var 106 @end table 107 108 Returns the option to pass to @code{MHD_response_set_options()}. 109 @end deftypefun 110 111 112 @node libmicrohttpd-response-observability 113 @subsection Response options for observability 114 115 @c FIXME: this should be a *request* option! 116 117 @anchor{MHD_R_OPTION_TERMINATION_CALLBACK} 118 @deftypefun {struct MHD_ResponseOptionAndValue} MHD_R_OPTION_TERMINATION_CALLBACK (MHD_RequestEndedCallback ended_cb, void *ended_cb_cls) 119 120 Set a function to be called once MHD is finished with the request. 121 122 @table @var 123 124 @item ended_cb 125 the function to call, 126 @code{NULL} to not use the callback 127 128 @item ended_cb_cls 129 the closure for the callback 130 @end table 131 132 Returns the option to pass to @code{MHD_response_set_options()}. 133 @end deftypefun 134 135 136 @anchor{MHD_RequestEndedCallback} 137 @deftypefn {Function Pointer} void (*MHD_RequestEndedCallback) (void *cls, const struct MHD_RequestEndedData *req_data, void *request_app_context) 138 139 Signature of the callback used by MHD to notify the application about completed requests. 140 141 This is the last callback called for any request (if the 142 respective option is set by the application). The main 143 use-case is to clean up the application context. 144 145 @table @var 146 @c FIXME: we want to get rid of this argument... 147 @item cls 148 custom value provided by the application at callback registration time; 149 150 @item data 151 final data about the client's request; 152 153 @item request_app_contex 154 value from the location where the application 155 stored information about the request; @code{NULL} 156 if the application never stored any data there. 157 158 @end table 159 @end deftypefn 160 161 The @var{data} provides the following information 162 about the request: 163 164 @anchor{MHD_RequestEndedData} 165 @deftp {C Struct} struct MHD_RequestEndedData 166 167 Data for @ref{MHD_RequestEndedCallback}s. 168 169 @table @var 170 171 @item @code{struct MHD_Request *} request 172 The request handle. 173 Most of the request data may already be unavailable. 174 175 @item @code{enum MHD_RequestEndedCode} code 176 Code explaining how the request ended. 177 178 @item @code{union MHD_RequestEndedDetail} details 179 Further details about how the request ended, specifics 180 depend on @var{code}. 181 182 @end table 183 @end deftp 184 185 186 @anchor{MHD_RequestEndedCode} 187 @deftp {Enumeration} MHD_RequestEndedCode 188 189 The @code{enum MHD_RequestEndedCode} specifies reasons 190 why or how a request has been ended. 191 192 @table @code 193 194 @item MHD_REQUEST_ENDED_COMPLETED_OK 195 The response was successfully sent. 196 197 @item MHD_REQUEST_ENDED_COMPLETED_OK_UPGRADE 198 The response was successfully sent and connection is being switched to another protocol. 199 200 @item MHD_REQUEST_ENDED_TIMEOUT_REACHED 201 No activity on the connection for the number of seconds exceeding the timeout value. 202 @c FIXME: specified using @ref{MHD_C_OPTION_TIMEOUT}. 203 204 @item MHD_REQUEST_ENDED_CONNECTION_ERROR 205 The connection was broken or we had a TLS protocol error. 206 207 @item MHD_REQUEST_ENDED_CLIENT_ABORT 208 The client terminated the connection by closing the socket either completely or for writing (TCP half-closed) before sending the complete request. 209 210 @item MHD_REQUEST_ENDED_HTTP_PROTOCOL_ERROR 211 The request was not valid according to HTTP specifications. 212 213 @item MHD_REQUEST_ENDED_BY_APP_ABORT 214 The application aborted handling the request without 215 specifying a response. 216 217 @item MHD_REQUEST_ENDED_BY_APP_ERROR 218 The request was aborted because the application failed to provide a valid response. 219 220 @item MHD_REQUEST_ENDED_NO_RESOURCES 221 MHD failed to handle the connection due to resource exhaustion. 222 223 @item MHD_REQUEST_ENDED_FILE_ERROR 224 The request was aborted due to an error reading the file (for responses backed by file descriptors). 225 226 @item MHD_REQUEST_ENDED_NONCE_ERROR 227 The request was aborted due to MHD failing to generate a valid nonce for digest authentication. 228 229 @item MHD_REQUEST_ENDED_DAEMON_SHUTDOWN 230 The request was terminated because MHD is closing the 231 underlying session as MHD is being shut down. 232 233 @end table 234 @end deftp 235 236 237 @anchor{MHD_RequestEndedDetail} 238 @deftp {C Union} struct MHD_RequestEndedDetail 239 240 @var{code}-specific details on how a request ended. 241 So far not used, only a placeholder. 242 243 @table @var 244 245 @item @code{void *} reserved 246 Placeholder. Do not used. 247 248 @end table 249 @end deftp 250 251 252 253 @node libmicrohttpd-response-testing 254 @subsection Response options for testing 255 256 257 @anchor{MHD_R_OPTION_CHUNKED_ENC} 258 @deftypefun {struct MHD_ResponseOptionAndValue} MHD_R_OPTION_CHUNKED_ENC () 259 260 Force use of chunked encoding even if the response content size is known. 261 Ignored when the response does not have a body. 262 263 Returns the option to pass to @code{MHD_response_set_options()}. 264 @end deftypefun 265 266 267 @anchor{MHD_R_OPTION_INSANITY_HEADER_CONTENT_LENGTH} 268 @deftypefun {struct MHD_ResponseOptionAndValue} MHD_R_OPTION_INSANITY_HEADER_CONTENT_LENGTH () 269 270 Disable sanity checks that generally prevent clients from manually 271 setting the HTTP content length option. Also allows applications to 272 set several "Content-Length" headers. These headers will be returned 273 to the client even with replies without a body. 274 275 This option is useful when using MHD to test HTTP clients, but should 276 have no place in production. 277 278 Returns the option to pass to @code{MHD_response_set_options()}. 279 @end deftypefun