5 Starting and stopping the server

Function: void MHD_set_panic_func (MHD_PanicCallback cb, void *cls)

Set a handler for fatal errors.

cb

function to call if MHD encounters a fatal internal error. If no handler was set explicitly, MHD will call abort.

cls

closure argument for cb; the other arguments are the name of the source file, line number and a string describing the nature of the fatal error (which can be NULL)

Function: 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.

flags

OR-ed combination of MHD_FLAG values;

port

port to bind to;

apc

callback to call to check which clients will be allowed to connect; you can pass NULL in which case connections from any IP will be accepted;

apc_cls

extra argument to apc;

dh

default handler for all URIs;

dh_cls

extra argument to dh.

Additional arguments are a list of options (type-value pairs, terminated with MHD_OPTION_END). It is mandatory to use MHD_OPTION_END as last argument, even when there are no additional arguments.

Return NULL on error, handle to daemon on success.

Function: MHD_socket MHD_quiesce_daemon (struct MHD_Daemon *daemon)

Stop accepting connections from the listening socket. Allows clients to continue processing, but stops accepting new connections. Note that the caller is responsible for closing the returned socket; however, if MHD is run using threads (anything but external select mode), it must not be closed until AFTER MHD_stop_daemon has been called (as it is theoretically possible that an existing thread is still using it).

This function is useful in the special case that a listen socket is to be migrated to another process (i.e. a newer version of the HTTP server) while existing connections should continue to be processed until they are finished.

Return -1 on error (daemon not listening), the handle to the listen socket otherwise.

Function: void MHD_stop_daemon (struct MHD_Daemon *daemon)

Shutdown an HTTP daemon.

Function: enum MHD_Result 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 MHD_get_fdset() if the client-controlled select-method is used.

This function will work for external poll and select mode. However, if using external select mode, you may want to instead use MHD_run_from_select, as it is more efficient.

daemon

daemon to process connections of

Return MHD_YES on success, MHD_NO if this daemon was not started with the right options for this call.

Function: enum MHD_Result MHD_run_from_select (struct MHD_Daemon *daemon, const fd_set *read_fd_set, const fd_set *write_fd_set, const fd_set *except_fd_set)

Run webserver operations given sets of ready socket handles.

This method should be called by clients in combination with MHD_get_fdset if the client-controlled (external) select method is used.

You can use this function instead of MHD_run if you called select on the result from MHD_get_fdset. File descriptors in the sets that are not controlled by MHD will be ignored. Calling this function instead of MHD_run is more efficient as MHD will not have to call select again to determine which operations are ready.

daemon

daemon to process connections of

read_fd_set

set of descriptors that must be ready for reading without blocking

write_fd_set

set of descriptors that must be ready for writing without blocking

except_fd_set

ignored, can be NULL

Return MHD_YES on success, MHD_NO on serious internal errors.

Function: void MHD_add_connection (struct MHD_Daemon *daemon, int client_socket, const struct sockaddr *addr, socklen_t addrlen)

Add another client connection to the set of connections managed by MHD. This API is usually not needed (since MHD will accept inbound connections on the server socket). Use this API in special cases, for example if your HTTP server is behind NAT and needs to connect out to the HTTP client, or if you are building a proxy.

If you use this API in conjunction with a internal select or a thread pool, you must set the option MHD_USE_ITC to ensure that the freshly added connection is immediately processed by MHD.

The given client socket will be managed (and closed!) by MHD after this call and must no longer be used directly by the application afterwards.

daemon

daemon that manages the connection

client_socket

socket to manage (MHD will expect to receive an HTTP request from this socket next).

addr

IP address of the client

addrlen

number of bytes in addr

This function will return MHD_YES on success, MHD_NO if this daemon could not handle the connection (i.e. malloc failed, etc). The socket will be closed in any case; ’errno’ is set to indicate further details about the error.