diff options
Diffstat (limited to 'doc/microhttpd.texi')
| -rw-r--r-- | doc/microhttpd.texi | 1198 |
1 files changed, 1198 insertions, 0 deletions
diff --git a/doc/microhttpd.texi b/doc/microhttpd.texi new file mode 100644 index 00000000..e9b63779 --- /dev/null +++ b/doc/microhttpd.texi @@ -0,0 +1,1198 @@ +@setfilename microhttpd.info + +@macro gnu{} +@acronym{GNU} +@end macro + +@macro gpl{} +@acronym{GPL} +@end macro + +@macro http{} +@acronym{HTTP} +@end macro + +@macro tcp{} +@acronym{TCP} +@end macro + +@macro api{} +@acronym{API} +@end macro + +@macro urloc{} +@acronym{URL} +@end macro + +@macro uri{} +@acronym{URI} +@end macro + +@macro ascii{} +@acronym{ASCII} +@end macro + +@c ............................................................ + +@macro cfunction{NAME} +@code{\NAME\()} +@end macro + +@macro null{} +@code{NULL} +@end macro + +@c ............................................................ + +@macro glibcref{NODE, NODE} +@pxref{\NODE\, \NODE\, \NODE\, libc} +@end macro + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +@c ------------------------------------------------------------ +@node microhttpd +@appendix Libmicrohttpd documentation + + +@macro mhd{} +@acronym{MHD} +@end macro + + +@noindent +This appendix documents Libmicrohttpd version 0.1.2. It is built upon +the documentation in the header file @file{microhttpd.h}. + +@menu +* microhttpd intro:: Introduction. +* microhttpd const:: Constants. +* microhttpd struct:: Structures type definition. +* microhttpd cb:: Callback functions definition. +* microhttpd init:: Starting and stopping the server. +* microhttpd inspect:: Inspection. +* microhttpd requests:: Handling requests. +* microhttpd responses:: Building responses to requests. +* microhttpd post:: Adding a @code{POST} processor. +@end menu + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd intro +@appendixsec Introduction + + +@noindent +All symbols defined in the public @api{} start with @code{MHD_}. @mhd{} +is a small @http{} daemon library. As such, it does not have any @api{} +for logging errors (you can only enable or disable logging to stderr). +Also, it may not support all of the @http{} features directly, where +applicable, portions of @http{} may have to be handled by clients of the +library. + +The library is supposed to handle everything that it must handle +(because the @api{} would not allow clients to do this), such as basic +connection management; however, detailed interpretations of headers --- +such as range requests --- and @http{} methods are left to clients. The +library does understand @code{HEAD} and will only send the headers of +the response and not the body, even if the client supplied a body. The +library also understands headers that control connection management +(specifically, @code{Connection: close} and @code{Expect: 100 continue} +are understood and handled automatically). + +@mhd{} understands @code{POST} data and is able to decode certain +formats (at the moment only @code{application/x-www-form-urlencoded}) if +the entire data fits into the allowed amount of memory for the +connection. Unsupported encodings and large @code{POST} submissions are +provided as a stream to the main application (and thus can be processed, +just not conveniently by @mhd{}). + +The header file defines various constants used by the @http{} protocol. +This does not mean that @mhd{} actually interprets all of these values. +The provided constants are exported as a convenience for users of the +library. @mhd{} does not verify that transmitted @http{} headers are +part of the standard specification; users of the library are free to +define their own extensions of the @http{} standard and use those with +@mhd{}. + +All functions are guaranteed to be completely reentrant and +thread--safe. + + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd const +@appendixsec Constants + + +@deftp {Enumeration} MHD_FLAG +Options for the @mhd{} daemon. + +Note that if neither @code{MHD_USER_THREAD_PER_CONNECTION} nor +@code{MHD_USE_SELECT_INTERNALLY} are used, the client wants control over +the process and will call the appropriate microhttpd callbacks. + +Starting the daemon may also fail if a particular option is not +implemented or not supported on the target platform (i.e. no support for +@acronym{SSL}, threads or IPv6). + +@table @code +@item MHD_NO_FLAG +No options selected. + +@item MHD_USE_DEBUG +Run in debug mode. If this flag is used, the library should print error +messages and warnings to stderr. + +@item MHD_USE_SSL +Run in https mode. + +@item MHD_USE_THREAD_PER_CONNECTION +Run using one thread per connection. + +@item MHD_USE_SELECT_INTERNALLY +Run using an internal thread doing @code{SELECT}. + +@item MHD_USE_IPv6 +Run using the IPv6 protocol (otherwise, @mhd{} will just support IPv4). + + +@item MHD_USE_PEDANTIC_CHECKS +Be pedantic about the protocol (as opposed to as tolerant as possible). +Specifically, at the moment, this flag causes @mhd{} to reject @http{} +1.1 connections without a @code{Host} header. This is required by the +standard, but of course in violation of the ``be as liberal as possible +in what you accept'' norm. It is recommended to turn this @strong{ON} +if you are testing clients against @mhd{}, and @strong{OFF} in +production. +@end table +@end deftp + + +@deftp {Enumeration} MHD_OPTION +@mhd{} options. Passed in the varargs portion of +@cfunction{MHD_start_daemon}. + +@table @code +@item MHD_OPTION_END +No more options / last option. This is used to terminate the VARARGs +list. + +@item MHD_OPTION_CONNECTION_MEMORY_LIMIT +Maximum memory size per connection (followed by an @code{unsigned int}). + +@item MHD_OPTION_CONNECTION_LIMIT +Maximum number of concurrenct connections to accept (followed by an +@code{unsigned int}). + +@item MHD_OPTION_CONNECTION_TIMEOUT +After how many seconds of inactivity should a connection automatically +be timed out? (followed by an @code{unsigned int}; use zero for no +timeout). + +@item MHD_OPTION_NOTIFY_COMPLETED +Register a function that should be called whenever a request has been +completed (this can be used for application--specific clean up). +Requests that have never been presented to the application (via +@cfunction{MHD_AccessHandlerCallback}) will not result in +notifications. + +This option should be followed by @strong{TWO} pointers. First a +pointer to a function of type @cfunction{MHD_RequestCompletedCallback} +and second a pointer to a closure to pass to the request completed +callback. The second pointer maybe @null{}. +@end table +@end deftp + + +@deftp {Enumeration} MHD_ValueKind +The @code{MHD_ValueKind} specifies the source of the key--value pairs in +the @http{} protocol. + +@table @code +@item MHD_RESPONSE_HEADER_KIND +Response header. + +@item MHD_HEADER_KIND +@http{} header. + +@item MHD_COOKIE_KIND +Cookies. Note that the original @http{} header containing the cookie(s) +will still be available and intact. + +@item MHD_POSTDATA_KIND +@code{POST} data. This is available only if a content encoding +supported by @mhd{} is used (currently only @acronym{URL} encoding), and +only if the posted content fits within the available memory pool. Note +that in that case, the upload data given to the +@cfunction{MHD_AccessHandlerCallback} will be empty (since it has +already been processed). + +@item MHD_GET_ARGUMENT_KIND +@code{GET} (@uri{}) arguments. +@end table +@end deftp + + +@deftp {Enumeration} MHD_RequestTerminationCode +The @code{MHD_RequestTerminationCode} specifies reasons why a request +has been terminated (or completed). + +@table @code +@item MHD_REQUEST_TERMINATED_COMPLETED_OK +We finished sending the response. + +@item MHD_REQUEST_TERMINATED_WITH_ERROR +Error handling the connection (resources exhausted, other side closed +connection, application error accepting request, etc.) + +@item MHD_REQUEST_TERMINATED_TIMEOUT_REACHED +No activity on the connection for the number of seconds specified using +@code{MHD_OPTION_CONNECTION_TIMEOUT}. + +@item MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN +We had to close the session since @mhd{} was being shut down. +@end table +@end deftp + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd struct +@appendixsec Structures type definition + + +@deftp {C Struct} MHD_Daemon +Handle for the daemon (listening on a socket for @http{} traffic). +@end deftp + + +@deftp {C Struct} MHD_Connection +Handle for a connection / @http{} request. With @http{}/1.1, multiple +requests can be run over the same connection. However, @mhd{} will only +show one request per @tcp{} connection to the client at any given time. +@end deftp + + +@deftp {C Struct} MHD_Response +Handle for a response. +@end deftp + + +@deftp {C Struct} MHD_PostProcessor +Handle for @code{POST} processing. +@end deftp + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd cb +@appendixsec Callback functions definition + + +@deftypefn {Function Pointer} int {*MHD_AcceptPolicyCallback} (void *cls, const struct sockaddr * addr, socklen_t addrlen) +Invoked in the context of a connection to allow or deny a client to +connect. This callback return @code{MHD_YES} if connection is allowed, +@code{MHD_NO} if not. + +@table @var +@item cls +custom value selected at callback registration time; +@item addr +address information from the client; +@item addrlen +length of the address information. +@end table +@end deftypefn + + +@deftypefn {Function Pointer} int {*MHD_AccessHandlerCallback} (void *cls, struct MHD_Connection * connection, const char *url, const char *method, const char *version, const char *upload_data, unsigned int *upload_data_size, void **con_cls) +Invoked in the context of a connection to answer a request from the +client. This callback must call @mhd{} functions (example: the +@code{MHD_Response} ones) to provide content to give back to the client +and return an @http{} status code (i.e. @code{200} for OK, @code{404}, +etc.). + +@ref{microhttpd post}, for details on how to code this callback. + +Must return @code{MHD_YES} if the connection was handled successfully, +@code{MHD_NO} if the socket must be closed due to a serious error while +handling the request + +@table @var +@item cls +custom value selected at callback registration time; + +@item url +the @urloc{} requested by the client; + +@item method +the @http{} method used by the client (@code{GET}, @code{PUT}, +@code{DELETE}, @code{POST}, etc.); + +@item version +the @http{} version string (i.e. @code{HTTP/1.1}); + +@item upload_data +the data being uploaded (excluding headers): + +@itemize +@item +for a @code{POST} that fits into memory and that is encoded with a +supported encoding, the @code{POST} data will @strong{NOT} be given in +@var{upload_data} and is instead available as part of +@cfunction{MHD_get_connection_values}; + +@item +very large @code{POST} data @strong{will} be made available +incrementally in @var{upload_data}; +@end itemize + +@item upload_data_size +set initially to the size of the @var{upload_data} provided; this +callback must update this value to the number of bytes @strong{NOT} +processed; + +@item con_cls +reference to a pointer, initially set to @null{}, that this callback can +set to some address and that will be preserved by @mhd{} for future +calls for this request; + +since the access handler may be called many times (i.e., for a +@code{PUT}/@code{POST} operation with plenty of upload data) this allows +the application to easily associate some request--specific state; + +if necessary, this state can be cleaned up in the global +@code{MHD_RequestCompletedCallback} (which can be set with the +@code{MHD_OPTION_NOTIFY_COMPLETED}). +@end table +@end deftypefn + + +@deftypefn {Function Pointer} void {*MHD_RequestCompletedCallback} (void *cls, struct MHD_Connectionconnection, void **con_cls, enum MHD_RequestTerminationCode toe) +Signature of the callback used by @mhd{} to notify the application about +completed requests. + +@table @var +@item cls +custom value selected at callback registration time; + +@item connection +connection handle; + +@item con_cls +value as set by the last call to the +@code{MHD_AccessHandlerCallback}; + +@item toe +reason for request termination see @code{MHD_OPTION_NOTIFY_COMPLETED}. +@end table +@end deftypefn + + +@deftypefn {Function Pointer} int {*MHD_KeyValueIterator} (void *cls, enum MHD_ValueKind kind, const char *key, const char *value) +Iterator over key--value pairs. This iterator can be used to iterate +over all of the cookies, headers, or @code{POST}--data fields of a +request, and also to iterate over the headers that have been added to a +response. + +Return @code{MHD_YES} to continue iterating, @code{MHD_NO} to abort the +iteration. +@end deftypefn + + +@deftypefn {Function Pointer} int {*MHD_ContentReaderCallback} (void *cls, size_t pos, char *buf, int max) +Callback used by @mhd{} in order to obtain content. The callback has to +copy at most @var{max} bytes of content into @var{buf}. The total +number of bytes that has been placed into @var{buf} should be returned. + +Note that returning zero will cause @mhd{} to try again, either +``immediately'' if in multi--threaded mode (in which case the callback +may want to do blocking operations) or in the next round if MHD_run is +used. Returning zero for a daemon that runs in internal +@cfunction{select} mode is an error (since it would result in busy +waiting) and will cause the program to be aborted (@cfunction{abort}). + +@table @var +@item cls +custom value selected at callback registration time; + +@item pos +position in the datastream to access; note that if an +@code{MHD_Response} object is re--used, it is possible for the same +content reader to be queried multiple times for the same data; however, +if an @code{MHD_Response} is not re--used, @mhd{} guarantees that +@var{pos} will be the sum of all non--negative return values obtained +from the content reader so far. +@end table + +Return @code{-1} on error (@mhd{} will no longer try to read content and +instead close the connection with the client). +@end deftypefn + + +@deftypefn {Function Pointer} void {*MHD_ContentReaderFreeCallback} (void *cls) +This method is called by @mhd{} if we are done with a content reader. +It should be used to free resources associated with the content reader. +@end deftypefn + + +@deftypefn {Function Pointer} int {*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, size_t off, size_t size) +Iterator over key--value pairs where the value maybe made available in +increments and/or may not be zero--terminated. Used for processing +@code{POST} data. + +@table @var +@item cls +custom value selected at callback registration time; + +@item kind +type of the value; + +@item key +zero--terminated key for the value; + +@item filename +name of the uploaded file, @null{} if not known; + +@item content_type +mime--type of the data, @null{} if not known; + +@item transfer_encoding +encoding of the data, @null{} if not known; + +@item data +pointer to size bytes of data at the specified offset; + +@item off +offset of data in the overall value; + +@item size +number of bytes in data available. +@end table + +Return @code{MHD_YES} to continue iterating, @code{MHD_NO} to abort the +iteration. +@end deftypefn + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd init +@appendixsec Starting and stopping the server + + +@deftypefun {struct MHD_Daemon *} MHD_start_daemon (unsigned int flags, unsigned short port, MHD_AcceptPolicyCallback apc, void *apc_cls, MHD_AccessHandlerCallback dh, void *dh_cls, ...) +Start a webserver on the given port. + +@table @var +@item flags +OR--ed combination of @code{MHD_FLAG} values; + +@item port +port to bind to; + +@item apc +callback to call to check which clients will be allowed to connect; you +can pass @null{} in which case connections from any @acronym{IP} will be +accepted; + +@item apc_cls +extra argument to @var{apc}; + +@item dh +default handler for all @uri{}s; + +@item dh_cls +extra argument to @var{dh}. +@end table + +Additional arguments are a list of options (type--value pairs, +terminated with @code{MHD_OPTION_END}). It is mandatory to use +@code{MHD_OPTION_END} as last argument, even when there are no +additional arguments. + +Return @null{} on error, handle to daemon on success. +@end deftypefun + + +@deftypefun void MHD_stop_daemon (struct MHD_Daemon *daemon) +Shutdown an @http{} daemon. +@end deftypefun + + +@deftypefun int MHD_run (struct MHD_Daemon *daemon) +Run webserver operations (without blocking unless in client callbacks). +This method should be called by clients in combination with +@cfunction{MHD_get_fdset} if the client--controlled @cfunction{select} +method is used. + +Return @code{MHD_YES} on success, @code{MHD_NO} if this daemon was not +started with the right options for this call. +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd inspect +@appendixsec Inspection + + +@deftypefun int MHD_get_fdset (struct MHD_Daemon *daemon, fd_set * read_fd_set, fd_set * write_fd_set, fd_set * except_fd_set, int *max_fd) +Obtain the @cfunction{select} sets for this daemon. The daemon's socket +is added to @var{read_fd_set}. The list of currently existent +connections is scanned and their file descriptors added to the correct +set. + +@glibcref{Waiting for I/O}, for details on file descriptor sets. + +After the call completed successfully: the variable referenced by +@var{max_fd} references the file descriptor with highest integer +identifier. The variable must be set to zero before invoking this +function. + +Return @code{MHD_YES} on success, @code{MHD_NO} if: the arguments are +invalid (example: @null{} pointers); this daemon was not started with +the right options for this call. +@end deftypefun + + +@deftypefun int MHD_get_timeout (struct MHD_Daemon *daemon, unsigned long long *timeout) +Obtain timeout value for select for this daemon (only needed if +connection timeout is used). The returned value is how long +@cfunction{select} should at most block, not the timeout value set for +connections. + +@table @var +@item timeout +set to the timeout (in milliseconds). +@end table + +Return @code{MHD_YES} on success, @code{MHD_NO} if timeouts are not used +(or no connections exist that would necessiate the use of a timeout +right now). +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd requests +@appendixsec Handling requests + + +@menu +* microhttpd handlers:: @uri{} specific handlers. +* microhttpd values:: Connection headers and small + @code{POST} data. +@end menu + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd handlers +@appendixsubsec @uri{} specific handlers + + +@noindent +A set of callbacks can be registered in the state of a daemon +(@code{MHD_Daemon}) to handle request for specific sets of +resources. The set is selected by specifying the prefix string of the +@uri{}, example: + +@example +/bookcase +@end example + +@noindent +matches all of the following: + +@example +/bookcase/book.html +/bookcase/pencil.html +/bookcase/strawberry.html +@end example + +Handlers are stored in a linked list (managed with @cfunction{malloc} +and @cfunction{free}). Prefixes are compared with @cfunction{strcmp}. + + +@deftypefun int MHD_register_handler (struct MHD_Daemon *daemon, const char *uri_prefix, MHD_AccessHandlerCallback dh, void *dh_cls) +Register an access handler for all @uri{}s beginning with +@var{uri_prefix}, a zero--terminated @ascii{}--coded string. + +Return @code{MRI_NO} if: the arguments are invalid (example: @null{} +pointers); a handler for this exact prefix already exists; an error +allocating memory happens. +@end deftypefun + + +@deftypefun int MHD_unregister_handler (struct MHD_Daemon *daemon, const char *uri_prefix, MHD_AccessHandlerCallback dh, void *dh_cls) +Unregister an access handler for the @uri{}s beginning with +@var{uri_prefix}. + +Return @code{MHD_NO} if: the arguments are invalid (example: @null{} +pointers); a handler for this exact prefix is not known for this daemon. +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd values +@appendixsubsec Connection headers and small @code{POST} data + + +@deftypefun int MHD_get_connection_values (struct MHD_Connection *connection, enum MHD_ValueKind kind, MHD_KeyValueIterator iterator, void *iterator_cls) +Get all the headers matching @var{kind} from the request. + +The @var{iterator} callback is invoked once for each header, with +@var{iterator_cls} as first argument. Return the number of entries +iterated over; this can be less than the number of headers if, while +iterating, @var{iterator} returns @code{MHD_NO}. + +@var{iterator} can be @null{}: in this case this function just counts +and returns the number of headers. +@end deftypefun + + +@deftypefun {const char *} MHD_lookup_connection_value (struct MHD_Connection *connection, enum MHD_ValueKind kind, const char *key) +Get a particular header value. If multiple values match the @var{kind}, +return one of them (the ``first'', whatever that means). @var{key} must +reference a zero--terminated @ascii{}--coded string representing the +header to look for: it is compared against the headers using +@cfunction{strcasecmp}, so case is ignored. Return @null{} if no such +item was found. +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd responses +@appendixsec Building answers to responses + + +@menu +* microhttpd response enqueue:: Enqueuing a response. +* microhttpd response create:: Creating a response object. +* microhttpd response headers:: Adding headers to a response. +* microhttpd response inspect:: Inspecting a response object. +@end menu + + +@noindent +Response objects handling by @mhd{} is asynchronous with respect to the +application execution flow. Instances of the @code{MHD_Response} +structure are not associated to a daemon and neither to a client +connection: they are managed with reference counting. + +In the simplest case: we allocate a new @code{MHD_Response} structure +for each response, we use it once and finally we destroy it. + +@mhd{} allows more efficient resources usages. + +Example: we allocate a new @code{MHD_Response} structure for each +response @strong{kind}, we use it every time we have to give that +responce and we finally destroy it only when the daemon shuts down. + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd response enqueue +@appendixsubsec Enqueuing a response + + +@deftypefun int MHD_queue_response (struct MHD_Connection *connection, unsigned int status_code, struct MHD_Response *response) +Queue a response to be transmitted to the client as soon as possible +(increment the reference counter). + +@table @var +@item connection +the connection identifying the client; + +@item status_code +@http{} status code (i.e. @code{200} for OK); + +@item response +response to transmit. +@end table + +Return @code{MHD_YES} on success or if message has been queued. Return +@code{MHD_NO}: if arguments are invalid (example: @null{} pointer); on +error (i.e. reply already sent). +@end deftypefun + + +@deftypefun void MHD_destroy_response (struct MHD_Response *response) +Destroy a response object and associated resources (decrement the +reference counter). Note that @mhd{} may keep some of the resources +around if the response is still in the queue for some clients, so the +memory may not necessarily be freed immediatley. +@end deftypefun + + +An explanation of reference counting@footnote{Note to readers acquainted +to the Tcl @api{}: reference counting on @code{MHD_Connection} +structures is handled in the same way as Tcl handles @code{Tcl_Obj} +structures through @cfunction{Tcl_IncrRefCount} and +@cfunction{Tcl_DecrRefCount}.}: + +@enumerate +@item +a @code{MHD_Response} object is allocated: + +@example +struct MHD_Response * response = MHD_create_response_from_data(...); +/* here: reference counter = 1 */ +@end example + +@item +the @code{MHD_Response} object is enqueued in a @code{MHD_Connection}: + +@example +MHD_queue_response(connection, , response); +/* here: reference counter = 2 */ +@end example + +@item +the creator of the response object discharges responsibility for it: + +@example +MHD_destroy_response(response); +/* here: reference counter = 1 */ +@end example + +@item +the daemon handles the connection sending the response's data to the +client then decrements the reference counter by calling +@cfunction{MHD_destroy_response}: the counter's value drops to zero and +the @code{MHD_Response} object is released. +@end enumerate + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd response create +@appendixsubsec Creating response objects + + +@deftypefun {struct MHD_Response *} MHD_create_response_from_callback (size_t size, unsigned int block_size, MHD_ContentReaderCallback crc, void *crc_cls, MHD_ContentReaderFreeCallback crfc) +Create a response object. The response object can be extended with +header information and then it can be used any number of times. + +@table @var +@item size +size of the data portion of the response, @code{-1} for unknown; + +@item block_size +preferred block size for querying @var{crc} (advisory only, @mhd{} may +still call @var{crc} using smaller chunks); this is essentially the +buffer size used for @acronym{IO}, clients should pick a value that is +appropriate for @acronym{IO} and memory performance requirements; + +@item crc +callback to use to obtain response data; + +@item crc_cls +extra argument to @var{crc}; + +@item crfc +callback to call to free @var{crc_cls} resources. +@end table + +Return @null{} on error (i.e. invalid arguments, out of memory). +@end deftypefun + + +@deftypefun {struct MHD_Response *} MHD_create_response_from_data (size_t size, void *data, int must_free, int must_copy) +Create a response object. The response object can be extended with +header information and then it can be used any number of times. + +@table @var +@item size +size of the data portion of the response; + +@item data +the data itself; + +@item must_free +if true: @mhd{} should free data when done; + +@item must_copy +if true: @mhd{} allocates a block of memory and use it to make a copy of +@var{data} embedded in the returned @code{MHD_Response} structure; +handling of the embedded memory is responsibility of @mhd{}; @var{data} +can be released anytime after this call returns. +@end table + +Return @null{} on error (i.e. invalid arguments, out of memory). +@end deftypefun + + +Example: create a response from a statically allocated string: + +@example +const char * data = "<html><body><p>Error!</p></body></html>"; + +struct MHD_Connection * connection = ...; +struct MHD_Response * response; + +response = MHD_create_response_from_data(strlen(data), data, + MHD_NO, MHD_NO); +MHD_queue_response(connection, 404, response); +MHD_destroy_response(response); +@end example + + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd response headers +@appendixsubsec Adding headers to a response + + +@deftypefun int MHD_add_response_header (struct MHD_Response *response, const char *header, const char *content) +Add a header line to the response. The strings referenced by +@var{header} and @var{content} must be zero--terminated and they are +duplicated into memory blocks embedded in @var{response}. + +Notice that the strings must not hold newlines, carriage returns or tab +chars. + +Return @code{MHD_NO} on error (i.e. invalid header or content format or +memory allocation error). +@end deftypefun + + +@deftypefun int MHD_del_response_header (struct MHD_Response *response, const char *header, const char *content) +Delete a header line from the response. Return @code{MHD_NO} on error +(arguments are invalid or no such header known). +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd response inspect +@appendixsubsec Inspecting a response object + + +@deftypefun int MHD_get_response_headers (struct MHD_Response *response, MHD_KeyValueIterator iterator, void *iterator_cls) +Get all of the headers added to a response. + +Invoke the @var{iterator} callback for each header in the response, +using @var{iterator_cls} as first argument. Return number of entries +iterated over. @var{iterator} can be @null{}: in this case the function +just counts headers. + +@var{iterator} should not modify the its key and value arguments, unless +we know what we are doing. +@end deftypefun + + +@deftypefun {const char *} MHD_get_response_header (struct MHD_Response *response, const char *key) +Find and return a pointer to the value of a particular header from the +response. @var{key} must reference a zero--terminated string +representing the header to look for. The search is case sensitive. +Return @null{} if header does not exist or @var{key} is @null{}. + +We should not modify the value, unless we know what we are doing. +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd post +@appendixsec Adding a @code{POST} processor + + +@menu +* microhttpd post api:: Programming interface for the + @code{POST} processor. +@end menu + + +@noindent +When a small amount of data comes from a client's @code{POST} request: +the data is available through the values interface. @ref{microhttpd +values}, for details. In this case @mhd{} invokes +@code{MHD_AccessHandlerCallback} only once and the callback must process +all the data during that invocation. + +When a big amount of data comes from a client's @code{POST} request: the +@code{MHD_AccessHandlerCallback} will be invoked multiple times to +process data as it arrives; at each invocation a new chunk of data must +be processed. The arguments @var{upload_data} and @var{upload_data_size} +are used to reference the chunk of data. + +When @code{MHD_AccessHandlerCallback} is invoked for a new connection: +its @code{*@var{con_cls}} argument is set to @null{}. When @code{POST} +data comes in the upload buffer it is @strong{mandatory} to use the +@var{con_cls} to hold data or to mark an ongoing process. + +To detect that a new connection has come with the @code{POST} method: + +@example +int +access_handler (void *cls, + struct MHD_Connection * connection, + const char *url, + const char *method, const char *version, + const char *upload_data, unsigned int *upload_data_size, + void **con_cls) +@{ + static int old_connection_marker; + int new_connection = (NULL == *con_cls); + int method_is_post = strcmp("POST",method); + + if (new_connection && method_is_post) + @{ + /* new connection with POST */ + *con_cls = &old_connection_marker; + @} + + ... +@} +@end example + +@noindent +in this example the value of @code{*con_cls} is just an unused pointer +to an unused integer: its purpose is to make @code{*con_cls} different +from @null{}. When serious processing of @code{POST} data is needed: it +can be a pointer to a dynamically allocated data structure. + +To detect that @code{POST} data is in the upload buffer: + +@example +int +access_handler (void *cls, + struct MHD_Connection * connection, + const char *url, + const char *method, const char *version, + const char *upload_data, unsigned int *upload_data_size, + void **con_cls) +@{ + static int old_connection_marker; + int new_connection = (NULL == *con_cls); + int method_is_post = strcmp("POST",method); + + if (new_connection && method_is_post) + @{ + int data_in_upload_buffer = (0 != *upload_data_size); + + if (data_in_upload_buffer) + @{ + *con_cls = &old_connection_marker; + /* POST data in the buffer */ + @} + else + /* POST data accessible with the values API */ + @} + + ... +@} +@end example + + +At each invocation there are two options: + +@enumerate +@item +the callback can process the whole chunk by itself; every time @mhd{} +invokes it a new chunk is fully processed; with this mode the callback +has to @code{*upload_data_size = 0} before returning @code{MHD_YES}; + +@item +the callback can process a section of the chunk by itself; every time +@mhd{} invokes it the buffer holds the old data as well as new data +coming from the client; with this mode the callback has to set +@code{*upload_data_size} to the numbe of bytes still to process before +returning @code{MHD_YES}; + +example: @mhd{} invokes the callback with @code{100 == +*upload_data_size}; the callback processes the first 80 bytes and before +returning the callback sets @code{*upload_data_size = 20}; the last +unprocessed 20 bytes will be the first 20 at the next invocation; + +@item +when a new connection with @code{POST} data in the buffer comes: the +callback allocates a PostProcessor and hand to it the responsibility of +processing data; a pointer to the PostProcessor structure is saved in +@code{*con_cls}, so that it is available at each subsequent invocation; + +the post processor data can be freed by a later invocation to an +appropriate callback. +@end enumerate + + +Let's see how to implement strategy 1: + +@example +int +access_handler (void *cls, + struct MHD_Connection * connection, + const char *url, + const char *method, const char *version, + const char *upload_data, unsigned int *upload_data_size, + void **con_cls) +@{ + static int old_connection_marker; + int new_connection = (NULL == *con_cls); + int method_is_post = strcmp("POST",method); + + if (new_connection && method_is_post) + @{ + int data_in_upload_buffer = (0 != *upload_data_size); + + if (data_in_upload_buffer) + @{ + *con_cls = &old_connection_marker; + @} + else + @{ + /* POST data accessible with the values API */ + return MHD_YES; + @} + @} + + if (&old_connection_marker == *con_cls) + @{ + consume_data(upload_data, *upload_data_size); + *upload_data_size = 0; + return MHD_YES; + @} + + /* process other methods */ + return MHD_YES; +@} +@end example + +Let's see how to implement strategy 2: + +@example +int +access_handler (void *cls, + struct MHD_Connection * connection, + const char *url, + const char *method, const char *version, + const char *upload_data, unsigned int *upload_data_size, + void **con_cls) +@{ + static int old_connection_marker; + int new_connection = (NULL == *con_cls); + int method_is_post = strcmp("POST",method); + + if (new_connection && method_is_post) + @{ + int data_in_upload_buffer = (0 != *upload_data_size); + + if (data_in_upload_buffer) + @{ + *con_cls = &old_connection_marker; + @} + else + @{ + /* POST data accessible with the values API */ + return MHD_YES; + @} + @} + + if (&old_connection_marker == *con_cls) + @{ + int number_of_bytes_to_consume = 100; + + if (number_of_bytes_to_consume > *upload_data_size) + number_of_bytes_to_consume = *upload_data_size; + + consume_some_data(upload_data, number_of_bytes_to_consume); + *upload_data_size -= number_of_bytes_to_consume; + return MHD_YES; + @} + + /* process other methods */ + return MHD_YES; +@} + +@end example + + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd post api +@appendixsubsec Programming interface for the @code{POST} processor + + + +@deftypefun {struct MHD_PostProcessor *} MHD_create_post_processor (struct MHD_Connection *connection, unsigned int buffer_size, MHD_PostDataIterator iterator, void *iterator_cls) +Create a PostProcessor. A PostProcessor can be used to (incrementally) +parse the data portion of a @code{POST} request. + +@table @var +@item connection +the connection on which the @code{POST} is happening (used to determine +the @code{POST} format); + +@item buffer_size +maximum number of bytes to use for internal buffering (used only for the +parsing, specifically the parsing of the keys). A tiny value (256-1024) +should be sufficient; do @strong{NOT} use a value smaller than 256; + +@item iterator +iterator to be called with the parsed data; must @strong{NOT} be +@null{}; + +@item iterator_cls +custom value to be used as first argument to @var{iterator}. +@end table + +Return @null{} on error (out of memory, unsupported encoding), otherwise +a PP handle. +@end deftypefun + + +@deftypefun int MHD_post_process (struct MHD_PostProcessor *pp, const char *post_data, unsigned int post_data_len) +Parse and process @code{POST} data. Call this function when @code{POST} +data is available (usually during an @code{MHD_AccessHandlerCallback}) +with the @var{upload_data} and @var{upload_data_size}. Whenever +possible, this will then cause calls to the +@code{MHD_IncrementalKeyValueIterator}. + +@table @var +@item pp +the post processor; + +@item post_data +@var{post_data_len} bytes of @code{POST} data; + +@item post_data_len +length of @var{post_data}. +@end table + +Return @code{MHD_YES} on success, @code{MHD_NO} on error +(out--of--memory, iterator aborted, parse error). +@end deftypefun + + +@deftypefun void MHD_destroy_post_processor (struct MHD_PostProcessor *pp) +Release PostProcessor resources. +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + |