httpd.h

picoos源码。The RTOS and the TCP/IP stack will be built automatically.

/*
 *  Copyright (c) 2004, Dennis Kuschel.
 *  All rights reserved. 
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met:
 *
 *   1. Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *   2. Redistributions in binary form must reproduce the above copyright
 *      notice, this list of conditions and the following disclaimer in the
 *      documentation and/or other materials provided with the distribution.
 *   3. The name of the author may not be used to endorse or promote
 *      products derived from this software without specific prior written
 *      permission. 
 *
 *  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
 *  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 *  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
 *  INDIRECT,  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 *  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 *  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 *  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 *  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 *  OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */

/**
 * @file    httpd.h
 * @author  Dennis Kuschel
 * @brief   HTTP demon for embedded devices
 *
 * This software is from http://mycpu.mikrocontroller.net.
 * Please send questions and bug reports to [e-mail].
 */

#ifndef _HTTPD_H_
#define _HTTPD_H_

#include "sys.h"

/** @defgroup httpd Embedded HTTP Demon *//** @{ */


/** define this to 1 to enable servlet support
 */
#ifndef HTTP_SERVLETS
#define HTTP_SERVLETS   1
#endif


#if HTTP_SERVLETS

/** Servlet object */
typedef  void*      SERVLET_t;

/** Function pointer to servlet function. */
typedef  sint_t (*SERVLETFUNC_t)(SERVLET_t slobj);

#define SLERR_OK            0
#define SLERR_FAIL          -1
#define SLERR_NEEDMEM       -2

#define SLERR_BADREQUEST    -3  /* 400 Bad Request */
#define SLERR_NOTFOUND      -4  /* 404 Not Found   */
#define SLERR_SERVER        -5  /* 500 Internal Server Error */
#define SLERR_CREATED       -6  /* 201 Created */
#define SLERR_ACCEPTED      -7  /* 202 ACCEPTED */
#define SLERR_PARTIAL       -8  /* 206 Partial Content */
#define SLERR_FORBIDDEN     -9  /* 403 Forbidden */
#define SLERR_TOOLARGE      -10 /* 413 Request Entity Too Large */
#define SLERR_UNAVAILABLE   -11 /* 503 Service Unavailable */
#define SLERR_BUSY          -12 /* 200 OK, but Server Busy */


/**
 * Servlet function: Create a new servlet object.
 * This function is used to create and add a new servlet
 * object to the http demon.
 * @param func          pointer to servlet function
 * @param filename      name of path and file that is overloaded
 *                      by the servlet
 * @return zero on success.
 * @sa hsl_destroy, hsl_getParameterByName
 */
sint_t hsl_create(SERVLETFUNC_t func, const char *filename);

/**
 * Servlet function: Destroy a servlet object.
 * The servlet object will be removed from the http demon.
 * @param func          pointer to the servlet function.
 * @return zero on success.
 * @sa hsl_create
 */
sint_t hsl_destroy(SERVLETFUNC_t func);

/**
 * Servlet function:
 * Get the value of a named parameter from the request URI.
 * @param slobj         pointer to the servlet object
 * @param name          name of the parameter to retrieve
 * @return Pointer to a zero terminated ascii string containing
 *         the parameter value.
 * @sa hsl_create
 */
char *hsl_getParameterByName(SERVLET_t *slobj, const char *name);

/**
 * Servlet function:
 * This function returns the own name (name of the servlet).
 * @param slobj         pointer to the servlet object
 * @return              pointer to the name of the servlet (read only)
 * @sa hsl_create
 */
char *hsl_getOwnName(SERVLET_t *slobj);

/**
 * Servlet function:
 * Request more memory for the output stream buffer.
 * Per default, one kilobyte (=1024 bytes) is reserved for the
 * output stream. If larger HTML pages shall be created, the
 * buffer size must be increased by calling this function from
 * within the servlet.
 * @param slobj         pointer to the servlet object
 * @param bufsize       bufsize
 * @return status code. If the status is not SLERR_OK, the
 *         servlet function MUST return this code to the http demon.
 *         The http demon will call the servlet function again
 *         when the requested memory is available.
 * @sa hsl_printf, hsl_getParameterByName, hsl_create
 */
sint_t hsl_setStreamBufSize(SERVLET_t *slobj, u32_t bufsize);

/**
 * Servlet function:
 * Print formatted to the stdout of the current servlet instance.
 * @param slobj         pointer to the servlet object
 * @param fmt           format string, followed by options
 * @return A positive value denoting the count of printed characters
 *         on success. A negative value is returned on error.
 * @sa hsl_setStreamBufSize, hsl_create
 */
sint_t hsl_printf(SERVLET_t *slobj, const char *fmt, ...);

/**
 * Servlet function:
 * This function returns a pointer to the servlets session memory.
 * @param slobj         pointer to the servlet object
 * @return The pointer to the session memory. If NULL is returned,
 *         no session is associated with the servlet. The servlet
 *         may call ::hsl_newSession to create a new session.
 * @sa hsl_newSession, hsl_destroySession, hsl_create
 */
void* hsl_getSession(SERVLET_t *slobj);

/**
 * Servlet function:
 * This function creates a new session.
 * A session is understood as a memory buffer where the servlet
 * can store its private data. The lifetime of a session is limmited,
 * it is removed automatically by the http demon when it timed out.
 * @param slobj         pointer to the servlet object
 * @param memsize       memory size of the session (in bytes)
 * @param timeout       lifetime of the session (in seconds)
 * @return On success, a pointer to the memory buffer of the session
 *         is returned. If this function fails, NULL is returned.
 *         If this happens, the servlet should return with SLERR_BUSY.
 * @sa hsl_getSession, hsl_destroySession, hsl_create
 */
void* hsl_newSession(SERVLET_t *slobj, u32_t memsize, u32_t timeout);

/**
 * Servlet function:
 * This function destorys a servlet session. It should be called when
 * the user logs out.
 * @param slobj         pointer to the servlet object
 * @return zero on success
 * @sa hsl_getSession, hsl_newSession, hsl_create
 */
sint_t hsl_destroySession(SERVLET_t *slobj);

/**
 * Servlet function:
 * Inserts the current session ID into a web formular. Creates the
 * string  '<input type="hidden" name="sid" value="xxxxxxxx">'
 * @param slobj         pointer to the servlet object
 * @return zero on success
 */
sint_t hsl_formAddSessionId(SERVLET_t *slobj);


#define HSL_LINK_RAW   0x00000001
#define HSL_LINK_SID   0x00000002
#define HSL_LINK_QM    0x80000000  /* internal, do not use */


/**
 * Servlet function:
 * Create a new link object. You must use this function in your servlet
 * if you wish to pass a session ID with a link back to your servlet.
 * Further, this function simplifies the creation of links with an
 * appended parameter list.
 * To create dynamic links, you need to call these functions in the
 * following order:
 *   ::hsl_linkCreate, ::hsl_linkAddStringVal, ::hsl_linkInsert
 *
 * @param slobj         pointer to the servlet object
 * @param url           the base url of the link (without parametes)
 *                      Note: If this parameter is set to NULL,
 *                            the filename of the servlet is inserted.
 * @param flags         bitmask of flags:
 *                       - HSL_LINK_RAW  create URL only, without
 *                                       link-tags( <a=href...> </a> )
 *                       - HSL_LINK_SID  append session ID to the link
 * @return zero on success
 * @sa hsl_linkAddStringVal, hsl_linkAddNumberVal, hsl_linkInsert,
 *     hsl_addSessionIdToForm
 */
sint_t hsl_linkCreate(SERVLET_t *slobj, const char* url, u32_t flags);

/**
 * Servlet function:
 * Add a string value to the parameter list of a link. The link
 * must have been created with ::hsl_linkCreate before this function
 * can be called.
 * @param slobj         pointer to the servlet object
 * @param name          name of the parameter
 * @param val           string value of the parameter
 * @return zero on success
 * @sa hsl_linkCreate, hsl_linkAddNumberVal, hsl_linkInsert
 */
sint_t hsl_linkAddStringVal(SERVLET_t *slobj, const char *name,
                            const char* val);

/**
 * Servlet function:
 * Add a decimal value to the parameter list of a link. The link
 * must have been created with ::hsl_linkCreate before this function
 * can be called.
 * @param slobj         pointer to the servlet object
 * @param name          name of the parameter
 * @param val           decimal value of the parameter
 * @return zero on success
 * @sa hsl_linkCreate, hsl_linkAddStringVal, hsl_linkInsert
 */
sint_t hsl_linkAddNumberVal(SERVLET_t *slobj, const char *name, u32_t val);

/**
 * Servlet function:
 * Insert a link that was created by ::hsl_linkCreate into the
 * dynamic html page.
 * @param slobj         pointer to the servlet object
 * @param linktext      Link text that is displayed to the user.
 *                      Note that this text may contain further
 *                      html commands. If the link was created
 *                      with the flag HSL_LINK_RAW, this parameter
 *                      is a don't care.
 * @return zero on success
 * @sa hsl_linkCreate, hsl_linkAddStringVal, hsl_linkAddNumberVal
 */
sint_t hsl_linkInsert(SERVLET_t *slobj, const char *linktext);

/**
 * Servlet function:
 * Add the session id as a hidden parameter to a form.
 * @param slobj         pointer to the servlet object
 * @return zero on success
 * @sa hsl_linkCreate
 */
sint_t hsl_addSessionIdToForm(SERVLET_t *slobj);


#endif


/**
 * This function starts the HTTP demon. The function
 * call does not return, so it is recommended to setup
 * a new task that executes this function.
 * To terminate the demon you can call the function ::httpd_stop.
 * @param rootDirectory    HTTP root directory name on the filesystem
 *                         (this is the '/' directory where the
 *                         initial index.html is stored).
 * @param maxServletMem    Maximum sum of bytes servlets may allocate
 *                         to buffer their output stream.
 *                         This parameter is a don't care if servlets
 *                         are disabled.
 * @param maxSessionMem    Maximum sum of bytes all servlets together
 *                         are allowed to allocate for their local
 *                         session memory.
 *                         If you use sessions, you may need to set
 *                         this value high, because much memory will
 *                         pend in sessions that are going to timeout.
 *                         This parameter is a don't care if servlets
 *                         are disabled.
 * @return zero on success.
 */
sint_t httpd_start(const char *rootDirectory,
                   u32_t maxServletMem, u32_t maxSessionMem);

/**
 * This function stoppes the HTTP demon.
 * Note that it takes a while (up to 1 second) until
 * this function returns.
 * @return zero on success.
 */
sint_t httpd_stop(void);

/**
 * This function can be used to test if the
 * HTTP demon task is still running.
 * @return  nonzero when the httpd is running.
 */
sint_t httpd_running(void);


/*@}*/
#endif /* _HTTPD_H_ */