Bitty HTTP

Development » AutoDocs

1Bitty HTTP Autodocs

W
WS_COOKIE
WS_GET
WS_GetOSSocketHandles
WS_Header
WS_Init
WS_Location
WS_POST
WS_SetCookie
WS_SetHTTPStatusCode
WS_Shutdown
WS_Start
WS_Tick
WS_URLDecode
WS_URLDecodeInPlace
WS_URLEncode
WS_WriteChunk
WS_WriteChunkStr
WS_WriteWhole
WS_WriteWholeStr


WebServer.c/WS_COOKIE()

 NAME:
    WS_COOKIE

 SYNOPSIS:
    const char *WS_COOKIE(struct WebServer *Web,const char *Arg);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Arg [I] -- The GET argument to search for an return

 FUNCTION:
    This function gets a COOKIE from the request and returns it.

    You must place all the COOKIE names you are going to be using (or could
    want to use) in the Web->PageProp->Cookies[] array for the system to be
    able read a cookie.

 RETURNS:
    A pointer to the value or NULL if was not set.

 SEE ALSO:
    WS_Start(), WS_GET(), WS_POST()
Index

WebServer.c/WS_GET()

 NAME:
    WS_GET

 SYNOPSIS:
    const char *WS_GET(struct WebServer *Web,const char *Arg);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Arg [I] -- The GET argument to search for an return

 FUNCTION:
    This function gets a GET arg from the request and returns it.

    You must place all the GET args you are going to be using (or could want
    to use) in the Web->PageProp->Gets[] array for the system to be able
    read a GET arg.

 RETURNS:
    A pointer to the value or NULL if was not set.

 SEE ALSO:
    WS_Start(), WS_COOKIE(), WS_POST()
Index

WebServer.c/WS_GetOSSocketHandles()

 NAME:
    WS_GetOSSocketHandles

 SYNOPSIS:
    int WS_GetOSSocketHandles(t_ConSocketHandle *Handles);

 PARAMETERS:
    Handles [O] -- An array to fill in with the handles being used by the
                   web server.  This must be at least
                   'WS_OPT_MAX_CONNECTIONS+1' in size.

 FUNCTION:
    This function gets all the socket handles being used by the web server.
    You can use these handles to wait on.

    The returned handles depend on what 't_ConSocketHandle' is defined as.

 RETURNS:
    The number of handles being returned

 SEE ALSO:
    
Index

WebServer.c/WS_Header()

 NAME:
    WS_Header

 SYNOPSIS:
    bool WS_Header(struct WebServer *Web,const char *Header);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Header [I] -- The header to write.

 FUNCTION:
    This function writes out a header as part of the http reply.

 RETURNS:
    true -- Things worked out
    false -- There was an error (have you already started sending content?)

 NOTES:
    You do not need to end the string with a \r\n.  This function adds it
    for you.

 LIMITATIONS:
    You can not use this function if you have started sending content.

 SEE ALSO:
    WS_Start(), WS_WriteChunk()
Index

WebServer.c/WS_Init()

 NAME:
    WS_Init

 SYNOPSIS:
    void WS_Init(void);

 PARAMETERS:
    NONE

 FUNCTION:
    This function init's the web server.

 RETURNS:
    NONE

 SEE ALSO:
    WS_Shutdown()
Index

WebServer.c/WS_Location()

 NAME:
    WS_Location

 SYNOPSIS:
    bool WS_Location(struct WebServer *Web,const char *NewURL);

 PARAMETERS:
    Web [I] -- The web server context to work on
    NewURL [I] -- The new URL to redirect the browser to.

 FUNCTION:
    This function does a 301 Moved Permanently redirect.

 RETURNS:
    true -- Things worked out
    false -- There was an error

 NOTES:
    This must be done before anything else is sent (content, header, etc)

 SEE ALSO:
    
Index

WebServer.c/WS_POST()

 NAME:
    WS_POST

 SYNOPSIS:
    const char *WS_POST(struct WebServer *Web,const char *Arg);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Arg [I] -- The GET argument to search for an return

 FUNCTION:
    This function gets a POST arg from the request and returns it.

    You must place all the POST args you are going to be using (or could
    want to use) in the Web->PageProp->Posts[] array for the system to be
    able read a POST arg.

 RETURNS:
    A pointer to the value or NULL if was not set.

 SEE ALSO:
    WS_Start(), WS_GET(), WS_COOKIE()
Index

WebServer.c/WS_SetCookie()

 NAME:
    WS_SetCookie

 SYNOPSIS:
    bool WS_SetCookie(struct WebServer *Web,const char *Name,
          const char *Value,time_t Expire,const char *Path,const char *Domain,
          bool Secure,bool HttpOnly);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Name [I] -- Name of the cookie.  This can not have ' ', ',', or ';'.
    Value [I] -- The value of the cookie. This value is stored on the clients
                 computer; do not store sensitive information.  This is also
                 not escaped (or URI encoded).  You can not have the chars
                 ';', '=', '\r', '\n', ' ', or ','.  Short answer, URI encode
                 your string (WS_URLEncode).
    Expire [I] -- The time the cookie expires.  This is a time_t
                  (Unix timestamp) so is in number of seconds since the epoch.
                  This is sent into gmtime() to make a string.  Pass 0 to
                  ignore.
    Path [I] -- The path on the server in which the cookie will be available
                on. If set to '/', the cookie will be available within the
                entire domain. If set to '/foo/', the cookie will only be
                available within the /foo/ directory and all sub-directories
                such as /foo/bar/ of domain.  If you pass NULL the current
                directory that the cookie is being set in.
    Domain [I] -- The (sub)domain that the cookie is available to. Setting
                  this to a subdomain (such as 'www.example.com') will make
                  the cookie available to that subdomain and all other
                  sub-domains of it (i.e. w2.www.example.com). To make
                  the cookie available to the whole domain (including
                  all subdomains of it), simply set the value to the
                  domain name ('example.com', in this case).

                  Older browsers still implementing the deprecated RFC 2109
                  may require a leading . to match all subdomains.
    Secure [I] -- Indicates that the cookie should only be transmitted over
                  a secure HTTPS connection from the client. When set to
                  true, the cookie will only be set if a secure connection
                  exists. On the server-side, it's on the programmer to
                  send this kind of cookie only on secure connection.
    HttpOnly [I] -- When true the cookie will be made accessible only
                    through the HTTP protocol. This means that the cookie
                    won't be accessible by scripting languages, such as
                    JavaScript. It has been suggested that this setting
                    can effectively help to reduce identity theft through
                    XSS attacks (although it is not supported by all
                    browsers), but that claim is often disputed.

 FUNCTION:
    This function sets a cookie to be sent to the client.

 RETURNS:
    true -- Things worked out
    false -- There was an error (have you already started sending content?)

 NOTES:
    Most of this header was taken from the PHP doc's.

 SEE ALSO:
    
Index

WebServer.c/WS_SetHTTPStatusCode()

 NAME:
    WS_SetHTTPStatusCode

 SYNOPSIS:
    bool WS_SetHTTPStatusCode(struct WebServer *Web,e_ReplyStatusType Code);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Code [I] -- The status code to set.  Only a limited set are supported.

 FUNCTION:
    This function sets the http reply status code that is sent out.

 RETURNS:
    true -- Things worked out
    false -- There was an error

 NOTES:
    This must be done before anything else is sent (content, header, etc)

 SEE ALSO:
    WS_Location(), WS_Header()
Index

WebServer.c/WS_Shutdown()

 NAME:
    WS_Shutdown

 SYNOPSIS:
    void WS_Shutdown(void);

 PARAMETERS:
    NONE

 FUNCTION:
    This function releases anything the web server is using.  After you
    call this you need to call WS_Init() again before you can use any
    web server functions.

 RETURNS:
    NONE

 SEE ALSO:
    WS_Init()
Index

WebServer.c/WS_Start()

 NAME:
    WS_Start

 SYNOPSIS:
    bool WS_Start(uint16_t Port);

 PARAMETERS:
    Port [I] -- What port to listen on

 FUNCTION:
    This function starts the web server listening for incoming connections.

 RETURNS:
    true -- Things worked out
    false -- There was an error

 SEE ALSO:
    WS_WriteWhole(), WS_WriteChunk(), WS_Header(),
Index

WebServer.c/WS_Tick()

 NAME:
    WS_Tick

 SYNOPSIS:
    void WS_Tick(void);

 PARAMETERS:
    NONE

 FUNCTION:
    This function runs the web server.  It accepts new connections, reads
    from existing connections, and sends data out of the open connections
    (it also handles timeouts).

 RETURNS:
    NONE

 NOTES:
    This must be called regularly.

 SEE ALSO:
    
Index

WebServer.c/WS_URLDecode()

 NAME:
    WS_URLDecode

 SYNOPSIS:
    bool WS_URLDecode(const char *Value,char *Decoded,int MaxLen);

 PARAMETERS:
    Value [I] -- The string to decode.
    Decoded [O] -- The buffer to store the decoded string in.
    MaxLen [I] -- The size of 'Decoded'.

 FUNCTION:
    This function encodes a string into URL encoding (%20 for space)

 RETURNS:
    true -- Things worked out
    false -- If we had to clip the string to keep it in 'MaxLen'.

 SEE ALSO:
    
Index

WebServer.c/WS_URLDecodeInPlace()

 NAME:
    WS_URLDecodeInPlace

 SYNOPSIS:
    char *WS_URLDecodeInPlace(char *Value);

 PARAMETERS:
    Value [I] -- The URL encoded string to decode

 FUNCTION:
    This function decodes a URL encoded string directly over top of the
    string.

 RETURNS:
    A pointer to the char directly after the new string ends (after the \0)

 SEE ALSO:
    
Index

WebServer.c/WS_URLEncode()

 NAME:
    WS_URLEncode

 SYNOPSIS:
    bool WS_URLEncode(const char *Value,char *OutputBuffer,int MaxLen);

 PARAMETERS:
    Value [I] -- The string to encode.
    OutputBuffer [O] -- The buffer to store the encoded string in.  This
                        should be 3 times the size of Value for worst case.
    MaxLen [I] -- The size of 'OutputBuffer'.

 FUNCTION:
    This function encodes a string into URL encoding (%20 for space)

 RETURNS:
    true -- Things worked out
    false -- If we had to clip the string to keep it in 'MaxLen'.

 SEE ALSO:
    
Index

WebServer.c/WS_WriteChunk()

 NAME:
    WS_WriteChunk

 SYNOPSIS:
    void WS_WriteChunk(struct WebServer *Web,const char *Buffer,int Len);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Buffer [I] -- The buffer with the contents to send in it.
    Len [I] -- The number of bytes in 'Buffer'

 FUNCTION:
    This function sends content using the chunked method.  This means you
    do not need to know the length of the content before sending (you can
    build it as you go).

    You would normally use this function for dynamic content.  That way
    you do not have to build the whole web page in a buffer before
    repling.

 RETURNS:
    NONE

 SEE ALSO:
    WS_WriteChunkStr(), WS_WriteWhole()
Index

WebServer.c/WS_WriteChunkStr()

 NAME:
    WS_WriteChunkStr

 SYNOPSIS:
    void WS_WriteChunkStr(struct WebServer *Web,const char *Buffer);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Buffer [I] -- The buffer with the contents to send in it.  This is
                  a C string (ending in \0).

 FUNCTION:
    This function sends content using the chunked method.  This means you
    do not need to know the length of the content before sending (you can
    build it as you go).

    This is the same as WS_WriteChunk() except it works on a C string
    instead of a buffer.  This function just calls WS_WriteChunk() with
    a strlen() for the length.

 RETURNS:
    NONE

 SEE ALSO:
    WS_Start(), WS_WriteChunk()
Index

WebServer.c/WS_WriteWhole()

 NAME:
    WS_WriteWhole

 SYNOPSIS:
    void WS_WriteWhole(struct WebServer *Web,const char *Buffer,int Len);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Buffer [I] -- The buffer with the whole contents to send in it.
    Len [I] -- The number of bytes in 'Buffer'

 FUNCTION:
    This function sends the content to the client using 'Content-Length'.
    After you call this function you can not send any more content or headers.

    You use this function if you are sending a static resource like a graphic
    or static web page.  You can also use this you have built all the content
    is a buffer and will not need to send any more.

 RETURNS:
    NONE

 SEE ALSO:
    WS_Start(), WS_WriteWholeStr(), WS_WriteChunk()
Index

WebServer.c/WS_WriteWholeStr()

 NAME:
    WS_WriteWholeStr

 SYNOPSIS:
    void WS_WriteWholeStr(struct WebServer *Web,const char *Buffer);

 PARAMETERS:
    Web [I] -- The web server context to work on
    Buffer [I] -- The buffer with the whole contents to send in it.  This
                  is a C string (ending in \0).

 FUNCTION:
    This function sends the content to the client using 'Content-Length'.
    After you call this function you can not send any more content or headers.

    This is the same as WS_WriteWhole() except it works on a C string
    instead of a buffer.  This function just calls WS_WriteWhole() with
    a strlen() for the length.

 RETURNS:
    NONE

 SEE ALSO:
    WS_Start(), WS_WriteWhole()