defs/si_web/httpserv.h File Reference

A tiny portable web server. More...

#include <si_std/string.h>
#include <si_std/listt.h>
#include <pthread.h>

Go to the source code of this file.

Classes

struct  sc_httpServer
 HTTP server object. More...
struct  sc_httpDocument
 HTTP Document object. More...

Defines

#define sm_HTTP_DOC_FROM_BUFFER(filename, buffername)
 Macro that can create a static document object from a C array of document data.

Typedefs

typedef int(* sc_httpDocumentCallback )(const sc_httpRequest *req, sc_httpResponse *resp)
 Signature of document generator callback function.
Forward declarations
typedef struct sc_httpDocument sc_httpDocument
typedef struct sc_httpRequest sc_httpRequest
typedef struct sc_httpResponse sc_httpResponse
typedef struct sc_httpUpload sc_httpUpload

Enumerations

enum  sc_httpRequestType { sc_httpRequestType_GET = 1, sc_httpRequestType_PUT = 2, sc_httpRequestType_POST = 3, sc_httpRequestType_INV = 0 }
 Enumeration of HTTP request types.
enum  sc_httpRequest_argType { sc_httpRequest_argType_unknown = -1, sc_httpRequest_argType_normal = 0, sc_httpRequest_argType_upload = 1 }
 Enumeration of form argument types.

Functions

 sm_listDecl (sc_httpDocument)
 Macro declares sc_httpDocumentList, a list of http documents.
sc_status sc_httpServer_construct (sc_httpServer *psrv, s_uint16 port)
 Construct a new webserver on the given port.
sc_status sc_httpServer_destruct (sc_httpServer *pserver)
 Destructs the server pserver.
sc_status sc_httpServer_addDocument (sc_httpServer *psrv, sc_httpDocument *pdoc)
 Adds the document pdoc to the server.
sc_status sc_httpServer_start (sc_httpServer *psrv)
 Starts the HTTP server on the port given at construction.
sc_status sc_httpServer_stop (sc_httpServer *psrv)
 Stops the HTTP server psrv.
sc_status sc_httpResponse_write (sc_httpResponse *presp, const char *pstr)
 Write the specified string as output HTML.
sc_status sc_httpResponse_writeBinary (sc_httpResponse *presp, const s_uint8 *pbuff, s_uint32 buffSize)
 Write the specified data as binary output.
const char * sc_httpRequest_getBody (const sc_httpRequest *preq)
 Returns the body of the request in case the request was a PUT or POST.
sc_httpRequestType sc_httpRequest_getRequestType (const sc_httpRequest *preq)
 Returns the type of the request: GET, PUT, or POST.
int sc_httpRequest_getArgCount (const sc_httpRequest *preq)
 Returns the number of arguments posted with request preq.
const char * sc_httpRequest_getArgName (const sc_httpRequest *preq, s_uint32 aidx)
 Returns the name of the argument at aidx.
sc_httpRequest_argType sc_httpRequest_getArgType (const sc_httpRequest *preq, const char *argName)
 Returns the type of the argument named argName.
int sc_httpRequest_getArgTypeByIndex (const sc_httpRequest *preq, s_uint32 aidx)
 Returns the type of the argument at idx.
const char * sc_httpRequest_getArgValue (const sc_httpRequest *preq, const char *argName)
 Returns the value of the argument named argName.
const char * sc_httpRequest_getArgValueByIndex (const sc_httpRequest *preq, s_uint32 aidx)
 Returns the value of the argument at idx.
const sc_httpUpload * sc_httpRequest_getArgUploadValue (const sc_httpRequest *preq, const char *argName)
 Returns the value of the upload argument argName.
const sc_httpUpload * sc_httpRequest_getArgUploadValueByIndex (const sc_httpRequest *preq, s_uint32 aidx)
 Returns the value of the upload argument at aidx.
s_uint32 sc_httpUpload_getContentSize (const sc_httpUpload *upl)
 Returns the size of uploaded content.
const char * sc_httpUpload_getContentType (const sc_httpUpload *upl)
 Returns the content type of the uploaded content (mime type).
const char * sc_httpUpload_getContentFilename (const sc_httpUpload *upl)
 Returns the filename of the uploaded content as posted.
sc_status sc_httpUpload_getContent (const sc_httpUpload *upl, s_uint8 *pOutBuf)
 Copies the uploaded content to pOutBuf, which must be large enough to accept it.
sc_status sc_httpDocument_construct (sc_httpDocument *doc, const char *name, sc_httpDocumentCallback callback)
 Construct a new document doc with the given name and callback generator function.
sc_status sc_httpDocument_constructCopy (sc_httpDocument *doc, sc_httpDocument *oth)
 Constructs document doc, copying members of oth.
sc_status sc_httpDocument_assign (sc_httpDocument *doc, sc_httpDocument *rhs)
 Assigns document doc, the value of rhs.
sc_status sc_httpDocument_destruct (sc_httpDocument *doc)
 Destructs document doc.


Detailed Description

A tiny portable web server.

This tiny web server supports HTTP 1.0 and serves up documents added to its internal document list via sc_httpServer_addDocument. The documents are created dynamically by a generator callback function.


Define Documentation

#define sm_HTTP_DOC_FROM_BUFFER ( filename,
buffername   ) 

Value:

int dump_##buffername (const sc_httpRequest* preq, sc_httpResponse* presp) \
    { \
      return sc_httpResponse_writeBinary(presp, buffername, sizeof(buffername)); \
    }\
    sc_httpDocument http_doc_##buffername = { filename, dump_##buffername }
Macro that can create a static document object from a C array of document data.


Function Documentation

sc_status sc_httpDocument_assign ( sc_httpDocument doc,
sc_httpDocument rhs 
)

Assigns document doc, the value of rhs.

Parameters:
[in,out] doc The document to assign to.
[in] rhs The value to assign.
Note:
This function is needed for sc_httpDocumentList.

sc_status sc_httpDocument_construct ( sc_httpDocument doc,
const char *  name,
sc_httpDocumentCallback  callback 
)

Construct a new document doc with the given name and callback generator function.

Parameters:
[in,out] doc The document to construct.
[in] name The name of the document as served.
[in] callback The callback function that generates the document dynamically when requested.

sc_status sc_httpDocument_constructCopy ( sc_httpDocument doc,
sc_httpDocument oth 
)

Constructs document doc, copying members of oth.

Parameters:
[in,out] doc The document to construct.
[in] oth The document to copy.
Note:
This function is needed for sc_httpDocumentList.

int sc_httpRequest_getArgCount ( const sc_httpRequest *  preq  ) 

Returns the number of arguments posted with request preq.

Parameters:
[in] preq The HTTP request object.
Returns:
The number of arguments in request preq.

const char* sc_httpRequest_getArgName ( const sc_httpRequest *  preq,
s_uint32  aidx 
)

Returns the name of the argument at aidx.

Parameters:
[in] preq The HTTP request object.
[in] aidx The index of the argument whose name will be returned.
Returns:
The name of the argument at aidx.
Note:
If idx >= argCount, this function returns NULL.

sc_httpRequest_argType sc_httpRequest_getArgType ( const sc_httpRequest *  preq,
const char *  argName 
)

Returns the type of the argument named argName.

Parameters:
[in] preq The HTTP request object.
[in] argName The name of the argument whose type will be returned.
Returns:
The type of the argument named argName.
Note:
If argName is not a known argument, this function returns NULL.

int sc_httpRequest_getArgTypeByIndex ( const sc_httpRequest *  preq,
s_uint32  aidx 
)

Returns the type of the argument at idx.

Parameters:
[in] preq The HTTP request object.
[in] aidx The index of the argument whose type will be returned.
Note:
If idx >= argCount, this function returns NULL.

const sc_httpUpload* sc_httpRequest_getArgUploadValue ( const sc_httpRequest *  preq,
const char *  argName 
)

Returns the value of the upload argument argName.

Parameters:
[in] preq The HTTP request object.
[in] argName The name of the upload argument.
Returns:
The sc_httpUpload object with the name argName.
Note:
If argName is not a known argument, this function returns NULL.

This function is for use with "upload" arguments as returned by argType. If the named argument is a "normal" argument, this function returns NULL.

Information about the upload (name, filename, content type, etc) can be determined using the sc_httpUpload functions.

const sc_httpUpload* sc_httpRequest_getArgUploadValueByIndex ( const sc_httpRequest *  preq,
s_uint32  aidx 
)

Returns the value of the upload argument at aidx.

Parameters:
[in] preq The HTTP request object.
[in] aidx The index of the upload argument.
Returns:
The sc_httpUpload object with at index aidx.
Note:
If idx >= argCount, this function returns NULL.

This function is for use with "upload" arguments as returned by argType. If the argument specified is a "normal" argument, this function returns NULL.

Information about the upload (name, filename, content type, etc) can be determined using the sc_httpUpload functions.

const char* sc_httpRequest_getArgValue ( const sc_httpRequest *  preq,
const char *  argName 
)

Returns the value of the argument named argName.

Parameters:
[in] preq The HTTP request object.
[in] argName The name of the argument to get.
Returns:
The value of the specified argument as a string.
Note:
If argName is not a known argument, this function returns NULL.

This function is for use with "normal" arguments as returned by argType. If the named argument is an "upload" argument, this function returns NULL.

const char* sc_httpRequest_getArgValueByIndex ( const sc_httpRequest *  preq,
s_uint32  aidx 
)

Returns the value of the argument at idx.

Parameters:
[in] preq The HTTP request object.
[in] aidx The index of the argument to get.
Returns:
The value of the specified argument as a string.
Note:
If idx >= argCount, this function returns NULL.

This function is for use with "normal" arguments as returned by argType. If the named argument is an "upload" argument, this function returns NULL.

const char* sc_httpRequest_getBody ( const sc_httpRequest *  preq  ) 

Returns the body of the request in case the request was a PUT or POST.

Could be used, for example, to read a SOAP envelope in a request.

Parameters:
[in] preq The HTTP request object.
Returns:
Pointer to the body of the request, if present.

sc_httpRequestType sc_httpRequest_getRequestType ( const sc_httpRequest *  preq  ) 

Returns the type of the request: GET, PUT, or POST.

Parameters:
[in] preq The HTTP request object.
Returns:
the type of the request: GET, PUT, or POST

sc_status sc_httpResponse_write ( sc_httpResponse *  presp,
const char *  pstr 
)

Write the specified string as output HTML.

Parameters:
[in,out] presp The HTTP response object.
[in] pstr The string to write as response output.
Note:
This function is intended to be used to return a web page from an http document callback.

sc_status sc_httpResponse_writeBinary ( sc_httpResponse *  presp,
const s_uint8 *  pbuff,
s_uint32  buffSize 
)

Write the specified data as binary output.

Parameters:
[in,out] presp The HTTP response object.
[in] pbuff The buffer to write as response output.
[in] buffSize The number of bytes of pbuff to write.
Note:
This function is intended to be used to return data from an http document callback. This version is especially useful when returning an image file (e.g. .jpg).

sc_status sc_httpServer_addDocument ( sc_httpServer psrv,
sc_httpDocument pdoc 
)

Adds the document pdoc to the server.

The server may only serve documents that have been explicitly added using this function.

Parameters:
[in,out] psrv The server object.
[in] pdoc The document object to add.

sc_status sc_httpServer_construct ( sc_httpServer psrv,
s_uint16  port 
)

Construct a new webserver on the given port.

Parameters:
[in,out] psrv The server object to construct.
[in] port The port for the server to listen on.
Note:
To start the server, you must call sc_httpServer_start.
See also:
sc_httpServer_start

sc_status sc_httpServer_start ( sc_httpServer psrv  ) 

Starts the HTTP server on the port given at construction.

Parameters:
[in,out] psrv The server object to start.
See also:
To add documents to server, call http_server_addDocument.

sc_status sc_httpServer_stop ( sc_httpServer psrv  ) 

Stops the HTTP server psrv.

Parameters:
[in,out] psrv The server object to stop.

sc_status sc_httpUpload_getContent ( const sc_httpUpload *  upl,
s_uint8 *  pOutBuf 
)

Copies the uploaded content to pOutBuf, which must be large enough to accept it.

See also:
sc_httpUpload_getContentSize for how to determine the size of the uploaded content.

const char* sc_httpUpload_getContentFilename ( const sc_httpUpload *  upl  ) 

Returns the filename of the uploaded content as posted.

Returns:
The 'filename' parameter of the uploaded content.

s_uint32 sc_httpUpload_getContentSize ( const sc_httpUpload *  upl  ) 

Returns the size of uploaded content.

Returns:
The size in bytes of the uploaded content.

const char* sc_httpUpload_getContentType ( const sc_httpUpload *  upl  ) 

Returns the content type of the uploaded content (mime type).

Returns:
The MIME type of the uploaded content.


doxygen