commit 1725bcf3c546fccbf22d7794bf7290fcc28c385d
parent 8e796aefcc5980863088935033fe4d48d4a2e3fa
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 5 May 2013 18:01:09 +0000
-improvements to docs
Diffstat:
20 files changed, 148 insertions(+), 86 deletions(-)
diff --git a/doc/examples/sessions.c b/doc/examples/sessions.c
@@ -522,6 +522,7 @@ post_iterator (void *cls,
*
* @param cls argument given together with the function
* pointer when the handler was registered with MHD
+ * @param connection handle to connection which is being processed
* @param url the requested url
* @param method the HTTP method used ("GET", "PUT", etc.)
* @param version the HTTP version string (i.e. "HTTP/1.1")
@@ -535,7 +536,7 @@ post_iterator (void *cls,
* @param upload_data_size set initially to the size of the
* upload_data provided; the method must update this
* value to the number of bytes NOT processed;
- * @param con_cls pointer that the callback can set to some
+ * @param ptr pointer that the 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 PUT/POST operation
diff --git a/src/daemon/basicauth.c b/src/daemon/basicauth.c
@@ -100,10 +100,14 @@ MHD_basic_auth_get_username_password(struct MHD_Connection *connection,
/**
- * Queues a response to request basic authentication from the client
+ * Queues a response to request basic authentication from the client.
+ * The given response object is expected to include the payload for
+ * the response; the "WWW-Authenticate" header will be added and the
+ * response queued with the 'UNAUTHORIZED' status code.
*
* @param connection The MHD connection structure
* @param realm the realm presented to the client
+ * @param response response object to modify and queue
* @return MHD_YES on success, MHD_NO otherwise
*/
int
diff --git a/src/daemon/connection.c b/src/daemon/connection.c
@@ -1107,7 +1107,7 @@ get_next_header_line (struct MHD_Connection *connection)
}
return NULL;
}
- /* found, check if we have proper CRLF */
+ /* found, check if we have proper LFCR */
if (('\r' == rbuf[pos]) && ('\n' == rbuf[pos + 1]))
rbuf[pos++] = '\0'; /* skip both r and n */
rbuf[pos++] = '\0';
diff --git a/src/daemon/daemon.c b/src/daemon/daemon.c
@@ -95,7 +95,7 @@
* @param cls unused
* @param file name of the file with the problem
* @param line line number with the problem
- * @param msg error message with details
+ * @param reason error message with details
*/
static void
mhd_panic_std (void *cls,
@@ -722,7 +722,7 @@ exit:
/**
* Callback for receiving data from the socket.
*
- * @param conn the MHD connection structure
+ * @param connection the MHD connection structure
* @param other where to write received data to
* @param i maximum size of other (in bytes)
* @return number of bytes actually received
@@ -747,7 +747,7 @@ recv_param_adapter (struct MHD_Connection *connection,
/**
* Callback for writing data to the socket.
*
- * @param conn the MHD connection structure
+ * @param connection the MHD connection structure
* @param other data to write
* @param i number of bytes to write
* @return actual number of bytes written
@@ -803,6 +803,9 @@ send_param_adapter (struct MHD_Connection *connection,
/**
* Signature of main function for a thread.
+ *
+ * @param cls closure argument for the function
+ * @return termination code from the thread
*/
typedef void *(*ThreadStartRoutine)(void *cls);
@@ -817,7 +820,7 @@ typedef void *(*ThreadStartRoutine)(void *cls);
* @return 0 on success
*/
static int
-create_thread (pthread_t * thread,
+create_thread (pthread_t *thread,
const struct MHD_Daemon *daemon,
ThreadStartRoutine start_routine,
void *arg)
@@ -1057,29 +1060,22 @@ MHD_add_connection (struct MHD_Daemon *daemon,
gnutls_transport_set_ptr (connection->tls_session,
(gnutls_transport_ptr_t) connection);
gnutls_transport_set_pull_function (connection->tls_session,
- (gnutls_pull_func) &
- recv_param_adapter);
+ (gnutls_pull_func) &recv_param_adapter);
gnutls_transport_set_push_function (connection->tls_session,
- (gnutls_push_func) &
- send_param_adapter);
+ (gnutls_push_func) &send_param_adapter);
- if (daemon->https_mem_trust){
- gnutls_certificate_server_set_request(connection->tls_session, GNUTLS_CERT_REQUEST);
- }
+ if (daemon->https_mem_trust)
+ gnutls_certificate_server_set_request(connection->tls_session, GNUTLS_CERT_REQUEST);
}
#endif
if (0 != pthread_mutex_lock(&daemon->cleanup_connection_mutex))
- {
- MHD_PANIC ("Failed to acquire cleanup mutex\n");
- }
+ MHD_PANIC ("Failed to acquire cleanup mutex\n");
DLL_insert (daemon->connections_head,
daemon->connections_tail,
connection);
if (0 != pthread_mutex_unlock(&daemon->cleanup_connection_mutex))
- {
- MHD_PANIC ("Failed to release cleanup mutex\n");
- }
+ MHD_PANIC ("Failed to release cleanup mutex\n");
/* attempt to create handler thread */
if (0 != (daemon->options & MHD_USE_THREAD_PER_CONNECTION))
@@ -1742,6 +1738,7 @@ MHD_select_thread (void *cls)
/**
* Start a webserver on the given port.
*
+ * @param flags combination of MHD_FLAG values
* @param port port to bind to
* @param apc callback to call to check which clients
* will be allowed to connect
@@ -1751,7 +1748,7 @@ MHD_select_thread (void *cls)
* @return NULL on error, handle to daemon on success
*/
struct MHD_Daemon *
-MHD_start_daemon (unsigned int options,
+MHD_start_daemon (unsigned int flags,
uint16_t port,
MHD_AcceptPolicyCallback apc,
void *apc_cls,
@@ -1761,7 +1758,7 @@ MHD_start_daemon (unsigned int options,
va_list ap;
va_start (ap, dh_cls);
- daemon = MHD_start_daemon_va (options, port, apc, apc_cls, dh, dh_cls, ap);
+ daemon = MHD_start_daemon_va (flags, port, apc, apc_cls, dh, dh_cls, ap);
va_end (ap);
return daemon;
}
@@ -2163,16 +2160,19 @@ create_socket (int domain, int type, int protocol)
/**
* Start a webserver on the given port.
*
+ * @param flags combination of MHD_FLAG values
* @param port port to bind to
* @param apc callback to call to check which clients
* will be allowed to connect
* @param apc_cls extra argument to apc
* @param dh default handler for all URIs
* @param dh_cls extra argument to dh
+ * @param ap list of options (type-value pairs,
+ * terminated with MHD_OPTION_END).
* @return NULL on error, handle to daemon on success
*/
struct MHD_Daemon *
-MHD_start_daemon_va (unsigned int options,
+MHD_start_daemon_va (unsigned int flags,
uint16_t port,
MHD_AcceptPolicyCallback apc,
void *apc_cls,
@@ -2193,15 +2193,15 @@ MHD_start_daemon_va (unsigned int options,
int use_pipe;
#ifndef HAVE_INET6
- if (0 != (options & MHD_USE_IPv6))
+ if (0 != (flags & MHD_USE_IPv6))
return NULL;
#endif
#ifndef HAVE_POLL_H
- if (0 != (options & MHD_USE_POLL))
+ if (0 != (flags & MHD_USE_POLL))
return NULL;
#endif
#if ! HTTPS_SUPPORT
- if (0 != (options & MHD_USE_SSL))
+ if (0 != (flags & MHD_USE_SSL))
return NULL;
#endif
if (NULL == dh)
@@ -2211,7 +2211,7 @@ MHD_start_daemon_va (unsigned int options,
memset (daemon, 0, sizeof (struct MHD_Daemon));
/* try to open listen socket */
#if HTTPS_SUPPORT
- if (0 != (options & MHD_USE_SSL))
+ if (0 != (flags & MHD_USE_SSL))
{
gnutls_priority_init (&daemon->priority_cache,
"NORMAL",
@@ -2219,7 +2219,7 @@ MHD_start_daemon_va (unsigned int options,
}
#endif
daemon->socket_fd = -1;
- daemon->options = (enum MHD_OPTION) options;
+ daemon->options = (enum MHD_OPTION) flags;
daemon->port = port;
daemon->apc = apc;
daemon->apc_cls = apc_cls;
@@ -2252,7 +2252,7 @@ MHD_start_daemon_va (unsigned int options,
return NULL;
}
#ifndef WINDOWS
- if ( (0 == (options & MHD_USE_POLL)) &&
+ if ( (0 == (flags & MHD_USE_POLL)) &&
(daemon->wpipe[0] >= FD_SETSIZE) )
{
#if HAVE_MESSAGES
@@ -2271,7 +2271,7 @@ MHD_start_daemon_va (unsigned int options,
daemon->nonce_nc_size = 4; /* tiny */
#endif
#if HTTPS_SUPPORT
- if (0 != (options & MHD_USE_SSL))
+ if (0 != (flags & MHD_USE_SSL))
{
daemon->cred_type = GNUTLS_CRD_CERTIFICATE;
}
@@ -2281,7 +2281,7 @@ MHD_start_daemon_va (unsigned int options,
if (MHD_YES != parse_options_va (daemon, &servaddr, ap))
{
#if HTTPS_SUPPORT
- if ( (0 != (options & MHD_USE_SSL)) &&
+ if ( (0 != (flags & MHD_USE_SSL)) &&
(NULL != daemon->priority_cache) )
gnutls_priority_deinit (daemon->priority_cache);
#endif
@@ -2299,7 +2299,7 @@ MHD_start_daemon_va (unsigned int options,
"Specified value for NC_SIZE too large\n");
#endif
#if HTTPS_SUPPORT
- if (0 != (options & MHD_USE_SSL))
+ if (0 != (flags & MHD_USE_SSL))
gnutls_priority_deinit (daemon->priority_cache);
#endif
free (daemon);
@@ -2314,7 +2314,7 @@ MHD_start_daemon_va (unsigned int options,
STRERROR (errno));
#endif
#if HTTPS_SUPPORT
- if (0 != (options & MHD_USE_SSL))
+ if (0 != (flags & MHD_USE_SSL))
gnutls_priority_deinit (daemon->priority_cache);
#endif
free (daemon);
@@ -2329,7 +2329,7 @@ MHD_start_daemon_va (unsigned int options,
"MHD failed to initialize nonce-nc mutex\n");
#endif
#if HTTPS_SUPPORT
- if (0 != (options & MHD_USE_SSL))
+ if (0 != (flags & MHD_USE_SSL))
gnutls_priority_deinit (daemon->priority_cache);
#endif
free (daemon->nnc);
@@ -2339,7 +2339,7 @@ MHD_start_daemon_va (unsigned int options,
#endif
/* Thread pooling currently works only with internal select thread model */
- if ( (0 == (options & MHD_USE_SELECT_INTERNALLY)) &&
+ if ( (0 == (flags & MHD_USE_SELECT_INTERNALLY)) &&
(daemon->worker_pool_size > 0) )
{
#if HAVE_MESSAGES
@@ -2350,7 +2350,7 @@ MHD_start_daemon_va (unsigned int options,
}
#ifdef __SYMBIAN32__
- if (0 != (options & (MHD_USE_SELECT_INTERNALLY | MHD_USE_THREAD_PER_CONNECTION)))
+ if (0 != (flags & (MHD_USE_SELECT_INTERNALLY | MHD_USE_THREAD_PER_CONNECTION)))
{
#if HAVE_MESSAGES
MHD_DLOG (daemon,
@@ -2363,14 +2363,14 @@ MHD_start_daemon_va (unsigned int options,
(0 == (daemon->options & MHD_USE_NO_LISTEN_SOCKET)) )
{
/* try to open listen socket */
- if ((options & MHD_USE_IPv6) != 0)
+ if ((flags & MHD_USE_IPv6) != 0)
socket_fd = create_socket (PF_INET6, SOCK_STREAM, 0);
else
socket_fd = create_socket (PF_INET, SOCK_STREAM, 0);
if (-1 == socket_fd)
{
#if HAVE_MESSAGES
- if (0 != (options & MHD_USE_DEBUG))
+ if (0 != (flags & MHD_USE_DEBUG))
MHD_DLOG (daemon,
"Call to socket failed: %s\n",
STRERROR (errno));
@@ -2380,7 +2380,7 @@ MHD_start_daemon_va (unsigned int options,
if ((SETSOCKOPT (socket_fd,
SOL_SOCKET,
SO_REUSEADDR,
- &on, sizeof (on)) < 0) && ((options & MHD_USE_DEBUG) != 0))
+ &on, sizeof (on)) < 0) && ((flags & MHD_USE_DEBUG) != 0))
{
#if HAVE_MESSAGES
MHD_DLOG (daemon,
@@ -2391,7 +2391,7 @@ MHD_start_daemon_va (unsigned int options,
/* check for user supplied sockaddr */
#if HAVE_INET6
- if (0 != (options & MHD_USE_IPv6))
+ if (0 != (flags & MHD_USE_IPv6))
addrlen = sizeof (struct sockaddr_in6);
else
#endif
@@ -2399,7 +2399,7 @@ MHD_start_daemon_va (unsigned int options,
if (NULL == servaddr)
{
#if HAVE_INET6
- if (0 != (options & MHD_USE_IPv6))
+ if (0 != (flags & MHD_USE_IPv6))
{
memset (&servaddr6, 0, sizeof (struct sockaddr_in6));
servaddr6.sin6_family = AF_INET6;
@@ -2423,7 +2423,7 @@ MHD_start_daemon_va (unsigned int options,
}
daemon->socket_fd = socket_fd;
- if (0 != (options & MHD_USE_IPv6))
+ if (0 != (flags & MHD_USE_IPv6))
{
#ifdef IPPROTO_IPV6
#ifdef IPV6_V6ONLY
@@ -2448,7 +2448,7 @@ MHD_start_daemon_va (unsigned int options,
if (-1 == BIND (socket_fd, servaddr, addrlen))
{
#if HAVE_MESSAGES
- if (0 != (options & MHD_USE_DEBUG))
+ if (0 != (flags & MHD_USE_DEBUG))
MHD_DLOG (daemon,
"Failed to bind to port %u: %s\n",
(unsigned int) port,
@@ -2461,7 +2461,7 @@ MHD_start_daemon_va (unsigned int options,
if (LISTEN (socket_fd, 20) < 0)
{
#if HAVE_MESSAGES
- if (0 != (options & MHD_USE_DEBUG))
+ if (0 != (flags & MHD_USE_DEBUG))
MHD_DLOG (daemon,
"Failed to listen for connections: %s\n",
STRERROR (errno));
@@ -2476,10 +2476,10 @@ MHD_start_daemon_va (unsigned int options,
}
#ifndef WINDOWS
if ( (socket_fd >= FD_SETSIZE) &&
- (0 == (options & MHD_USE_POLL)) )
+ (0 == (flags & MHD_USE_POLL)) )
{
#if HAVE_MESSAGES
- if ((options & MHD_USE_DEBUG) != 0)
+ if ((flags & MHD_USE_DEBUG) != 0)
MHD_DLOG (daemon,
"Socket descriptor larger than FD_SETSIZE: %d > %d\n",
socket_fd,
@@ -2514,7 +2514,7 @@ MHD_start_daemon_va (unsigned int options,
#if HTTPS_SUPPORT
/* initialize HTTPS daemon certificate aspects & send / recv functions */
- if ((0 != (options & MHD_USE_SSL)) && (0 != MHD_TLS_init (daemon)))
+ if ((0 != (flags & MHD_USE_SSL)) && (0 != MHD_TLS_init (daemon)))
{
#if HAVE_MESSAGES
MHD_DLOG (daemon,
@@ -2527,8 +2527,8 @@ MHD_start_daemon_va (unsigned int options,
goto free_and_fail;
}
#endif
- if ( ( (0 != (options & MHD_USE_THREAD_PER_CONNECTION)) ||
- ( (0 != (options & MHD_USE_SELECT_INTERNALLY)) &&
+ if ( ( (0 != (flags & MHD_USE_THREAD_PER_CONNECTION)) ||
+ ( (0 != (flags & MHD_USE_SELECT_INTERNALLY)) &&
(0 == daemon->worker_pool_size)) ) &&
(0 == (daemon->options & MHD_USE_NO_LISTEN_SOCKET)) &&
(0 != (res_thread_create =
@@ -2671,7 +2671,7 @@ thread_failed:
pthread_mutex_destroy (&daemon->nnc_lock);
#endif
#if HTTPS_SUPPORT
- if (0 != (options & MHD_USE_SSL))
+ if (0 != (flags & MHD_USE_SSL))
gnutls_priority_deinit (daemon->priority_cache);
#endif
free (daemon);
diff --git a/src/daemon/digestauth.c b/src/daemon/digestauth.c
@@ -736,6 +736,9 @@ MHD_digest_auth_check (struct MHD_Connection *connection,
* @param connection The MHD connection structure
* @param realm the realm presented to the client
* @param opaque string to user for opaque value
+ * @param response reply to send; should contain the "access denied"
+ * body; note that this function will set the "WWW Authenticate"
+ * header and that the caller should not do this
* @param signal_stale MHD_YES if the nonce is invalid to add
* 'stale=true' to the authentication header
* @return MHD_YES on success, MHD_NO otherwise
diff --git a/src/daemon/internal.c b/src/daemon/internal.c
@@ -111,6 +111,7 @@ MHD_DLOG (const struct MHD_Daemon *daemon, const char *format, ...)
*
* @param cls closure (use NULL)
* @param connection handle to connection, not used
+ * @param val value to unescape (modified in the process)
* @return length of the resulting val (strlen(val) maybe
* shorter afterwards due to elimination of escape sequences)
*/
diff --git a/src/daemon/internal.h b/src/daemon/internal.h
@@ -57,14 +57,14 @@ extern void *mhd_panic_cls;
/**
* Trigger 'panic' action based on fatal errors.
*
- * @param error message (const char *)
+ * @param msg error message (const char *)
*/
#define MHD_PANIC(msg) mhd_panic (mhd_panic_cls, __FILE__, __LINE__, msg)
#else
/**
* Trigger 'panic' action based on fatal errors.
*
- * @param error message (const char *)
+ * @param msg error message (const char *)
*/
#define MHD_PANIC(msg) mhd_panic (mhd_panic_cls, __FILE__, __LINE__, NULL)
#endif
@@ -156,6 +156,7 @@ MHD_DLOG (const struct MHD_Daemon *daemon,
*
* @param cls closure (use NULL)
* @param connection handle to connection, not used
+ * @param val value to unescape (modified in the process)
* @return length of the resulting val (strlen(val) maybe
* shorter afterwards due to elimination of escape sequences)
*/
diff --git a/src/daemon/memorypool.c b/src/daemon/memorypool.c
@@ -81,6 +81,7 @@ struct MemoryPool
* Create a memory pool.
*
* @param max maximum size of the pool
+ * @return NULL on error
*/
struct MemoryPool *
MHD_pool_create (size_t max)
@@ -119,6 +120,8 @@ MHD_pool_create (size_t max)
/**
* Destroy a memory pool.
+ *
+ * @param pool memory pool to destroy
*/
void
MHD_pool_destroy (struct MemoryPool *pool)
@@ -135,6 +138,12 @@ MHD_pool_destroy (struct MemoryPool *pool)
/**
* Allocate size bytes from the pool.
+ *
+ * @param pool memory pool to use for the operation
+ * @param size number of bytes to allocate
+ * @param from_end allocate from end of pool (set to MHD_YES);
+ * use this for small, persistent allocations that
+ * will never be reallocated
* @return NULL if the pool cannot support size more
* bytes
*/
@@ -170,6 +179,7 @@ MHD_pool_allocate (struct MemoryPool *pool,
* allocation may be leaked until the pool is
* destroyed (and copying the data maybe required).
*
+ * @param pool memory pool to use for the operation
* @param old the existing block
* @param old_size the size of the existing block
* @param new_size the new size of the block
@@ -223,6 +233,7 @@ MHD_pool_reallocate (struct MemoryPool *pool,
* Clear all entries from the memory pool except
* for "keep" of the given "size".
*
+ * @param pool memory pool to use for the operation
* @param keep pointer to the entry to keep (maybe NULL)
* @param size how many bytes need to be kept at this address
* @return addr new address of "keep" (if it had to change)
diff --git a/src/daemon/memorypool.h b/src/daemon/memorypool.h
@@ -42,6 +42,7 @@ struct MemoryPool;
* Create a memory pool.
*
* @param max maximum size of the pool
+ * @return NULL on error
*/
struct MemoryPool *
MHD_pool_create (size_t max);
@@ -49,6 +50,8 @@ MHD_pool_create (size_t max);
/**
* Destroy a memory pool.
+ *
+ * @param pool memory pool to destroy
*/
void
MHD_pool_destroy (struct MemoryPool *pool);
@@ -57,6 +60,8 @@ MHD_pool_destroy (struct MemoryPool *pool);
/**
* Allocate size bytes from the pool.
*
+ * @param pool memory pool to use for the operation
+ * @param size number of bytes to allocate
* @param from_end allocate from end of pool (set to MHD_YES);
* use this for small, persistent allocations that
* will never be reallocated
@@ -77,6 +82,7 @@ MHD_pool_allocate (struct MemoryPool *pool,
* allocation may be leaked until the pool is
* destroyed (and copying the data maybe required).
*
+ * @param pool memory pool to use for the operation
* @param old the existing block
* @param old_size the size of the existing block
* @param new_size the new size of the block
@@ -95,6 +101,7 @@ MHD_pool_reallocate (struct MemoryPool *pool,
* Clear all entries from the memory pool except
* for "keep" of the given "size".
*
+ * @param pool memory pool to use for the operation
* @param keep pointer to the entry to keep (maybe NULL)
* @param size how many bytes need to be kept at this address
* @return addr new address of "keep" (if it had to change)
diff --git a/src/daemon/postprocessor.c b/src/daemon/postprocessor.c
@@ -71,19 +71,19 @@ enum RN_State
RN_Inactive = 0,
/**
- * If the next character is '\n', skip it. Otherwise,
+ * If the next character is CR, skip it. Otherwise,
* just go inactive.
*/
RN_OptN = 1,
/**
- * Expect '\r\n' (and only '\r\n'). As always, we also
- * expect only '\r' or only '\n'.
+ * Expect LFCR (and only LFCR). As always, we also
+ * expect only LF or only CR.
*/
RN_Full = 2,
/**
- * Expect either '\r\n' or '--\r\n'. If '--\r\n', transition into dash-state
+ * Expect either LFCR or '--'LFCR. If '--'LFCR, transition into dash-state
* for the main state machine
*/
RN_Dash = 3,
@@ -221,9 +221,9 @@ struct MHD_PostProcessor
enum PP_State state;
/**
- * Side-state-machine: skip '\r\n' (or just '\n').
+ * Side-state-machine: skip LRCR (or just LF).
* Set to 0 if we are not in skip mode. Set to 2
- * if a '\r\n' is expected, set to 1 if a '\n' should
+ * if a LFCR is expected, set to 1 if a CR should
* be skipped if it is the next character.
*/
enum RN_State skip_rn;
@@ -256,22 +256,22 @@ struct MHD_PostProcessor
* specifically the parsing of the keys). A
* tiny value (256-1024) should be sufficient.
* Do NOT use 0.
- * @param ikvi iterator to be called with the parsed data
- * @param cls first argument to ikvi
+ * @param iter iterator to be called with the parsed data
+ * @param iter_cls first argument to iter
* @return NULL on error (out of memory, unsupported encoding),
* otherwise a PP handle
*/
struct MHD_PostProcessor *
MHD_create_post_processor (struct MHD_Connection *connection,
size_t buffer_size,
- MHD_PostDataIterator ikvi, void *cls)
+ MHD_PostDataIterator iter, void *iter_cls)
{
struct MHD_PostProcessor *ret;
const char *encoding;
const char *boundary;
size_t blen;
- if ((buffer_size < 256) || (connection == NULL) || (ikvi == NULL))
+ if ((buffer_size < 256) || (connection == NULL) || (iter == NULL))
mhd_panic (mhd_panic_cls, __FILE__, __LINE__, NULL);
encoding = MHD_lookup_connection_value (connection,
MHD_HEADER_KIND,
@@ -312,8 +312,8 @@ MHD_create_post_processor (struct MHD_Connection *connection,
return NULL;
memset (ret, 0, sizeof (struct MHD_PostProcessor) + buffer_size + 1);
ret->connection = connection;
- ret->ikvi = ikvi;
- ret->cls = cls;
+ ret->ikvi = iter;
+ ret->cls = iter_cls;
ret->encoding = encoding;
ret->buffer_size = buffer_size;
ret->state = PP_Init;
@@ -508,6 +508,15 @@ try_match_header (const char *prefix, char *line, char **suffix)
/**
*
* @param pp post processor context
+ * @param boundary boundary to look for
+ * @param blen number of bytes in boundary
+ * @param ioffptr set to the end of the boundary if found,
+ * otherwise incremented by one (FIXME: quirky API!)
+ * @param next_state state to which we should advance the post processor
+ * if the boundary is found
+ * @param next_dash_state dash_state to which we should advance the
+ * post processor if the boundary is found
+ * @return MHD_NO if the boundary is not found, MHD_YES if we did find it
*/
static int
find_boundary (struct MHD_PostProcessor *pp,
@@ -595,6 +604,8 @@ try_get_value (const char *buf,
* @param pp post processor context
* @param ioffptr set to how many bytes have been
* processed
+ * @param next_state state to which the post processor should
+ * be advanced if we find the end of the headers
* @return MHD_YES if we can continue processing,
* MHD_NO on error or if we do not have
* enough data yet
@@ -617,7 +628,7 @@ process_multipart_headers (struct MHD_PostProcessor *pp,
}
if (newline == pp->buffer_pos)
return MHD_NO; /* will need more data */
- if (newline == 0)
+ if (0 == newline)
{
/* empty line - end of headers */
pp->skip_rn = RN_Full;
@@ -652,6 +663,7 @@ process_multipart_headers (struct MHD_PostProcessor *pp,
* process accordingly.
*
* @param pp post processor context
+ * @param ioffptr incremented based on the number of bytes processed
* @param boundary the boundary to look for
* @param blen strlen(boundary)
* @param next_state what state to go into after the
@@ -707,7 +719,7 @@ process_value_to_boundary (struct MHD_PostProcessor *pp,
/* cannot check for boundary, process content that
we have and check again later; except, if we have
no content, abort (out of memory) */
- if ((newline == 0) && (pp->buffer_pos == pp->buffer_size))
+ if ((0 == newline) && (pp->buffer_pos == pp->buffer_size))
{
pp->state = PP_Error;
return MHD_NO;
@@ -745,23 +757,23 @@ process_value_to_boundary (struct MHD_PostProcessor *pp,
static void
free_unmarked (struct MHD_PostProcessor *pp)
{
- if ((pp->content_name != NULL) && (0 == (pp->have & NE_content_name)))
+ if ((NULL != pp->content_name) && (0 == (pp->have & NE_content_name)))
{
free (pp->content_name);
pp->content_name = NULL;
}
- if ((pp->content_type != NULL) && (0 == (pp->have & NE_content_type)))
+ if ((NULL != pp->content_type) && (0 == (pp->have & NE_content_type)))
{
free (pp->content_type);
pp->content_type = NULL;
}
- if ((pp->content_filename != NULL) &&
+ if ((NULL != pp->content_filename) &&
(0 == (pp->have & NE_content_filename)))
{
free (pp->content_filename);
pp->content_filename = NULL;
}
- if ((pp->content_transfer_encoding != NULL) &&
+ if ((NULL != pp->content_transfer_encoding) &&
(0 == (pp->have & NE_content_transfer_encoding)))
{
free (pp->content_transfer_encoding);
@@ -774,6 +786,9 @@ free_unmarked (struct MHD_PostProcessor *pp)
* Decode multipart POST data.
*
* @param pp post processor context
+ * @param post_data data to decode
+ * @param post_data_len number of bytes in 'post_data'
+ * @return MHD_NO on error,
*/
static int
post_process_multipart (struct MHD_PostProcessor *pp,
diff --git a/src/daemon/response.c b/src/daemon/response.c
@@ -158,6 +158,7 @@ MHD_del_response_header (struct MHD_Response *response,
/**
* Get all of the headers added to a response.
*
+ * @param response response to query
* @param iterator callback to call on each header;
* maybe NULL (then just count headers)
* @param iterator_cls extra argument to iterator
@@ -185,11 +186,13 @@ MHD_get_response_headers (struct MHD_Response *response,
/**
* Get a particular header from the response.
*
+ * @param response response to query
* @param key which header to get
* @return NULL if header does not exist
*/
const char *
-MHD_get_response_header (struct MHD_Response *response, const char *key)
+MHD_get_response_header (struct MHD_Response *response,
+ const char *key)
{
struct MHD_HTTP_Header *pos;
@@ -296,7 +299,7 @@ free_callback (void *cls)
*
* @param size size of the data portion of the response
* @param fd file descriptor referring to a file on disk with the data
- * @param off offset to start reading from in the file
+ * @param offset offset to start reading from in the file
* @return NULL on error (i.e. invalid arguments, out of memory)
*/
struct MHD_Response *MHD_create_response_from_fd_at_offset (size_t size,
diff --git a/src/daemon/test_daemon.c b/src/daemon/test_daemon.c
@@ -19,7 +19,7 @@
*/
/**
- * @file daemon_test.c
+ * @file test_daemon.c
* @brief Testcase for libmicrohttpd starts and stops
* @author Christian Grothoff
*/
diff --git a/src/daemon/test_postprocessor.c b/src/daemon/test_postprocessor.c
@@ -19,7 +19,7 @@
*/
/**
- * @file postprocessor_test.c
+ * @file test_postprocessor.c
* @brief Testcase for postprocessor
* @author Christian Grothoff
*/
diff --git a/src/daemon/test_postprocessor_large.c b/src/daemon/test_postprocessor_large.c
@@ -19,7 +19,7 @@
*/
/**
- * @file postprocessor_large_test.c
+ * @file test_postprocessor_large.c
* @brief Testcase with very large input for postprocessor
* @author Christian Grothoff
*/
diff --git a/src/examples/https_fileserver_example.c b/src/examples/https_fileserver_example.c
@@ -17,7 +17,7 @@
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
/**
- * @file https_server_example.c
+ * @file https_fileserver_example.c
* @brief a simple HTTPS file server using TLS.
*
* Usage :
diff --git a/src/examples/post_example.c b/src/examples/post_example.c
@@ -492,9 +492,9 @@ post_iterator (void *cls,
/**
* Main MHD callback for handling requests.
*
- *
* @param cls argument given together with the function
* pointer when the handler was registered with MHD
+ * @param connection handle identifying the incoming connection
* @param url the requested url
* @param method the HTTP method used ("GET", "PUT", etc.)
* @param version the HTTP version string (i.e. "HTTP/1.1")
@@ -508,7 +508,7 @@ post_iterator (void *cls,
* @param upload_data_size set initially to the size of the
* upload_data provided; the method must update this
* value to the number of bytes NOT processed;
- * @param con_cls pointer that the callback can set to some
+ * @param ptr pointer that the 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 PUT/POST operation
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
@@ -66,7 +66,7 @@
* "platform.h" in the MHD distribution). If you have done so, you
* should also have a line with "#define MHD_PLATFORM_H" which will
* prevent this header from trying (and, depending on your platform,
- * failing) to #include the right headers.
+ * failing) to include the right headers.
*/
#ifndef MHD_MICROHTTPD_H
@@ -1066,12 +1066,12 @@ typedef int
* @param apc_cls extra argument to apc
* @param dh handler called for all requests (repeatedly)
* @param dh_cls extra argument to dh
- * @param ... list of options (type-value pairs,
+ * @param ap list of options (type-value pairs,
* terminated with MHD_OPTION_END).
* @return NULL on error, handle to daemon on success
*/
struct MHD_Daemon *
-MHD_start_daemon_va (unsigned int options,
+MHD_start_daemon_va (unsigned int flags,
uint16_t port,
MHD_AcceptPolicyCallback apc, void *apc_cls,
MHD_AccessHandlerCallback dh, void *dh_cls,
@@ -1458,7 +1458,7 @@ MHD_create_response_from_fd (size_t size,
* @param fd file descriptor referring to a file on disk with the
* data; will be closed when response is destroyed;
* fd should be in 'blocking' mode
- * @param off offset to start reading from in the file;
+ * @param offset offset to start reading from in the file;
* Be careful! 'off_t' may have been compiled to be a
* 64-bit variable for MHD, in which case your application
* also has to be compiled using the same options! Read
@@ -1655,6 +1655,7 @@ int
MHD_del_response_header (struct MHD_Response *response,
const char *header, const char *content);
+
/**
* Get all of the headers (and footers) added to a response.
*
@@ -1702,14 +1703,14 @@ const char *MHD_get_response_header (struct MHD_Response *response,
* performance, use 32 or 64k (i.e. 65536).
* @param iter iterator to be called with the parsed data,
* Must NOT be NULL.
- * @param cls first argument to ikvi
+ * @param iter_cls first argument to iter
* @return NULL on error (out of memory, unsupported encoding),
* otherwise a PP handle
*/
struct MHD_PostProcessor *
MHD_create_post_processor (struct MHD_Connection *connection,
size_t buffer_size,
- MHD_PostDataIterator iter, void *cls);
+ MHD_PostDataIterator iter, void *iter_cls);
/**
* Parse and process POST data.
@@ -1818,9 +1819,13 @@ MHD_basic_auth_get_username_password (struct MHD_Connection *connection,
/**
* Queues a response to request basic authentication from the client
+ * The given response object is expected to include the payload for
+ * the response; the "WWW-Authenticate" header will be added and the
+ * response queued with the 'UNAUTHORIZED' status code.
*
* @param connection The MHD connection structure
* @param realm the realm presented to the client
+ * @param response response object to modify and queue
* @return MHD_YES on success, MHD_NO otherwise
*/
int
diff --git a/src/include/plibc/plibc.h b/src/include/plibc/plibc.h
@@ -18,7 +18,7 @@
*/
/**
- * @file include/plibc.h
+ * @file plibc.h
* @brief PlibC header
* @attention This file is usually not installed under Unix,
* so ship it with your application
diff --git a/src/testcurl/https/tls_test_common.c b/src/testcurl/https/tls_test_common.c
@@ -252,10 +252,13 @@ send_curl_req (char *url, struct CBC * cbc, const char *cipher_suite,
return CURLE_OK;
}
+
/**
* compile test file url pointing to the current running directory path
+ *
* @param url - char buffer into which the url is compiled
- * @return
+ * @param port port to use for the test
+ * @return -1 on error
*/
int
gen_test_file_url (char *url, int port)
diff --git a/src/testcurl/https/tls_test_common.h b/src/testcurl/https/tls_test_common.h
@@ -98,6 +98,14 @@ http_dummy_ahc (void *cls, struct MHD_Connection *connection,
const char *version, size_t *upload_data_size,
void **ptr);
+
+/**
+ * compile test file url pointing to the current running directory path
+ *
+ * @param url - char buffer into which the url is compiled
+ * @param port port to use for the test
+ * @return -1 on error
+ */
int gen_test_file_url (char *url, int port);
int
