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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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()