callbacks.inc (9031B)
1 2 @deftypefn {Function Pointer} enum MHD_Result {*MHD_AcceptPolicyCallback} (void *cls, const struct sockaddr * addr, socklen_t addrlen) 3 Invoked in the context of a connection to allow or deny a client to 4 connect. This callback return @code{MHD_YES} if connection is allowed, 5 @code{MHD_NO} if not. 6 7 @table @var 8 @item cls 9 custom value selected at callback registration time; 10 @item addr 11 address information from the client; 12 @item addrlen 13 length of the address information. 14 @end table 15 @end deftypefn 16 17 18 @anchor{MHD_RequestCompletedCallback} 19 @deftypefn {Function Pointer} void {*MHD_RequestCompletedCallback} (void *cls, struct MHD_Connection *connection, void **req_cls, enum MHD_RequestTerminationCode toe) 20 Signature of the callback used by MHD to notify the application about 21 completed requests. 22 23 @table @var 24 @item cls 25 custom value selected at callback registration time; 26 27 @item connection 28 connection handle; 29 30 @item req_cls 31 value as set by the last call to the 32 @code{MHD_AccessHandlerCallback}; 33 34 @item toe 35 reason for request termination see @code{MHD_OPTION_NOTIFY_COMPLETED}. 36 @end table 37 @end deftypefn 38 39 40 @deftypefn {Function Pointer} enum MHD_Result {*MHD_KeyValueIterator} (void *cls, enum MHD_ValueKind kind, const char *key, const char *value, size_t value_size) 41 Iterator over key-value pairs. This iterator can be used to iterate 42 over all of the cookies, headers, or @code{POST}-data fields of a 43 request, and also to iterate over the headers that have been added to a 44 response. 45 46 @table @var 47 @item cls 48 custom value specified when iteration was triggered; 49 50 @item kind 51 kind of the header we are looking at 52 53 @item key 54 key for the value, can be an empty string 55 56 @item value 57 value corresponding value, can be NULL 58 59 @item value_size 60 number of bytes in @code{value}. This argument was introduced in 61 @code{MHD_VERSION} 0x00096301 to allow applications to use binary 62 zeros in values. Applications using this argument must ensure that 63 they are using a sufficiently recent version of MHD, i.e. by testing 64 @code{MHD_get_version()} for values above or equal to 0.9.64. 65 Applications that do not need zeros in values and that want to compile 66 without warnings against newer versions of MHD should not declare this 67 argument and cast the function pointer argument to 68 @code{MHD_KeyValueIterator}. 69 70 @end table 71 72 Return @code{MHD_YES} to continue iterating, @code{MHD_NO} to abort the 73 iteration. 74 @end deftypefn 75 76 77 @deftypefn {Function Pointer} ssize_t {*MHD_ContentReaderCallback} (void *cls, uint64_t pos, char *buf, size_t max) 78 Callback used by MHD in order to obtain content. The callback has to 79 copy at most @var{max} bytes of content into @var{buf}. The total 80 number of bytes that has been placed into @var{buf} should be returned. 81 82 Note that returning zero will cause MHD to try again. 83 Thus, returning zero should only be used in conjunction 84 with @code{MHD_suspend_connection()} to avoid busy waiting. 85 86 While usually the callback simply returns the number of bytes written 87 into @var{buf}, there are two special return value: 88 89 @code{MHD_CONTENT_READER_END_OF_STREAM} (-1) should be returned 90 for the regular end of transmission (with chunked encoding, MHD will then 91 terminate the chunk and send any HTTP footers that might be 92 present; without chunked encoding and given an unknown 93 response size, MHD will simply close the connection; note 94 that while returning @code{MHD_CONTENT_READER_END_OF_STREAM} is not technically 95 legal if a response size was specified, MHD accepts this 96 and treats it just as @code{MHD_CONTENT_READER_END_WITH_ERROR}. 97 98 @code{MHD_CONTENT_READER_END_WITH_ERROR} (-2) is used to indicate a server 99 error generating the response; this will cause MHD to simply 100 close the connection immediately. If a response size was 101 given or if chunked encoding is in use, this will indicate 102 an error to the client. Note, however, that if the client 103 does not know a response size and chunked encoding is not in 104 use, then clients will not be able to tell the difference between 105 @code{MHD_CONTENT_READER_END_WITH_ERROR} and 106 @code{MHD_CONTENT_READER_END_OF_STREAM}. 107 This is not a limitation of MHD but rather of the HTTP protocol. 108 109 @table @var 110 @item cls 111 custom value selected at callback registration time; 112 113 @item pos 114 position in the datastream to access; note that if an 115 @code{MHD_Response} object is re-used, it is possible for the same 116 content reader to be queried multiple times for the same data; however, 117 if an @code{MHD_Response} is not re-used, MHD guarantees that 118 @var{pos} will be the sum of all non-negative return values obtained 119 from the content reader so far. 120 @end table 121 122 Return @code{-1} on error (MHD will no longer try to read content and 123 instead close the connection with the client). 124 @end deftypefn 125 126 127 @deftypefn {Function Pointer} void {*MHD_ContentReaderFreeCallback} (void *cls) 128 This method is called by MHD if we are done with a content reader. 129 It should be used to free resources associated with the content reader. 130 @end deftypefn 131 132 133 @deftypefn {Function Pointer} enum MHD_Result {*MHD_PostDataIterator} (void *cls, enum MHD_ValueKind kind, const char *key, const char *filename, const char *content_type, const char *transfer_encoding, const char *data, uint64_t off, size_t size) 134 Iterator over key-value pairs where the value maybe made available in 135 increments and/or may not be zero-terminated. Used for processing 136 @code{POST} data. 137 138 @table @var 139 @item cls 140 custom value selected at callback registration time; 141 142 @item kind 143 type of the value; 144 145 @item key 146 zero-terminated key for the value; 147 148 @item filename 149 name of the uploaded file, @code{NULL} if not known; 150 151 @item content_type 152 mime-type of the data, @code{NULL} if not known; 153 154 @item transfer_encoding 155 encoding of the data, @code{NULL} if not known; 156 157 @item data 158 pointer to size bytes of data at the specified offset; 159 160 @item off 161 offset of data in the overall value; 162 163 @item size 164 number of bytes in data available. 165 @end table 166 167 Return @code{MHD_YES} to continue iterating, @code{MHD_NO} to abort the 168 iteration. 169 @end deftypefn 170 171 172 @deftypefn {Function Pointer} void* {*MHD_WebSocketMallocCallback} (size_t buf_len) 173 @cindex websocket 174 This callback function is used internally by many websocket functions 175 for allocating data. 176 By default @code{malloc} is used. 177 You can use your own allocation function with @code{MHD_websocket_stream_init2} 178 if you wish to. 179 This can be useful for operating systems like Windows 180 where @code{malloc}, @code{realloc} and @code{free} are compiler-dependent. 181 You can call the associated @code{malloc} callback of 182 a websocket stream with @code{MHD_websocket_malloc}. 183 184 @table @var 185 @item buf_len 186 size of the buffer to allocate in bytes. 187 @end table 188 189 Return the pointer of the allocated buffer or @code{NULL} on failure. 190 @end deftypefn 191 192 193 @deftypefn {Function Pointer} void* {*MHD_WebSocketReallocCallback} (void *buf, size_t new_buf_len) 194 @cindex websocket 195 This callback function is used internally by many websocket 196 functions for reallocating data. 197 By default @code{realloc} is used. 198 You can use your own reallocation function with 199 @code{MHD_websocket_stream_init2} if you wish to. 200 This can be useful for operating systems like Windows 201 where @code{malloc}, @code{realloc} and @code{free} are compiler-dependent. 202 You can call the associated @code{realloc} callback of 203 a websocket stream with @code{MHD_websocket_realloc}. 204 205 @table @var 206 @item buf 207 current buffer, may be @code{NULL}; 208 209 @item new_buf_len 210 new size of the buffer in bytes. 211 @end table 212 213 Return the pointer of the reallocated buffer or @code{NULL} on failure. 214 On failure the old pointer must remain valid. 215 @end deftypefn 216 217 218 @deftypefn {Function Pointer} void {*MHD_WebSocketFreeCallback} (void *buf) 219 @cindex websocket 220 This callback function is used internally by many websocket 221 functions for freeing data. 222 By default @code{free} is used. 223 You can use your own free function with 224 @code{MHD_websocket_stream_init2} if you wish to. 225 This can be useful for operating systems like Windows 226 where @code{malloc}, @code{realloc} and @code{free} are compiler-dependent. 227 You can call the associated @code{free} callback of 228 a websocket stream with @code{MHD_websocket_free}. 229 230 @table @var 231 @item cls 232 current buffer to free, this may be @code{NULL} then nothing happens. 233 @end table 234 @end deftypefn 235 236 237 @deftypefn {Function Pointer} size_t {*MHD_WebSocketRandomNumberGenerator} (void *cls, void* buf, size_t buf_len) 238 @cindex websocket 239 This callback function is used for generating random numbers 240 for masking payload data in client mode. 241 If you use websockets in server mode with @emph{libmicrohttpd} then 242 you don't need a random number generator, because 243 the server doesn't mask its outgoing messages. 244 However if you wish to use a websocket stream in client mode, 245 you must pass this callback function to @code{MHD_websocket_stream_init2}. 246 247 @table @var 248 @item cls 249 closure specified in @code{MHD_websocket_stream_init2}; 250 @item buf 251 buffer to fill with random values; 252 @item buf_len 253 size of buffer in bytes. 254 @end table 255 256 Return the number of generated random bytes. 257 The return value should usually equal to buf_len. 258 @end deftypefn