Installation Sources of the SimpleHTTPd

Note:
This section may describe in a later version all aspects of the WWW server's sources. But for now, it only gives details about the WWW server loadable modules (module API) and the server's API for module routines. At the end, there is a description of how to write a module.

Basics

When the WWW server starts-up or re-initializes, it gets a list of modules to load. These modules must be located to a system path, where the operation system searches for them. Loadable modules are implemented as

Depending the operating system, some environment variables (LD_LIBRARY_PATH under Unix-style operating systems incl. HP/UX, DPATH in the CONFIG.SYS under IBM OS/2) or the registry (MS Windows NT) must be set.

The loadable module itself has various entry points for the stuff to be handled. Some entry points are necessary, some optional. The next section gives a description of the module's API.

topLoadable Module's API

The modules have an unique API (application programming interface) to the WWW server. There is a number of routines, which has to be implemented for working, and another number of other routines, which are optional. Further, a set of data structures is defined for information storage. Currently, the routines are:

modAbort()
Abort handler of the module.
modClear()
Module destructor, called on unload of module.
modConfig() (reserved for future use)
Configuration request for the module by the administration tool.
modHandler()
Handler for incoming requests.
modInit()
Initializer of the module, when module is loaded.
See below for a brief description of each routine.

modAbort()
int modAbort( PHttpConnection pConn,
              HttpModAbort fReason );
typeoptional
inputpConnconnection and request details of the request, which shall be aborted
fReason
  • HTTP_MOD_ABORT_UNKNOWN = unknown reason why to abort connection
  • HTTP_MOD_TIMEOUT = request timed out
  • HTTP_MOD_CONNECTION_LOST = connection channel got lost
  • HTTP_MOD_SHUTDOWN = WWW server is going down
  • HTTP_MOD_CLOSE_CHANNEL = channel is being closed, perform any per-connection handling (see SSL)
returnint
  • == 0 : abort successfully completed
  • < 0 : abort failed due to errors
The abort handler is called by the main process of the WWW server in order to terminate a connection due to an error condition or server shutdown. Please note, that the process or thread ID of the call to this routine may vary from the one that is handling the request! Also note, that an returned error does not delay a server shutdown or the abort process!

modClear()
int modClear( void );
typeoptional
input-
returnint
  • == 0 : module has been cleared successfully
  • < 0 : module cleared with error(s)
This routine is called by the main server process to tell a module that it'll be unloaded. This routine is also called, when the server re-initializes itself after a configuration change. The module itself does not need to remove itself from memory - this is done by the WWW server. But this function call is provided in order to free ressources allocated by the initialization routine of the module.

modConfig()
int modConfig( PHttpConnection pConn,
               PTwoWayLinkedList *pCfg );
typeoptional
inputpConnconnection and request details of the request
pCfgtwo-way linked list with parameters, the module has stored within the server's configuration data area.
returnint
  • == 0 : module has been configured successfully
  • == 1 : module has no configuration handler
  • < 0 : module configured with error(s)
This routine provides modules with the ability of handling their own configuration data. Each module has its own area within the server's configuration data area. When a module is initialized (see modInit()), it either gets this data or may set new (default) values. These datas are given to modConfig() by the pCfg parameter. The data may be displayed. New data is sent back to the WWW server by using a HTML form and HTTP method GET or POST (i.e. <form action="..." method="GET"> ... </form> or <form action="..." method="POST"> ... </form>).
Because it is too difficult to explain it here, have a look at the MOD_test sample module program.
Note: A module may refuse a configuration request be returning a value of +1. The administration tool then returns a note, that the module does not have a configuration entry - same, as if modConfig() wouldn't be implemented.

modHandler()
int modHandler( PHttpConnection pConn );
typemust be implemented!
inputpConnconnection and request details of the request, which shall be aborted
returnint
  • == 0 : request processed with no errors, WWW server returns HTTP_RC_OKAY (code 200)
  • < 0 : module internal error, WWW server returns HTTP_RC_INTERNAL_ERROR (code 500)
  • > 0 : module returns an individual error, the return code is any HTTP return code
The handler routine is the main entry of a module. It processes an incoming request. The main WWW server process starts on each incoming request a new process (Unix) or thread (Win32, OS/2), which then results in a call to this routine, if the path maps to this module. The module the takes control over the request handling. For proper completion, after successful or unsuccessful processing of the request, the control must be returned to the WWW server - no exit() calls!

modInit()
int modInit( PHttpRoutines pRoutines,
             PTwoWayLinkedList *pCfg,
             int fNew );
typeoptional
inputpRoutines list of entry points of routines within the WWW server for the module. This list is a easy way of accessing public routines of the WWW server, without having the need of extracting them to a separate link-library, that has to be loaded by WWW server and module(s).
pCfgtwo-way linked list of configuration data for this module. You may use the LinkedList...() calls of the WWW server API for processing.
fNewsignal for the module, that a previous configuration of this module cannot be found. If fNew is set unequal 0, the module should set the defaults for its configuration.
returnint
  • == 0 : module successfully initialized
  • < 0 : module could not be initialized and may not be used
The module initializer may request ressources, which may then be used when handling requests. Configuration data is send by the WWW server. If there was no previous configuration and fNew != 0 is set, the module should initialize its configuration by the defaults. The WWW server then automatically stores this (default) configuration for further initialization calls. Online configuration shall be done via the modConfig() routine.

topWWW server's API for module routines

HttpConnection, PHttpConnection
typedef struct s_HttpConnection {
        PHttpServer      psServer;
        int (PROC_CALL_PTR pTCPsend)(
                struct s_HttpConnection *pConn,
                unsigned char *psz,
                int cb
        );
        int (PROC_CALL_PTR pTCPrecv)(
                struct s_HttpConnection *pConn,
                unsigned char *psz,
                int cb
        );
        int              iCommSocket;
        int              iPID;
        int              iTimeOut;
        int              iReadIdx;
        int              iWriteIdx;
        int              cLastChar;
        unsigned char    szBuffer[8192];
        unsigned char    szTemp[8192];
        char             szRemoteAddr[32];
        char             szRemoteHost[64];
        PTwoWayLinkedList pHttpSSLInfo;
        PTwoWayLinkedList pHttpCallHdr;
        HttpReqMethod    fReqMethod;
        int              fReqHttpVersion;
        unsigned long    fReqInfo;
        unsigned char   *pszAuthScheme;
        unsigned char   *pszAuthUser;
        unsigned char   *pszAuthPass;
        unsigned char   *pszLocation;
        unsigned char   *pszPath;
        unsigned char   *pszPathInfo;
        unsigned char   *pszQueryString;
        unsigned long    cbContentLength;
        unsigned long    cbContentRead;
        PTwoWayLinkedList pHttpRespHdr;
        int (PROC_CALL_PTR modAbort)(
                struct s_HttpConnection *pConn,
                HttpModAbort fReason
        );
        void            *pSSL;
        void            *psZ;
        void            *pZBuffer;
        unsigned long    ulZCRC32;
} HttpConnection, *PHttpConnection;
memberpurpose
psServerpointer to server structure HttpServer.
pTCPsend()either NULL, if default TCP/IP sending routine should be used, or pointer to a TCP/IP sending routine (is used by the SSL part of the WWW server).
pTCPrecv()either NULL, if default TCP/IP receiving routine should be used, or pointer to a TCP/IP receiving routine (is used by the SSL part of the WWW server).
iCommSocketsocket of current request.
iPIDprocess or thread ID of handler routine for the current request.
iTimeOutcurrent time-out in seconds, if this counter hits 0, a time-out is detected.
iReadIdx, iWriteIdxused internally by HttpRead() and HttpWrite().
cLastChar
szBuffer
szTempused by HttpPrintf(), but may also be used for personal purposes (temporary data storage).
szRemoteAddrIP address of requester.
szRemoteHosthost name of requester.
pHttpSSLInfotwo-way linked list with SSL info about the current connection. The list will only be filled, when fReqInfo has bit HTTP_REQ_SSL_ACTIVE set!
pHttpCallHdrtwo-way linked list with HTTP header of incoming request.
fReqMethodHTTP request method.
fReqHttpVersionversion of incoming HTTP request header, main version ist stored in 10s, minor version in 1s. HTTP version HTTP/1.0 is stored as 10.
fReqInfoa bit-wise coded data area, where informations concerning the request and its handling is stored. These bits are defined:
  • HTTP_REQ_KEEP_ALIVE = request for keeping the connection alive after processing the current request detected. Set by WWW server.
  • HTTP_REQ_REUSE_CHANNEL = answer to the WWW server on HTTP_REQ_KEEP_ALIVE. If set, the channel is not closed, but kept alive.
  • HTTP_REQ_GZIP_ACTIVE = set, when on-the-fly compression for the response is enabled (gzip compression).
  • HTTP_REQ_SSL_ACTIVE = set, when SSL online encryption/decryption takes place, i.e. a SSL connection is used.
  • HTTP_REQ_ERROR = error during processing of the request. This aborts HTTP_REQ_REUSE_CHANNEL.
  • HTTP_RESP_HEADER_SENT = response header has been sent.
pszAuthSchemeif not set NULL, references name of authorization scheme.
pszAuthUserif set, specfies name of user.
pszAuthPassif set, (decrypted) password of authorized user. Note: If the authorization is resolved by the WWW server (i.e. an authorization scheme is set within the WWW server's configuration), the original password is hidden and only a single '*' is set instead of it.
pszLocationURI of request.
pszPathresolved path of the request, e.g. the local system's path to the object.
pszPathInfoif set, points to additional path informations within pszPath.
pszQueryStringif query data is given in the URI, this pointer is set on it.
cbContentLengthif set to a value greater 0, there is pending data, which may be read via HttpRead().
cbContentReadused by HttpRead() in order to determine, how many bytes were already read.
modAbort()pointer to abort handler of the module if existing. Used by the abort and time-out handler of the WWW server.
pSSLpointer to SSL specific data - this entry is not intended for user purposes.
psZpointer to on-the-fly data compression information block.
pZBufferpointer to on-the-fly data compression Z buffer.
ulZCRC32CRC-32 value on un-compressed data.

HttpProtocol, PHttpProtocol
typedef enum e_HttpProtocol { ... } HttpProtocol,
                                  *PHttpProtocol;
valuemeaning
HTTP_UNKNOWN_PROTOCOL unknown transfer protocol
HTTP_FTPfile transfer protocol (FTP)
HTTP_HTTPhypertext transfer protocol (HTTP)
HTTP_HTTPShypertext transfer protocol over secure socket layer (HTTP over SSL)

HttpReqMethod
typedef enum e_HttpReqMethod { ... } HttpReqMethod;
valuemeaning
HTTP_UNKNOWN_METHOD HTTP method not known
HTTP_GETHTTP request method for getting a document - mostly used on WWW servers for getting HTML pages.
HTTP_HEADHTTP request for header information on a document (size, type, etc.), without transfer of the data.
HTTP_POSTHTTP method for sending data to a WWW server - often used on HTML forms. Used for transfering more data than possible by HTTP_GET.
HTTP_PUTlike HTTP_POST.
HTTP_DELETEHTTP method for deleting a data ressource.
HTTP_LINKHTTP method for creating a link to a document.
HTTP_UNLINKHTTP method for deleting a link on a document.

HttpRoutines, PHttpRoutines
typedef struct s_HttpRoutines {
        /* ... */
} HttpRoutines, *PHttpRoutines;
Used by HttpInit() within a loadable module for initializing an internal list of WWW server API routines. The above mentioned routines are accessible via macros defined in include/http.h and the internal list.

HttpServer, PHttpServer
typedef struct s_HttpServer {
        int              fSched;
        int              cbConnections;
        int              iTcpSocket;
        int              iTcpSSLSocket;
        int              iPort;
        int              iSSLPort;
        char             szLocalAddr[32];
        char             szLocalHost[64];
        char             szAdmin[64];
} HttpServer, *PHttpServer;
memberpurpose
fSchedstatus of background scheduler, is either
  • -1 = scheduler aborting in progress,
  • 0 = scheduler stopped, or
  • +1 = scheduler running.
cbConnectionsnumber of open connections to the WWW server
  • >= 0 = number of open connections,
  • == -1 = shutdown in progress.
iTcpSocketmain socket, where WWW server waits for incoming requests.
iTcpSocketSSL socket, where WWW server waits for incoming SSL requests (0 = not available).
iPortport number of TCP/IP port of WWW server.
iSSLPortport number of TCP/IP port of WWW SSL server (0 = not available).
szLocalAddrIP address of WWW server
szLocalHosthost name of WWW server
szAdmineMail address of WWW server's administrator

HttpSrvLaunch, PHttpSrvLaunch
typedef struct s_HttpSrvLaunch {
        int              iDay;
        int              iHour;
        int              iMin;
        void (* PROC_CALL pProc)(void *pArg);
        void            *pArg;
} HttpSrvLaunch, *PHttpSrvLaunch;
memberpurpose
iDayday of year/week, to launch application, these values are possible:
  • -1 = launch every day
  • 0 .. 365 = launch at specified day of year, Jan. 1st = 0
  • 400, 401 .. 406 = launch every sunday, monday, ..., saturday
iHourhour to launch application, with -1 = every hour and 0 .. 23 = given hour.
iMinminute to launch application, with -1 = every minute and 0 .. 59 = given minute.
pProcif set unequal NULL, this represents a pointer to the procedure to be launched at the given date or interval.
pArgoptional parameter on call to pProc.

TwoWayLinkedList, PTwoWayLinkedList
typedef struct s_TwoWayLinkedList {
        unsigned char             *pszText;
        struct s_TwoWayLinkedList *pPrev,
                                  *pNext;
} TwoWayLinkedList, *PTwoWayLinkedList;
memberpurpose
pszTexttext stored at this element.
pPrevpointer to previous element or NULL if this is the first element in the list.
pNextpointer to next element or NULL if this is the last element in the list.
Note:
You may use the List...() for processing two-way linked lists.

Definitions
definitiondescription
HTTP_REQ_...used on HttpConnection.fReqInfo. See there for details.
-HTTP response codes
HTTP_RC_CONTINUE100continue with request
HTTP_RC_OK200request completed sucessfully
HTTP_RC_MULTIPLE_CHOICES300URI fits more than one local object
HTTP_RC_MOVED_PERMANENTLY301URI is no longer valid, use returned one instead
HTTP_RC_MOVED_TEMPORARILY302URI is currently not valid, use returned one instead
HTTP_RC_BAD_REQUEST400bad request (format)
HTTP_RC_UNAUTHORIZED401un-authorized access to a protected ressource
HTTP_RC_PAYMENT_REQUIRED402payment is required for access
HTTP_RC_FORBIDDEN403access to ressource is forbidden
HTTP_RC_NOT_FOUND404ressource not found
HTTP_RC_METHOD_NOT_ALLOWED405invalid (or not-allowed) HTTP request method
HTTP_RC_REQUEST_TIMEOUT408request timed out prior getting all request data
HTTP_RC_CONFLICT409conflicting situation
HTTP_RC_GONE410WWW server has gone
HTTP_RC_LENGTH_REQUIRED411no content length given on request with HTTP method POST or PUT
HTTP_RC_SSL_REQUIRED499 (SimpleHTTPd-specific error code) a SSL connection is necessary for access to this information
HTTP_RC_INTERNAL_ERROR500internal WWW server error
HTTP_RC_NOT_IMPLEMENTED501not implemented feature or function requested
HTTP_RC_BAD_GATEWAY502gateway (like common gateway interface - CGI) did not respond correctly
HTTP_RC_SERVICE_UNAVAILABLE503service is not available
HTTP_RC_GATEWAY_TIME_OUT504while waiting for the response to a request, there was a time-out situation on the gateway interface (e.g. CGI)
HTTP_RC_UNSUPPORTED_VERSION505the given HTTP request version is not supported

HttpAdmGetSequence()
unsigned char * HttpAdmGetSequence( void );
input-
returnu. char *
  • == NULL : error
  • != NULL : string with sequence number
returns the currently valid sequence number, which has to be specified on configuration changes (see modConfig(), too).
Note: Was first introduced in shttpd V 0.2.

HttpBase64Decode()
unsigned char * HttpBase64Decode(
        unsigned char *pszBase64 );
inputpszBase64string with Base-64 encoded data
returnu. char *
  • == NULL : error during decode
  • != NULL : string to decoded data
decodes Base-64 encoded data and returns it as string, which is duplicated via strdup(). I.e. you have to free the memory associated with the returned pointer!

HttpCheckConns()
int HttpCheckConns( void );
inputnone
returnint
  • >= 0 : number of open connections
  • == -1 : shutdown in progress
returns the number of currently open connections to the WWW server. If the WWW server is being shut down, -1 is returned instead.

HttpInit()
void HttpInit( void );
inputnone
returnnone
Initializes the list of WWW server routines. Must be called at first in modInit().

HttpGetChar()
int HttpGetChar( PHttpConnection pConn );
inputpConndata structure containing information about the incoming request
returnint
  • == 0..255 : next character as ASCII / ANSI Latin-1 code
  • == 256 : end of data reached (EOF)
  • == -1 : invalid parameter (NULL pointer)
  • == -2 : time-out during reading
  • == -3 : communication error
returns the next character within the HTTP request's body.

HttpGetHttpErrorText()
unsigned char *HttpGetHttpErrorText( int iHttpRC );
inputiRCHTTP return code, for which an error text should be returned
returnunsigned char *
  • == NULL : internal error
  • != NULL : pointer to error text message for this HTTP return code
returns an error text for the given HTTP return code.
Notes:
- was first introduced in shttpd V 0.3.

HttpGetLine()
int HttpGetLine( PHttpConnection pConn,
                 unsigned char *pszBuffer,
                 int cbBuffer );
inputpConndata structure containing information about the incoming request
pszBufferbuffer, where to write the data to
cbBuffermax. number of bytes within pszBuffer
returnint
  • >= 0 : number of bytes read
  • == -1 : invalid parameter (NULL pointer)
  • == -2 : time-out during reading
  • == -3 : communication error
reads the next sequence of characters within the HTTP request's body as if it were a line, i.e. up to the occurrence of a LF, CR or CR+LF (\n = 0x10, \r = 0x13, \r\n = 0x13, 0x10) sequence. The sequence is also copied to the buffer, that then is zero (\0 = 0x00 = NUL) terminated.

HttpGetPathToBin()
int HttpGetPathToBin( unsigned char *pszPath,
                      int cbPath );
inputpszPathpointer to string variable, that shall obtain the path
cbPathmax. number of bytes within pszPath
returnint
  • == 0 : okay
  • == -1 : invalid parameter (NULL pointer)
  • == -2 : could not get path
returns the directory, where the WWW server binary is located. Modules may use this API call in order to put their own configuration and data files in this central directory.
Notes:
- was first introduced in shttpd V 0.3.

HttpGetServerInternalData()
PHttpServer HttpGetServerInternalData( void );
inputnone
returnPHttpServer
  • != NULL : okay, pointer to internal HttpServer structure
  • == NULL : no access to internal data is possible
returns a pointer to the internal HttpServer structure.
Notes:
- was first introduced in shttpd V 0.6.

HttpLog()
int HttpLog( PHttpConnection pConn,
             ... );
inputpConndata structure containing information about the incoming request
...string with format data and additional parameters, like printf()
returnint
  • >= 0 : number of bytes written
  • == -1 : invalid parameter (NULL pointer)
  • == -2 : error during writing
writes out the string to the logging facility.

HttpParseQueryStr()
int HttpParseQueryStr( unsigned char **ppszQueryStr,
                       unsigned char *pszBuffer,
                       unsigned long  cbBuffer );
inputppszQueryStrpointer to pointer with query string
pszBufferbuffer where to write parsed data
cbBuffermax. buffer length in bytes
returnint
  • > cbBuffer : data parsed partially, but buffer overload
  • == cbBuffer : data parsed successfully, buffer full
  • > 0 : data parsed, number of bytes read
  • == 0 : end of data reached, no more data
  • == -1 : invalid parameter (NULL pointer)
  • == -2 : input data contains invalid data (binary stuff)
  • == -3 : parsing error
parses a given query string and move ppszQueryStr to the next part of the query string to be parsed, so that sub-sequent calls to this routine parse the entire query string. The data in the query string is translated while parsed. See these notes:
  1. valid characters are ANSI 0x20 .. 0xFF (ISO 8859-1, Latin-1)
  2. '&' is used as divider between data blocks, the functions returns at such a character. Sub-sequent calls may be used, to parse the hole input data - the end is marked by a return value of 0 (zero).
  3. '%XX' is treated as hexadecimal expression for a character - all codes %05 (\t), %0A (\n), %0D (\r), between %20 and %FF are valid. All others are invalid and lead to error code -2 (binary data).
  4. '+' is treated as replacement character for ' ' (space, 0x20).
  5. It is recomended to decode the following symbols by the hexedecimal expression (see above two points):
    '
    ' ' --> '+' '%' --> '%25'
    '&' --> '%26' '+' --> '%2B'
    '/' --> '%2F
  6. Parsing is done until a '&' is reached (see above), the end of the input data is reached, or no more space is left in the output buffer (which will result in a return == cbBuffer + 1, if parsing had to be aborted).
  7. The pointer for reading is moved to behind '&' (see above), is left on the teminating character '\0' or on the character, on which the the error occurred.

HttpParseURL()
int HttpParseURL( unsigned char *pszURL,
                  PHttpProtocol  pfProtocol,
                  unsigned char *pszHost,
                  unsigned long  cbHost,
                  unsigned int  *piPort,
                  unsigned char *pszPath,
                  unsigned long cbPath );
input pszURLURL to be parsed
pfProtocol where to store the protocol info
pszHostwhere to store the remote host
cbHostmax. length for remote host info
piPortwhere to store the IP port number
pszPathwhere to store the other stuff
cbPathmax. length for other stuff
returnint
  • == 0 : okay, successfully parsed
  • == -1 : parameter error
parses the given URL pszURL of the form <protocol>://<host>:<port>/<path> and returns information about the protocol, host, used TCP/IP port and path (which includes all other stuff, too). Parameters not found will not be set, i.e. if no protocol is specified, the variable referenced by pfProtocol remains unchanged! So if default values have to be set, they have to be set prior calling HttpParseURL(). That also means, that you may use this call subsequently - lets say you first parse http://www.test.net/path/abc and afterwards you parse https:def, you will receive as host www.test.net and as path /path/def (if there is no absolute path given in the URL, the routine adds the relative path to the end of the old path setting).
Notes:
- was first introduced in shttpd V 0.2.
- all parameters except pszURL may be set NULL
- special characters (space, \n, \r, \t) are stripped from the path in pszURL before it is copied to pszPath

HttpPrintf()
int HttpPrintf( PHttpConnection pConn,
                ... );
inputpConndata structure containing information about the incoming request
...string with format data and additional parameters, like printf()
returnint
  • >= 0 : number of bytes written
  • == -1 : parameter error (NULL pointer)
  • == -2 : communication error
write data to the remote system in a free printf()-style. Note: Temporary storage is used in HttpConnection.szTemp.

HttpPuts()
int HttpPuts( PHttpConnection pConn,
              unsigned char *pszText );
inputpConndata structure containing information about the incoming request
pszTexttext to be written
returnint
  • >= 0 : number of bytes written
  • == -1 : parameter error (NULL pointer)
  • == -2 : communication error
writes the given string to the remote system and adds a \r\n (0x0D, 0x0A = CRLF) sequence to the end of it. Note: No temporary data is used.

HttpRead()
int HttpRead( PHttpConnection pConn,
              unsigned char *pszBuffer,
              int cbBuffer );
inputpConndata structure containing information about the incoming request
pszBufferbuffer where to write the data
cbBuffernumber of bytes to be read
returnint
  • >= 0 : number of bytes read
  • == -1 : parameter error (NULL pointer)
  • == -2 : read time-out
  • == -3 : communication error
  • == -99 : end of data, no more data
reads the given number of bytes into the buffer.

HttpRedirect()
int HttpRead( PHttpConnection pConn,
              unsigned char *pszURL );
inputpConndata structure containing information about the incoming request
pszURLnew URL where browser shall request instead of the current one
returnint
  • == 0 : okay
  • == -1 : parameter error (NULL pointer)
  • == -2 : error during sending
sends a HTTP response header with a suitable HTML page that redirects the browser request to the given URL.

HttpScheduleAt()
int HttpScheduleAt( PHttpSrvLaunch pEntry );
inputpEntrydata structure describing when and what to launch
returnint
  • == 0 : okay, entry has been added to scheduling list
  • == -1 : parameter error (NULL pointer)
  • == -2 : invalid date or interval
  • == -3 : scheduler not started yet, retry later
  • == -4 : can't add to scheduler list, list is full
adds an entry to the schedulers list, which is processed every minute. The list is cleared on each system start or reconfiguration run. So each and every procedure, that shall be scheduled, has to be added to the scheduler's list at execution of modInit().
Notes:
- was first introduced in shttpd V 0.3.

HttpSendHeader()
int HttpSendHeader( PHttpConnection pConn,
                    int fStatus );
inputpConndata structure containing information about the incoming request
fStatusHTTP response status, a value of 0 (zero) is re-mapped to HTTP_RC_OK
returnint
  • == 0 : HTTP response header sent
  • == -1 : parameter error (NULL pointer)
  • == -2 : communication error
first sends the initial line of the HTTP response header, using the response code fStatus. If the channel should be kept open (see HttpConnection.fReqInfo and HTTP_REQ_REUSE_CHANNEL), a Keep-Alive:-line is generated. Then the HTTP response header lines described in the two-way linked list HttpConnection.pHttpRespHdr are written. If no such list is given a default Content-type: text/html line is written.

HttpSockInit()
int HttpSockInit( void );
input-
returnint
  • == 0 : IP stack initialization completed
  • == -1 : IP stack initialization error
Initialization of the IP stack on Microsoft Windows systems (Win95, Win98, WinNT, Win2000).
Notes:
- was first introduced in shttpd V 0.3.
- is used internally - it is not necessary to call this function directly, because it is called automatically by the WWW server and the wrapper TCP/IP calls (see include file os.h).

HttpSystem()
int HttpSystem( int fEnv,
                unsigned char *pszCmdLine );
inputfEnv
  • == 0 : do not build environment, use standard environment
  • == 1 : build environment
pszCmdLinecommand line to be executed
returnint
  • == 0 : command executed
  • == -1 : parameter error (NULL pointer)
  • == -2 : execution error
executes the given command from command line - in-/output is not redirected!!!

HttpUngetChar()
int HttpUngetChar( PHttpConnection pConn,
                   unsigned char cChar );
inputpConndata structure containing information about the incoming request
cCharcharacter to be un-getted
returnint
  • == 0 : character put on top of input buffer
  • == -1 : parameter error (NULL pointer)
  • == -2 : can't put character on top of input buffer
deposits the given character on top of the input buffer, so that a following HttpGetChar(), HttpGetLine() or HttpRead() command gets it first.

HttpWrite()
int HttpWrite( PHttpConnection pConn,
               unsigned char *pszBuffer,
               int cbBuffer );
inputpConndata structure containing information about the incoming request
pszBufferbuffer with data
cbBuffernumber of bytes to be written
returnint
  • >= 0 : number of bytes written
  • == -1 : parameter error (NULL pointer)
  • == -2 : write time-out
  • == -3 : communication error
writes the number of given bytes directly to the remote system.

ListAdd()
int ListAdd( PTwoWayLinkedList *pList,
             unsigned char *pszText );
inputpListpointer to pointer to two-way linked list
pszTexttext to be added to the list
returnint
  • == 0 : line added to end of list
  • == -1 : parameter error (invalid pointer)
  • == -2 : memory allocation error (not enough memory)
adds the given line to the end of the list. The string given is duplicated via strdup().

ListClear()
int ListClear( PTwoWayLinkedList *pList );
inputpListpointer to pointer to two-way linked list
returnint
  • == 0 : list successfully deleted
  • == -1 : parameter error (invalid pointer)
removes all entries from the list and frees all associated memory.

ListDelete()
int ListDelete( PTwoWayLinkedList *pList,
                unsigned char *pszSearchText );
inputpListpointer to pointer to two-way linked list
pszSearchTexttext to be searched for (at line start)
returnint
  • == 0 : element removed from list, memory freed
  • == -1 : line not found
  • == -2 : error during deletion
searches for a line starting with the given text and deletes it. Memory associated with the element is freed.
Note: Search is case-insensitive.

ListFind()
char * ListFind( PTwoWayLinkedList *pList,
                 unsigned char *pszSearchText );
inputpListpointer to pointer to two-way linked list
pszSearchTexttext to be searched for (at line start)
returnchar *
  • == NULL : no data available or no list
  • != NULL : data of element found
searches for an element, which has a line starting with the same text as described by the search text. If found, a pointer to the data of the element is returned and the element is selected.
Note: Search is case-insensitive.

ListGet()
char * ListGet( PTwoWayLinkedList *pList );
inputpListpointer to pointer to two-way linked list
returnchar *
  • == NULL : no data available or no list
  • != NULL : data of currently selected element

ListNext()
int ListNext( PTwoWayLinkedList *pList );
inputpListpointer to pointer to two-way linked list
returnint
  • == 0 : next element selected
  • == 1 : no list or end of list reached
  • == -1 : parameter error (invalid pointer)
select next element in the list.

ListPrev()
int ListPrev( PTwoWayLinkedList *pList );
inputpListpointer to pointer to two-way linked list
returnint
  • == 0 : previous element selected
  • == 1 : no list or top of list reached
  • == -1 : parameter error (invalid pointer)
select previous element in the list.

ListReplace()
int ListReplace( PTwoWayLinkedList *pList,
                 unsigned char *pszSearchText,
                 unsigned char *pszReplaceText );
inputpListpointer to pointer to two-way linked list
pszSearchTexttext to be searched for at each start of line within the list
pszReplaceTexttext to be placed in the line matching the search criteria
returnint
  • == 0 : list successfully updated
  • == 1 : no replacement, replacement text was added to the end of the list
  • == -1 : parameter error (invalid pointer)
  • == -2 : memory allocation error (not enough memory)
replaces an existing line within the list with a new one. If the line searched for does not exist, the new text is added to the end of the list instead.

ListRewind()
int ListRewind( PTwoWayLinkedList *pList );
inputpListpointer to pointer to two-way linked list
returnint
  • == 0 : list successfully rewinded
  • == 1 : no list existing (empty list)
  • == -1 : parameter error (invalid pointer)
rewinds the given two-way linked list.

memShmAlloc()
void * memShmAlloc( unsigned long cbMemSize );
inputcbMemSizenumber of bytes to be allocated as shared memory
returnvoid *
  • != NULL : pointer to shared memory block
  • == NULL : could not allocate shared memory (error)
creates a shared memory block with the given size. The returned pointer may be given to child processes (Unix: fork()) which then have access to the same data - updates in that block are visible to the parent!
Note: Was first introduced in shttpd V 0.2.

memShmFree()
int memShmFree( void **ppMemory,
                unsigned long cbMemSize );
inputppMemorypointer to pointer to shared memory block
cbMemSizenumber of bytes to be de-allocated (size of shared memory block, as specified at memShmAlloc()
returnint
  • == 0 : okay, shared memory has been freed
  • == -1 : parameter error
  • == -2 : shared memory is already freed
frees the shared memory block - the associated pointer will be reset to NULL. Shared memory always should be allocated and freed by the master process or thread, i.e. in the module initializer and destructor routine, but nether in the module's handler routine!
Note: Was first introduced in shttpd V 0.2.

memSrvAlloc()
void * memSrvAlloc( unsigned long cbMemSize );
inputcbMemSizenumber of bytes to be allocated as server allocated memory
returnvoid *
  • != NULL : pointer to server allocated memory block
  • == NULL : could not allocate memory (error)
creates a server allocated memory block. This is memory occupied by the WWW server and therefor is not vulnerable to unloads of modules. If a memory block is already allocated, the pointer to this memory is returned instead of allocating a new block. For identification of the memory blocks, the definition of this command gets the file name and line number in the source code.
Note: Was first introduced in shttpd V 0.5.

memSrvFree()
int memSrvFree( void **ppMemory );
inputppMemorypointer to pointer to server allocated memory block, which was returned by memSrvAlloc()
returnint
  • == 0 : okay, server allocated memory has been freed
  • == -1 : parameter error
  • == -2 : server allocated memory is already freed
frees the server allocated memory block - the associated pointer will be reset to NULL. Server allocated memory always should be allocated and freed by the master process or thread, i.e. in the module initializer and destructor routine, but nether in the module's handler routine!
Note: Was first introduced in shttpd V 0.5.

topWriting a loadable module

A lots of things could be told. But it's much easier, to study the example MOD_test, a test / sample module (source code). You may also have a look at the sample module's output page.

There are some things to mention:

>> <<

Table of Contents
Table of
Contents
Index
Index A-Z
Server Administration
Server Ad-
ministration
Copyright
Copyright
Notes
©. 1998-2000 by Dirk Ohme