Home > Programmers Reference > GoAhead

See Also

Quick Nav

GOAHEAD - GoAhead API Native API

Components

Webs GoAhead request structure.
WebsAuth GoAhead Authentication.
WebsBuf A WebsBuf (ring queue) allows maximum utilization of memory for data storage and is ideal for input/output buffering.
WebsHash Hash table entry structure.
WebsRoute Request route structure.
WebsRuntime GoAhead Web Server Runtime.
WebsSession Session state storage.
WebsSocket Socket control structure.
WebsUpload File upload structure.

Functions

voidassert(bool cond)
 Assure that an assert condition is true.
voidbufAddNull(WebsBuf *bp)
 Add a trailing null to the buffer.
voidbufAdjustEnd(WebsBuf *bp, ssize size)
 Adjust the endp pointer by the specified size.
voidbufAdjustStart(WebsBuf *bp, ssize count)
 Adjust the start (servp) reference.
voidbufCompact(WebsBuf *bp)
 Compact the data in the buffer and move to the start of the buffer.
intbufCreate(WebsBuf *bp, int increment, int maxsize)
 Create a buffer.
voidbufFlush(WebsBuf *bp)
 Flush all data in the buffer and reset the pointers.
voidbufFree(WebsBuf *bp)
 Free allocated storage for the buffer.
ssizebufGetBlk(WebsBuf *bp, char *blk, ssize len)
 Copy a block of from the buffer and adjust the servp.
ssizebufGetBlkMax(WebsBuf *bp)
 Return the maximum number of bytes the buffer can provide via a single block copy.
intbufGetc(WebsBuf *bp)
 Get a character from the buffer and increment the servp.
boolbufGrow(WebsBuf *bp, ssize room)
 Grow the buffer by at least the required amount of room.
intbufInsertc(WebsBuf *bp, char c)
 Insert a character to the buffer before the servp position and decrement the servp.
ssizebufLen(WebsBuf *bp)
 Get the length of available data in the buffer.
ssizebufPutBlk(WebsBuf *bp, char *blk, ssize len)
 Put a block to the buffer.
ssizebufPutStr(WebsBuf *bp, char *str)
 Append a string to the buffer at the endp position and increment the endp.
intbufPutc(WebsBuf *bp, char c)
 Append a character to the buffer at the endp position and increment the endp.
voidbufReset(WebsBuf *bp)
 Reset the buffer pointers to the start of the buffer if empty.
ssizebufRoom(WebsBuf *bp)
 Determine the room available in the buffer.
char*bufStart(WebsBuf *bp)
 Get a reference to the start of buffer data.
voiderror(char *fmt, ...)
 Emit an error message.
char*fmt(char *buf, ssize maxSize, char *format, ...)
 Format a string into a static buffer.
WebsHashhashCreate(int size)
 Create a hash table.
inthashDelete(WebsHash id, char *name)
 Delete a key by name.
WebsKey*hashEnter(WebsHash id, char *name, WebsValue value, int arg)
 Enter a new key and value into the hash table.
WebsKey*hashFirst(WebsHash id)
 Start walking the hash keys by returning the first key entry in the hash.
voidhashFree(WebsHash id)
 Free a hash table.
WebsKey*hashLookup(WebsHash id, char *name)
 Lookup a name in the hash table.
WebsKey*hashNext(WebsHash id, WebsKey *last)
 Continue walking the hash keys by returning the next key entry in the hash.
uinthextoi(char *str)
 Convert a hex string to an integer.
char*itosbuf(char *buf, ssize size, int64 value, int radix)
 Convert an integer to a string buffer.
voidlogClose()
 Close the log logging module.
intlogOpen()
 Open the log logging module.
WebsLogHandlerlogSetHandler(WebsLogHandler handler)
 Set a log callback.
voidlogSetPath(char *path)
 Set the filename to save logging output.
voidlogmsgProc(int level, char *fmt, ...)
 Emit a message to the log.
intscaselesscmp(char *s1, char *s2)
 Compare strings ignoring case.
boolscaselessmatch(char *s1, char *s2)
 Compare strings ignoring case.
char*sclone(char *str)
 Clone a string.
intscmp(char *s1, char *s2)
 Compare strings.
ssizescopy(char *dest, ssize destMax, char *src)
 Copy a string.
char*sfmt(char *format, ...)
 Format a string.
char*sfmtv(char *format, va_list args)
 Format a string with varargs.
ssizeslen(char *str)
 Return the length of a string.
char*slower(char *str)
 Convert a string to lower case.
boolsmatch(char *s1, char *s2)
 Compare strings.
intsncaselesscmp(char *s1, char *s2, ssize len)
 Compare strings ignoring case.
intsncmp(char *s1, char *s2, ssize len)
 Compare strings.
ssizesncopy(char *dest, ssize destMax, char *src, ssize count)
 Copy characters from a string.
intsocketAddress(struct sockaddr *addr, int addrlen, char *ipbuf, int ipLen, int *port)
 Extract the numerical IP address and port for the given socket info.
boolsocketAddressIsV6(char *ip)
 Determine if an IP address is an IPv6 address.
intsocketAlloc(char *host, int port, SocketAccept accept, int flags)
 Allocate a socket object.
voidsocketClose()
 Close the socket module.
voidsocketCloseConnection(int sid)
 Close a socket connection.
intsocketConnect(char *host, int port, int flags)
 Connect to a server and create a new socket.
voidsocketCreateHandler(int sid, int mask, SocketHandler handler, void *arg)
 Create a socket handler that will be invoked when I/O events occur.
voidsocketDeleteHandler(int sid)
 Delete a socket handler created via socketCreateHandler.
boolsocketEof(int sid)
 Determine if the socket is at end-of-file for input.
voidsocketFree(int sid)
 Free (and close) the socket.
intsocketGetBlock(int sid)
 Get the current blocking mode.
intsocketGetError()
 Get the error code for the last socket operation on this thread.
SocketsocketGetHandle(int sid)
 Get the underlying socket operating system socket/file handle.
intsocketGetPort(int sid)
 Get the IP port associated with this socket.
boolsocketHasDualNetworkStack()
 Indicate if the system has a dual IPv4 and IPv6 stack.
boolsocketHasIPv6()
 Indicate if the system has IPv6 support.
voidsocketHiddenData(WebsSocket *sp, ssize len, int dir)
 Indicate that the application layer has buffered data for the socket.
intsocketInfo(char *ip, int port, int *family, int *protocol, struct sockaddr_storage *addr, Socklen *addrlen)
 Get a socket address structure for the specified IP:Port.
boolsocketIsV6(int sid)
 Determine if a socket is bound to an IPv6 address.
intsocketListen(char *host, int port, SocketAccept accept, int flags)
 Open a listening socket.
intsocketOpen()
 Open the socket module.
intsocketParseAddress(char *ipAddrPort, char **pip, int *pport, int *secure, int defaultPort)
 Parse an IP address into its constituent parts.
voidsocketProcess()
 Process pending socket I/O events.
WebsSocket*socketPtr(int sid)
 Return the socket object for the socket ID.
ssizesocketRead(int sid, void *buf, ssize len)
 Read data from a socket.
voidsocketRegisterInterest(int sid, int mask)
 Register interest in socket I/OEvents.
voidsocketReservice(int sid)
 Request that the socket be reserviced.
intsocketSelect(int sid, WebsTime timeout)
 Wait for I/O on a socket.
intsocketSetBlock(int sid, int on)
 Set the socket blocking mode.
intsocketSetNoDelay(int sid, bool on)
 Set the socket delay mode.
intsocketWaitForEvent(WebsSocket *sp, int mask)
 Wait for a socket I/O event.
ssizesocketWrite(int sid, void *buf, ssize len)
 Write data to the socket.
voidsslClose()
 Close the ssl module.
voidsslFree(Webs *wp)
 Free a ssl connection associated with a request.
intsslOpen()
 Open the ssl module.
ssizesslRead(Webs *wp, void *buf, ssize len)
 Read data from a secure socket.
intsslUpgrade(Webs *wp)
 Upgrade a request connection to utilize SSL.
ssizesslWrite(Webs *wp, void *buf, ssize len)
 WRite data to a secure socket.
char*stok(char *str, char *delim, char **last)
 Tokenize a string.
char*strim(char *str, char *set, int where)
 Trim a string.
char*supper(char *str)
 Convert a string to upper case.
voidtraceProc(int level, char *fmt, ...)
 Emit a debug trace message to the log.
voidvalueFree(WebsValue *value)
 Free any allocated string in a value.
WebsValuevalueInteger(long value)
 Create an integer value.
WebsValuevalueString(char *value, int flags)
 Create an string value.
WebsValuevalueSymbol(void *value)
 Create an symbol value containing an object reference.
intwallocHandle(void *map)
 Allocate a handle from a map.
intwallocObject(void *map, int *max, int size)
 Allocate an object in a halloc map.
intwebsAccept(int sid, char *ipaddr, int port, int listenSid)
 Accept a new connection.
voidwebsActionOpen()
 Open the action handler.
WebsRole*websAddRole(char *role, WebsHash abilities)
 Add a role.
WebsRoute*websAddRoute(char *uri, char *handler, int pos)
 Add a route to the routing tables.
WebsUser*websAddUser(char *username, char *password, char *roles)
 Add a user.
intwebsAlloc(int sid)
 Allocate a new Webs object.
WebsSession*websAllocSession(Webs *wp, char *id, WebsTime lifespan)
 Test if a user possesses the required ability.
boolwebsAuthenticate(Webs *wp)
 Authenticate a user.
boolwebsCan(Webs *wp, WebsHash ability)
 Test if a user possesses the required ability.
voidwebsCancelTimeout(Webs *wp)
 Cancel the request timeout.
intwebsCgiHandler(Webs *wp)
 CGI handler service callback.
intwebsCgiOpen()
 Open the CGI handler.
WebsTimewebsCgiPoll()
 Poll for output from CGI processes and output.
voidwebsClose()
 Close the core GoAhead web server module.
voidwebsCloseAuth()
 Close the authentication module.
voidwebsCloseFile(int fd)
 Close an open file.
voidwebsCloseRoute()
 Close the route module.
intwebsCompareVar(Webs *wp, char *var, char *value)
 Compare a request variable.
voidwebsComputeAllUserAbilities()
 Compute the abilities for all users by resolving roles into abilities.
voidwebsConsumeInput(Webs *wp, ssize nbytes)
 Consume input from the request input buffer.
char*websDecode64(char *str)
 Decode the string using base-64 encoding.
char*websDecode64Block(char *str, ssize *len, int flags)
 Decode a block using base-46 encoding.
voidwebsDecodeUrl(char *decoded, char *input, ssize len)
 Decode a URL expanding NN encoding.
intwebsDefineAction(char *name, void *fun)
 Define an action callback for use with the action handler.
intwebsDefineHandler(char *name, WebsHandlerProc service, WebsHandlerClose close, int flags)
 Define a request handler.
intwebsDefineJst(char *name, WebsJstProc fn)
 Define a Javscript native function.
voidwebsDone(Webs *wp)
 Complete a request.
char*websEncode64(char *str)
 Encode a string using base-64 encoding.
char*websEncode64Block(char *str, ssize len)
 Encode a block using base-64 encoding.
voidwebsError(Webs *wp, int code, char *fmt, ...)
 Complete a request with an error response.
char*websErrorMsg(int code)
 Get a message for a HTTP status code.
char*websEscapeHtml(char *str)
 Escape unsafe characters in a string.
voidwebsFileOpen()
 Open and initialize the file handler.
boolwebsFlush(Webs *wp)
 Flush buffered transmit data and compact the transmit buffer to make room for more data.
voidwebsFree(Webs *wp)
 Free the webs request object.
voidwebsFreeUpload(Webs *wp)
 Free file upload data structures.
voidwebsFsClose()
 Close the file system module.
intwebsFsOpen()
 Open the file system module.
intwebsGetBackground()
 Get the background execution flag.
char*websGetCgiCommName()
 Get a unique temporary filename for CGI communications.
char*websGetCookie(Webs *wp)
 Get the request cookie if supplied.
char*websGetDateString(WebsFileInfo *sbuf)
 Get a date as a string.
intwebsGetDebug()
 Get the debug flag.
char*websGetDir(Webs *wp)
 Get the base file directory for a request.
char*websGetDocuments()
 Get the GoAhead base documents directory.
intwebsGetEof(Webs *wp)
 Get the request EOF status.
char*websGetExt(Webs *wp)
 Get the request URI extension.
char*websGetFilename(Webs *wp)
 Get the request filename.
char*websGetHost(Webs *wp)
 Get the request host.
char*websGetIfaddr(Webs *wp)
 Get the request interface address.
char*websGetIndex()
 Get the default index document name.
intwebsGetLogLevel()
 Get the current trace log level.
char*websGetMethod(Webs *wp)
 Get the request method.
char*websGetPassword(Webs *wp)
 Get the request password.
WebsVerifywebsGetPasswordStoreVerify()
 Set the password store verify callback.
char*websGetPath(Webs *wp)
 Get the request path.
intwebsGetPort(Webs *wp)
 Get the request TCP/IP port.
char*websGetProtocol(Webs *wp)
 Get the request HTTP protocol.
char*websGetQuery(Webs *wp)
 Get the request query component.
WebsHashwebsGetRoles()
 Get the roles hash.
char*websGetServer()
 Get the server host name.
char*websGetServerAddress()
 Get the server IP address.
char*websGetServerAddressUrl()
 Get the server IP address with port number.
char*websGetServerUrl()
 Get the server host name with port number.
WebsSession*websGetSession(Webs *wp, int create)
 Get the session state object for the current request.
char*websGetSessionID(Webs *wp)
 Get the session ID.
char*websGetSessionVar(Webs *wp, char *name, char *defaultValue)
 Get a session variable.
WebsHashwebsGetUpload(struct Webs *wp)
 Get the hash of uploaded files for the request.
char*websGetUrl(Webs *wp)
 Get the request URI.
char*websGetUserAgent(Webs *wp)
 Get the client User-Agent HTTP header.
char*websGetUsername(Webs *wp)
 Get the request username.
WebsHashwebsGetUsers()
 Get the users hash.
char*websGetVar(Webs *wp, char *name, char *defaultValue)
 Get a request variable.
intwebsJstOpen()
 Open the Javascript module.
intwebsJstWrite(int jid, Webs *wp, int argc, char **argv)
 Write data to the response.
intwebsListen(char *endpoint)
 Listen on a TCP/IP address endpoint.
intwebsLoad(char *path)
 Load routing tables from the specified filename.
boolwebsLoginUser(Webs *wp, char *username, char *password)
 Login a user by verifying the login credentials.
WebsUpload*websLookupUpload(struct Webs *wp, char *key)
 Open the file upload filter.
WebsUser*websLookupUser(char *username)
 Lookup if a user exists.
char*websMD5(char *str)
 Get an MD5 digest of a string.
char*websMD5Block(char *buf, ssize length, char *prefix)
 Get an MD5 digest of a block and optionally prepend a prefix.
char*websNormalizeUriPath(char *path)
 Normalize a URI path.
voidwebsNoteRequestActivity(Webs *wp)
 Take not of the request activity and mark the time.
intwebsOpen(char *documents, char *routes)
 Open the web server.
intwebsOpenAuth(int minimal)
 Open the authentication module.
intwebsOpenFile(char *path, int flags, int mode)
 Open the web page document for the current request.
intwebsOpenRoute()
 Open the routing module.
intwebsOptionsOpen()
 Open the options handler.
voidwebsOsClose()
 Close the O/S dependant code.
intwebsOsOpen()
 Open the O/S dependant code.
voidwebsPageClose(Webs *wp)
 Close the document page.
intwebsPageIsDirectory(Webs *wp)
 Test if the document page for the request corresponds to a directory.
intwebsPageOpen(Webs *wp, int mode, int perms)
 Open a web page document for a request.
ssizewebsPageReadData(Webs *wp, char *buf, ssize size)
 Read data from the request page document.
voidwebsPageSeek(Webs *wp, Offset offset, int origin)
 Seek to a position in the request page document.
intwebsPageStat(Webs *wp, WebsFileInfo *sbuf)
 Get file status for the current request document.
intwebsProcessCgiData(Webs *wp)
 Process CGI request body data.
intwebsProcessUploadData(Webs *wp)
 Process upload data for form, multipart mime file upload.
voidwebsPump(Webs *wp)
 Pump the state machine.
ssizewebsReadFile(int fd, char *buf, ssize size)
 Read data from an open file.
char*websReadWholeFile(char *path)
 Read all the data from a file.
voidwebsRedirect(Webs *wp, char *url)
 Redirect the client to a new URL.
intwebsRedirectByStatus(Webs *wp, int status)
 Redirect the client to a new URI.
intwebsRemoveRole(char *role)
 Remove a role from the system.
intwebsRemoveRoute(char *uri)
 Remove a route from the routing tables.
voidwebsRemoveSessionVar(Webs *wp, char *name)
 Remove a session variable.
intwebsRemoveUser(char *name)
 Remove a user from the system.
voidwebsResponse(Webs *wp, int status, char *msg)
 Create and send a request response.
voidwebsRestartEvent(int id, int delay)
 Restart an event.
intwebsRewriteRequest(Webs *wp, char *url)
 Rewrite a request.
voidwebsRouteRequest(Webs *wp)
 Route a request.
WebsTimewebsRunEvents()
 Run due events.
voidwebsRuntimeClose()
 Close the runtime code.
intwebsRuntimeOpen()
 Open the runtime code.
OffsetwebsSeekFile(int fd, Offset offset, int origin)
 Seek to a position in the current request page document.
intwebsServer(char *endpoint, char *documents)
 One line embedding API.
voidwebsServiceEvents(int *finished)
 Service I/O events until finished.
voidwebsSetBackground(int on)
 Set the background processing flag.
voidwebsSetBackgroundWriter(Webs *wp, WebsWriteProc proc)
 Define a background write I/O event callback.
voidwebsSetCookie(Webs *wp, char *name, char *value, char *path, char *domain, WebsTime lifespan, int flags)
 Define a cookie to include in the response.
voidwebsSetDebug(int on)
 Set the debug processing flag.
voidwebsSetDocuments(char *dir)
 Set the web documents directory.
voidwebsSetEnv(Webs *wp)
 Create the CGI environment variables for the current request.
voidwebsSetFormVars(Webs *wp)
 Create request variables for query and POST body data.
voidwebsSetHost(char *host)
 Define the host name for the server.
voidwebsSetIndex(char *filename)
 Create and send a request response.
voidwebsSetIpAddr(char *ipaddr)
 Define the host IP address.
voidwebsSetPasswordStoreVerify(WebsVerify verify)
 Set the password store verify callback.
voidwebsSetQueryVars(Webs *wp)
 Create request variables for query string data.
intwebsSetRouteAuth(WebsRoute *route, char *authType)
 Set route authentication scheme.
intwebsSetRouteMatch(WebsRoute *route, char *dir, char *protocol, WebsHash methods, WebsHash extensions, WebsHash abilities, WebsHash redirects)
 Configure a route by adding matching criteria.
intwebsSetSessionVar(Webs *wp, char *name, char *value)
 Set a session variable name value.
voidwebsSetStatus(Webs *wp, int status)
 Set the response HTTP status code.
voidwebsSetTxLength(Webs *wp, ssize length)
 Set the response body content length.
intwebsSetUserRoles(char *username, char *roles)
 Define the set of roles for a user.
voidwebsSetVar(Webs *wp, char *name, char *value)
 Set a request variable to a string value.
voidwebsSetVarFmt(Webs *wp, char *name, char *fmt, ...)
 Set a request variable to a formatted string value.
intwebsStartEvent(int delay, WebsEventProc proc, void *data)
 Start a callback event.
intwebsStatFile(char *path, WebsFileInfo *sbuf)
 Get file status for a file.
voidwebsStopEvent(int id)
 Stop an event.
char*websTempFile(char *dir, char *prefix)
 Create a temporary filename This does not guarantee the filename is unique or that it is not already in use by another application.
boolwebsTestVar(Webs *wp, char *name)
 Test if a request variable is defined.
voidwebsUploadOpen()
 Open the file upload filter.
intwebsUrlParse(char *url, char **buf, char **protocol, char **host, char **port, char **path, char **ext, char **reference, char **query)
 Parse a URL into its components.
boolwebsValid(Webs *wp)
 Test if a webs object is valid.
boolwebsVerifyPasswordFromCustom(Webs *wp)
 User password verification routine from a custom password back-end store.
boolwebsVerifyPasswordFromFile(Webs *wp)
 User password verification routine from auth.txt.
ssizewebsWrite(Webs *wp, char *fmt, ...)
 Write data to the response.
ssizewebsWriteBlock(Webs *wp, char *buf, ssize size)
 Write a block of data to the response.
voidwebsWriteEndHeaders(Webs *wp)
 Signify the end of the response headers.
ssizewebsWriteFile(int fd, char *buf, ssize size)
 Write data to the open file.
intwebsWriteHeader(Webs *wp, char *key, char *fmt, ...)
 Write a response header.
voidwebsWriteHeaders(Webs *wp, ssize contentLength, char *redirect)
 Write a set of standard response headers.
ssizewebsWriteSocket(Webs *wp, char *buf, ssize size)
 Write a block of data to the network.
intwfreeHandle(void *map, int handle)
 Free a handle in the map.

Typedefs

SocketAcceptSocket accept callback.
SocketHandlerSocket I/O callback.
WebsActionAction callback.
WebsAskLoginCallback to prompt the user for their password.
WebsErrorError code list.
WebsEventProcCallback function for events.
WebsFileInfoFile information structure.
WebsHandlerGoAhead handler object.
WebsHandlerCloseGoAhead handler close to release memory prior to shutdown.
WebsHandlerProcGoAhead handler service callback.
WebsHashHash table ID returned by hashCreate.
WebsJstProcJavascript native function.
WebsLogHandlerCallback for emitting trace log output.
WebsMimeMime type list.
WebsParseAuthCallback to parse authentication details submitted with the web request.
WebsRoleRole definition structure.
WebsRomIndexCompiled Rom Page Index.
WebsStatFile status structure.
WebsTimeSystem native time type.
WebsUserUser definition structure.
WebsValueValue union to store primitive value types.
WebsVerifyCallback to verify the username and password.
WebsWriteProcCallback for write I/O events.

Defines

#defineHTTP_CODE_ACCEPTED   202
 The request has been accepted and processing is continuing.
#defineHTTP_CODE_BAD_GATEWAY   502
 The server cannot act as a gateway for the given request.
#defineHTTP_CODE_BAD_METHOD   405
 The request HTTP method was not supported by the resource.
#defineHTTP_CODE_BAD_REQUEST   400
 The request is malformed.
#defineHTTP_CODE_BAD_VERSION   505
 The server does not support the HTTP protocol version.
#defineHTTP_CODE_COMMS_ERROR   550
 The server had a communicationss error responding to the client.
#defineHTTP_CODE_CONFLICT   409
 The request had a conflict in the request headers and URI.
#defineHTTP_CODE_CONTINUE   100
 Continue with request, only partial content transmitted.
#defineHTTP_CODE_CREATED   201
 The request has completed and a new resource was created.
#defineHTTP_CODE_EXPECTATION_FAILED   417
 The server cannot satisfy the Expect header requirements.
#defineHTTP_CODE_FORBIDDEN   403
 The request was legal, but the server refuses to process.
#defineHTTP_CODE_GATEWAY_TIMEOUT   504
 The server gateway timed out waiting for the upstream server.
#defineHTTP_CODE_GONE   410
 The requested resource is no longer available.
#defineHTTP_CODE_INSUFFICIENT_STORAGE   507
 The server has insufficient storage to complete the request.
#defineHTTP_CODE_INTERNAL_SERVER_ERROR   500
 Server processing or configuration error.
#defineHTTP_CODE_LENGTH_REQUIRED   411
 The request did not specify a required content length.
#defineHTTP_CODE_MOVED_PERMANENTLY   301
 The requested URI has moved permanently to a new location.
#defineHTTP_CODE_MOVED_TEMPORARILY   302
 The URI has moved temporarily to a new location.
#defineHTTP_CODE_NO_CONTENT   204
 The request has completed and there is no response to send.
#defineHTTP_CODE_NO_RESPONSE   444
 The connection was closed with no response to the client.
#defineHTTP_CODE_NOT_ACCEPTABLE   406
 The requested resource cannot generate the required content.
#defineHTTP_CODE_NOT_AUTHORITATIVE   203
 The request has completed but content may be from another source.
#defineHTTP_CODE_NOT_FOUND   404
 The requested resource was not found.
#defineHTTP_CODE_NOT_IMPLEMENTED   501
 The server does not recognize the request or method.
#defineHTTP_CODE_NOT_MODIFIED   304
 The requested resource has changed since the last request.
#defineHTTP_CODE_OK   200
 The request completed successfully.
#defineHTTP_CODE_PARTIAL   206
 The request has completed and is returning partial content.
#defineHTTP_CODE_PAYMENT_REQUIRED   402
 Reserved for future use.
#defineHTTP_CODE_PRECOND_FAILED   412
 The server cannot satisfy one of the request preconditions.
#defineHTTP_CODE_RANGE_NOT_SATISFIABLE   416
 The request content range does not exist for the resource.
#defineHTTP_CODE_REQUEST_TIMEOUT   408
 The server timed out waiting for the request to complete.
#defineHTTP_CODE_REQUEST_TOO_LARGE   413
 The request is too large for the server to process.
#defineHTTP_CODE_REQUEST_URL_TOO_LARGE   414
 The request URI is too long for the server to process.
#defineHTTP_CODE_RESET   205
 The request has completed with no content.
#defineHTTP_CODE_SEE_OTHER   303
 The requested URI can be found at another URI location.
#defineHTTP_CODE_SERVICE_UNAVAILABLE   503
 The server is currently unavailable or overloaded.
#defineHTTP_CODE_TEMPORARY_REDIRECT   307
 The request should be repeated at another URI location.
#defineHTTP_CODE_UNAUTHORIZED   401
 Authentication for the request has failed.
#defineHTTP_CODE_UNSUPPORTED_MEDIA_TYPE   415
 The request media type is not supported by the server or resource.
#defineHTTP_CODE_USE_PROXY   305
 The requested resource must be accessed via the location proxy.
#defineSOCKET_AGAIN   4
 Issue the request again.
#defineSOCKET_ASYNC   0x8
 Use async connect.
#defineSOCKET_BLOCK   0x10
 Use blocking I/O.
#defineSOCKET_BUFFERED_READ   0x200
 Message pending on this socket.
#defineSOCKET_BUFFERED_WRITE   0x400
 Message pending on this socket.
#defineSOCKET_CLOSING   0x40
 Socket is closing.
#defineSOCKET_CONNECTING   0x2
 Connect in progress.
#defineSOCKET_CONNRESET   0x80
 Socket connection was reset.
#defineSOCKET_EOF   0x1
 Seen end of file.
#defineSOCKET_EXCEPTION   0x8
 Interested in exceptions.
#defineSOCKET_HANDSHAKING   0x100
 Doing SSL handshake.
#defineSOCKET_INTR   5
 Call was interrupted.
#defineSOCKET_INVAL   6
 Invalid.
#defineSOCKET_LISTENING   0x20
 Socket is server listener.
#defineSOCKET_NETDOWN   3
 Network is down.
#defineSOCKET_NODELAY   0x800
 Disable Nagle algorithm.
#defineSOCKET_READABLE   0x2
 Make socket readable.
#defineSOCKET_RESERVICE   0x4
 Socket needs re-servicing.
#defineSOCKET_RESET   2
 Socket has been reset.
#defineSOCKET_WOULDBLOCK   1
 Socket would block on I/O.
#defineSOCKET_WRITABLE   0x4
 Make socket writable.
#defineVALUE_ALLOCATE   0x1
 Allocate strings using malloc.
#definevalue_numeric   (t >= byteint && t <= big)
 The value is a numeric type.
#definevalue_ok   (t > undefined && t <= symbol)
 The value is valid supported type.
#definevalue_str   (t >= string && t <= bytes)
 The value is a string type.
#defineWEBS_ACCEPTED   0x1
 TLS connection accepted.
#defineWEBS_ASSERT_MSG   0x10
 Originated from assert.
#defineWEBS_BEGIN   0x0
 Beginning state.
#defineWEBS_CHUNK_DATA   3
 Start of chunk data.
#defineWEBS_CHUNK_HEADER   2
 Preparing tx chunk header.
#defineWEBS_CHUNK_START   1
 Start of a new chunk.
#defineWEBS_CHUNK_UNCHUNKED   0
 Data is not transfer-chunk encoded.
#defineWEBS_CHUNKING   0x2
 Currently chunking output body data.
#defineWEBS_CLOSE   0x20000
 Close connection.
#defineWEBS_CLOSED   0x4
 Connection closed, ready to free.
#defineWEBS_COMPLETE   0x8
 Request complete.
#defineWEBS_CONFIG   2
 Configuration settings trace level.
#defineWEBS_CONTENT   0x1
 Ready for body data.
#defineWEBS_COOKIE   0x8
 Cookie supplied in request.
#defineWEBS_COOKIE_HTTP   0x2
 Flag for websSetCookie for http cookies (http only).
#defineWEBS_COOKIE_SECURE   0x1
 Flag for websSetCookie for secure cookies (https only).
#defineWEBS_DECODE_TOKEQ   1
 Decode base 64 blocks up to a NULL or equals.
#defineWEBS_ERROR   1
 Standard logging trace levels are 0 to 9 with 0 being the most verbose.
#defineWEBS_ERROR_MSG   0x20
 Originated from error.
#defineWEBS_FINALIZED   0x10
 Output is finalized.
#defineWEBS_FORM   0x20
 Request is a form (url encoded data).
#defineWEBS_HEADERS_CREATED   0x40
 Headers have been created and buffered.
#defineWEBS_HTTP11   0x80
 Request is using HTTP/1.1.
#defineWEBS_KEEP_ALIVE   0x100
 HTTP/1.1 keep alive.
#defineWEBS_LEVEL_MASK   0xF
 Level mask.
#defineWEBS_LOG_MSG   0x100
 Originated from logmsg.
#defineWEBS_MAX_LISTEN   8
 Maximum number of listen endpoints.
#defineWEBS_NOLOG   0x40000
 Don't write error to log.
#defineWEBS_RAW_MSG   0x200
 Raw message output.
#defineWEBS_READY   0x2
 Ready to route and start handler.
#defineWEBS_REROUTE   0x1000
 Restart route matching.
#defineWEBS_RESPONSE_TRACED   0x200
 Started tracing the response.
#defineWEBS_RUNNING   0x4
 Processing request.
#defineWEBS_SECURE   0x400
 Connection uses SSL.
#defineWEBS_SMALL_HASH   31
 General small hash size.
#defineWEBS_TRACE_MSG   0x400
 Originated from trace.
#defineWEBS_TRIM_BOTH   0x3
 Flag for strim to trim from both the start and the end of the string.
#defineWEBS_TRIM_END   0x2
 Flag for strim to trim from the end of the string.
#defineWEBS_TRIM_START   0x1
 Flag for strim to trim from the start of the string.
#defineWEBS_UPLOAD   0x800
 Multipart-mime file upload.
#defineWEBS_VARS_ADDED   0x8000
 Query and body form vars added.
#defineWEBS_VERBOSE   9
 Highest level of trace.
#defineWEBS_WARN   2
 Soft warning trace level.

Webs

Webs

GoAhead request structure.

Fields:
char *authDetails Http header auth details.
char *authResponse Outgoing auth header.
char *authType Authorization type (Basic/DAA).
char *boundary Mime boundary (static).
ssizeboundaryLen Boundary length.
intcgifd File handle for CGI program input.
char *cgiStdin Filename for CGI program input.
WebsBufchunkbuf Pre-chunking data buffer.
char *clientFilename Current file filename.
char *cnonce check nonce.
intcode Response status code.
char *contentType Body content type.
char *cookie Request cookie string.
WebsUpload *currentFile Current file context.
char *decodedQuery Decoded request query.
char *digest Password digest.
char *digestUri URI found in digest header.
intdocfd File descriptor for document being served.
intencoded True if the password is MD5(username:realm:password).
booleof If at the end of the request content.
char *ext Path extension.
char *filename Document path name.
WebsHashfiles Uploaded files.
intflags Current flags see above.
char *host Requested host.
charifaddr[64] Local interface ipaddress.
WebsBufinput Receive buffer after de-chunking.
char *inputFile File name to write input body data.
charipaddr[64] Connecting ipaddress.
ssizelastRead Number of bytes last read from the socket.
intlistenSid Listen Socket id.
char *method HTTP request method.
char *nc nonce count.
char *nonce opaque-to-client string sent by server.
char *opaque opaque value passed from server.
WebsBufoutput Transmit buffer after chunking.
char *password Authorization password.
char *path Path name without query. This is decoded.
intport Request port number.
char *protocol Protocol scheme (normally http|https).
char *protoVersion Protocol version (HTTP/1.1).
ssizeputLen Bytes read by a PUT request.
char *putname PUT temporary filename.
char *qop quality operator.
char *query Request query. This is decoded.
char *realm Realm field supplied in auth header.
char *referrer The referring page.
char *responseCookie Outgoing cookie.
struct WebsRoute *route Request route.
WebsBufrxbuf Raw receive buffer.
ssizerxChunkSize Rx chunk size.
intrxChunkState Rx chunk encoding state.
char *rxEndp Pointer to end of raw data in input beyond endp.
ssizerxLen Rx content length.
ssizerxRemaining Remaining content to read from client.
struct WebsSession *session Session record.
intsid Socket id (handler).
WebsTimesince Parsed if-modified-since time.
void *ssl SSL context.
intstate Current state.
inttimeout Timeout handle.
WebsTimetimestamp Last transaction with browser.
ssizetxChunkLen Length of the chunk.
chartxChunkPrefix[16] Transmit chunk prefix.
ssizetxChunkPrefixLen Length of prefix.
char *txChunkPrefixNext Current I/O pos in txChunkPrefix.
inttxChunkState Transmit chunk state.
ssizetxLen Tx content length header value.
intupfd Upload file handle.
intuploadState Current file upload state.
char *uploadTmp Current temp filename for upload data.
char *uploadVar Current upload form variable name.
char *url Full request url. This is not decoded.
struct WebsUser *user User auth record.
char *userAgent User agent (browser).
char *username Authorization username.
WebsHashvars CGI standard variables.
intwid Index into webs.
WebsWriteProcwriteData Handler write I/O event callback. Used by fileHandler.
ssizewritten Bytes actually transferred.
void sslClose ()

Close the ssl module.

See Also:
void sslFree (Webs *wp)

Free a ssl connection associated with a request.

Parameters:
wpWebs request object.
See Also:
int sslOpen ()

Open the ssl module.

Returns:
Zero if successful, otherwise -1.
See Also:
ssize sslRead (Webs *wp, void *buf, ssize len)

Read data from a secure socket.

Parameters:
wpWebs request object.
bufBuffer into which to read data.
lenSize of buf.
Returns:
Count of bytes read if successful, otherwise -1.
See Also:
int sslUpgrade (Webs *wp)

Upgrade a request connection to utilize SSL.

Description:
This routine is invoked on a connection received on a secure listening socket.
Parameters:
wpWebs request object.
Returns:
Zero if successful, otherwise -1.
See Also:
ssize sslWrite (Webs *wp, void *buf, ssize len)

WRite data to a secure socket.

Parameters:
wpWebs request object.
bufBuffer from which to write data.
lenSize of buf.
Returns:
Count of bytes written if successful, otherwise -1.
See Also:
int websAccept (int sid, char *ipaddr, int port, int listenSid)

Accept a new connection.

Parameters:
sidSocket ID handle for the newly accepted socket.
ipaddrIP address originating the connection.
portPort number originating the connection.
listenSidSocket ID of the listening socket.
Returns:
Zero if successful, otherwise -1.
See Also:
void websActionOpen ()

Open the action handler.

See Also:
int websAlloc (int sid)

Allocate a new Webs object.

Parameters:
sidSocket ID handle for the newly accepted socket.
Returns:
The webs[] handle index for the allocated Webs object.
See Also:
void websCancelTimeout (Webs *wp)

Cancel the request timeout.

Description:
Handlers may choose to manually manage the request timeout. This routine will disable the centralized management of the timeout for this request.
Parameters:
wpWebs request object.
See Also:
int websCgiHandler (Webs *wp)

CGI handler service callback.

Parameters:
wpWebs object.
Returns:
Returns 1 if the request was handled.
See Also:
int websCgiOpen ()

Open the CGI handler.

Returns:
Zero if successful, otherwise -1.
See Also:
WebsTime websCgiPoll ()

Poll for output from CGI processes and output.

Returns:
Time delay till next poll.
See Also:
void websClose ()

Close the core GoAhead web server module.

Description:
Invoked when GoAhead is shutting down.
See Also:
void websCloseFile (int fd)

Close an open file.

Parameters:
fdOpen file handle returned by websOpenFile.
See Also:
int websCompareVar (Webs *wp, char *var, char *value)

Compare a request variable.

Parameters:
wpWebs request object.
varVariable name.
valueValue to compare with.
Returns:
True if the value matches. Otherwise return 0.
See Also:
void websConsumeInput (Webs *wp, ssize nbytes)

Consume input from the request input buffer.

Description:
This is called by handlers when consuming data from the request input buffer. This call updates the input service pointers and compacts the input buffer if required.
Parameters:
wpWebs request object.
nbytesNumber of bytes the handler has consumed from the input buffer.
See Also:
char * websDecode64 (char *str)

Decode the string using base-64 encoding.

Description:
This modifies the original string.
Parameters:
strString to decode.
Returns:
The original string.
See Also:
char * websDecode64Block (char *str, ssize *len, int flags)

Decode a block using base-46 encoding.

Parameters:
strString to decode. The string must be null terminated.
lenReference to an integer holding the length of the decoded string.
flagsReserved.
Returns:
The original string.
See Also:
void websDecodeUrl (char *decoded, char *input, ssize len)

Decode a URL expanding NN encoding.

Description:
Supports insitu decoding. i.e. Input and output buffers may be the same.
Parameters:
decodedBuffer to hold the decoded URL.
inputInput URL or buffer to decode.
lenLength of the decoded buffer.
See Also:
int websDefineAction (char *name, void *fun)

Define an action callback for use with the action handler.

Description:
The action handler binds a C function to a URI under "/action".
Parameters:
nameURI path suffix. This suffix is added to "/action" to form the bound URI path.
funCallback function. The signature is void (*WebsAction)(Webs *wp);.
Returns:
Zero if successful, otherwise -1.
See Also:
int websDefineHandler (char *name, WebsHandlerProc service, WebsHandlerClose close, int flags)

Define a request handler.

Parameters:
nameName of the handler.
serviceHandler callback service procedure. Invoked to service each relevant request.
closeHandler callback close procedure. Called when GoAhead is shutting down.
flagsSet to WEBS_LEGACY_HANDLER to support the legacy handler API calling sequence.
Returns:
Zero if successful, otherwise -1.
See Also:
int websDefineJst (char *name, WebsJstProc fn)

Define a Javscript native function.

Description:
This routine binds a C function to a Javascript function. When the Javascript function is called, the C function is invoked.
Parameters:
nameJavascript function name.
fnC function to invoke.
Returns:
Zero if successful, otherwise -1.
See Also:
void websDone (Webs *wp)

Complete a request.

Description:
A handler should call websDone() to complete the request.
Parameters:
wpWebs request object.
See Also:
char * websEncode64 (char *str)

Encode a string using base-64 encoding.

Description:
The string is encoded insitu.
Parameters:
strString to encode.
Returns:
The original string.
See Also:
char * websEncode64Block (char *str, ssize len)

Encode a block using base-64 encoding.

Description:
The string is encoded insitu.
Parameters:
strString to encode.
lenLength of string to encode.
Returns:
The original string.
See Also:
void websError (Webs *wp, int code, char *fmt, ...)

Complete a request with an error response.

Parameters:
wpWebs request object.
codeHTTP status code.
fmtMessage printf style format.
...Format args.
See Also:
char * websErrorMsg (int code)

Get a message for a HTTP status code.

Parameters:
codeHTTP status code.
Returns:
Http status message.
See Also:
char * websEscapeHtml (char *str)

Escape unsafe characters in a string.

Parameters:
strString to escape.
Returns:
An allocated block containing the escaped string. Caller must free.
See Also:
void websFileOpen ()

Open and initialize the file handler.

See Also:
bool websFlush (Webs *wp)

Flush buffered transmit data and compact the transmit buffer to make room for more data.

Parameters:
wpWebs request object.
Returns:
True if the contents of the transmit buffer are fully written and the buffer is now empty.
See Also:
void websFree (Webs *wp)

Free the webs request object.

Description:
Callers should call websDone to complete requests prior to invoking websFree.
Parameters:
wpWebs request object.
See Also:
void websFreeUpload (Webs *wp)

Free file upload data structures.

Parameters:
wpWebs request object.
See Also:
void websFsClose ()

Close the file system module.

See Also:
int websFsOpen ()

Open the file system module.

Returns:
Zero if successful, otherwise -1.
See Also:
int websGetBackground ()

Get the background execution flag.

Description:
If GoAhead is invoked with background, it will run as a daemon in the background.
Returns:
True if GoAhead is running in the background.
See Also:
char * websGetCgiCommName ()

Get a unique temporary filename for CGI communications.

Returns:
Filename string.
See Also:
char * websGetCookie (Webs *wp)

Get the request cookie if supplied.

Parameters:
wpWebs request object.
Returns:
Cookie string if defined, otherwise null.
See Also:
char * websGetDateString (WebsFileInfo *sbuf)

Get a date as a string.

Description:
If sbuf is supplied, it is used to calculate the date. Otherwise, the current time is used.
Parameters:
sbufFile info object.
Returns:
An allocated date string. Caller should free.
See Also:
int websGetDebug ()

Get the debug flag.

Description:
If GoAhead is invoked with debugger, the debug flag will be set to true.
Returns:
True if GoAhead is running in debug mode.
See Also:
char * websGetDir (Webs *wp)

Get the base file directory for a request.

Description:
Returns the request route directory if defined, otherwise returns the documents directory.
Parameters:
wpWebs request object.
Returns:
Path name string. Caller should not free.
See Also:
char * websGetDocuments ()

Get the GoAhead base documents directory.

Description:
The documents directory is defined at build time and may be overridden by the GoAhead command line.
Returns:
Path string for the documents directory.
See Also:
int websGetEof (Webs *wp)

Get the request EOF status.

Description:
The request EOF status is set to true when all the request body (POST|PUT) data has been received.
Parameters:
wpWebs request object.
Returns:
True if all the request body data has been received.
See Also:
char * websGetExt (Webs *wp)

Get the request URI extension.

Parameters:
wpWebs request object.
Returns:
The URI filename extension component. Caller should not free.
See Also:
char * websGetFilename (Webs *wp)

Get the request filename.

Description:
The URI is mapped to a filename by decoding and prepending with the request directory.
Parameters:
wpWebs request object.
Returns:
Filename string. Caller should not free.
See Also:
char * websGetHost (Webs *wp)

Get the request host.

Description:
The request host is set to the Host HTTP header value if it is present. Otherwise it is set to the request URI hostname.
Parameters:
wpWebs request object.
Returns:
Host string. Caller should not free.
See Also:
char * websGetIfaddr (Webs *wp)

Get the request interface address.

Parameters:
wpWebs request object.
Returns:
Network interface string. Caller should not free.
See Also:
char * websGetIndex ()

Get the default index document name.

Description:
The default index is "index.html" and can be updated via websSetIndex.
Returns:
Index name string. Caller should not free.
See Also:
int websGetLogLevel ()

Get the current trace log level.

Returns:
Number between 0 and 9.
See Also:
char * websGetMethod (Webs *wp)

Get the request method.

Parameters:
wpWebs request object.
Returns:
HTTP method string. Caller should not free.
See Also:
char * websGetPassword (Webs *wp)

Get the request password.

Description:
The request password may be encoded depending on the authentication scheme. See wp->encoded to test if it is encoded.
Parameters:
wpWebs request object.
Returns:
Password string. Caller should not free.
See Also:
char * websGetPath (Webs *wp)

Get the request path.

Description:
The URI path component excludes the http protocol, hostname, port, reference and query components. It always beings with "/".
Parameters:
wpWebs request object.
Returns:
Request path string. Caller should not free.
See Also:
int websGetPort (Webs *wp)

Get the request TCP/IP port.

Parameters:
wpWebs request object.
Returns:
TCP/IP Port integer.
See Also:
char * websGetProtocol (Webs *wp)

Get the request HTTP protocol.

Description:
This will be set to either "http" or "https".
Parameters:
wpWebs request object.
Returns:
Protocol string. Caller should not free.
See Also:
char * websGetQuery (Webs *wp)

Get the request query component.

Parameters:
wpWebs request object.
Returns:
Request query string. Caller should not free.
See Also:
char * websGetServer ()

Get the server host name.

Returns:
Host name string. Caller should not free.
See Also:
char * websGetServerAddress ()

Get the server IP address.

Returns:
Server IP address string. Caller should not free.
See Also:
char * websGetServerAddressUrl ()

Get the server IP address with port number.

Returns:
Server IP:PORT address string. Caller should not free.
See Also:
char * websGetServerUrl ()

Get the server host name with port number.

Returns:
Host name string with port number. Caller should not free.
See Also:
char * websGetUrl (Webs *wp)

Get the request URI.

Description:
This returns the request URI. This may be modified if the request is rewritten via websRewrite.
Parameters:
wpWebs request object.
Returns:
URI string. Caller should not free.
See Also:
char * websGetUserAgent (Webs *wp)

Get the client User-Agent HTTP header.

Parameters:
wpWebs request object.
Returns:
User-Agent string. Caller should not free.
See Also:
char * websGetUsername (Webs *wp)

Get the request username.

Description:
If the request is authenticated, this call returns the username supplied during authentication.
Parameters:
wpWebs request object.
Returns:
Username string if defined, otherwise null. Caller should not free.
See Also:
char * websGetVar (Webs *wp, char *name, char *defaultValue)

Get a request variable.

Description:
Request variables are defined for HTTP headers of the form HTTP_*. Some request handlers also define their own variables. For example: CGI environment variables.
Parameters:
wpWebs request object.
nameVariable name.
defaultValueDefault value to return if the variable is not defined.
Returns:
Variable value string. Caller should not free.
See Also:
int websJstOpen ()

Open the Javascript module.

Returns:
Zero if successful, otherwise -1.
See Also:
int websJstWrite (int jid, Webs *wp, int argc, char **argv)

Write data to the response.

Parameters:
jidJavascript ID handle.
wpWebs request object.
argcCount of arguments.
argvArray arguments.
Returns:
Zero if successful, otherwise -1.
See Also:
int websListen (char *endpoint)

Listen on a TCP/IP address endpoint.

Description:
The URI is mapped to a filename by decoding and prepending with the request directory. For IPv6 addresses, use the format: [aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh:iiii]:port.
Parameters:
endpointIPv4 or IPv6 address on which to listen.
Returns:
Positive integer holding a Socket ID handle if successful, otherwise -1.
See Also:
char * websMD5 (char *str)

Get an MD5 digest of a string.

Parameters:
strString to analyze.
Returns:
Allocated MD5 checksum. Caller should free.
See Also:
char * websMD5Block (char *buf, ssize length, char *prefix)

Get an MD5 digest of a block and optionally prepend a prefix.

Parameters:
bufBlock to analyze.
lengthLength of block.
prefixOptional prefix to prepend to the MD5 sum.
Returns:
Allocated MD5 checksum. Caller should free.
See Also:
char * websNormalizeUriPath (char *path)

Normalize a URI path.

Description:
This removes "./", "../" and redundant separators.
Parameters:
pathURI path to normalize.
Returns:
A normalized URI path. Caller should not free.
See Also:
void websNoteRequestActivity (Webs *wp)

Take not of the request activity and mark the time.

Description:
This is used to defer the request timeout whenever there is request I/O activity.
Parameters:
wpWebs request object.
See Also:
int websOpen (char *documents, char *routes)

Open the web server.

Description:
This initializes the web server and defines the documents directory.
Parameters:
documentsOptional web documents directory. If set to null, the build time BIT_GOAHEAD_DOCUMENTS value is used for the documents directory.
routesOptional filename for a route configuration file to load. Additional route or authentication configuration files can be loaded via websLoad.
routesWebs request object.
Returns:
Zero if successful, otherwise -1.
See Also:
int websOpenFile (char *path, int flags, int mode)

Open the web page document for the current request.

Parameters:
pathFilename path to open.
flagsFile open flags.
modePermissions mask.
Returns:
Positive file handle if successful, otherwise -1.
See Also:
int websOptionsOpen ()

Open the options handler.

Returns:
Zero if successful, otherwise -1.
See Also:
void websOsClose ()

Close the O/S dependant code.

Description:
Called from websClose.
See Also:
int websOsOpen ()

Open the O/S dependant code.

Description:
Called from websOpen.
Returns:
Zero if successful, otherwise -1.
See Also:
void websPageClose (Webs *wp)

Close the document page.

Parameters:
wpWebs request object.
See Also:
int websPageIsDirectory (Webs *wp)

Test if the document page for the request corresponds to a directory.

Parameters:
wpWebs request object.
Returns:
True if the filename is a directory.
See Also:
int websPageOpen (Webs *wp, int mode, int perms)

Open a web page document for a request.

Parameters:
wpWebs request object.
modeFile open mode. Select from O_RDONLY and O_BINARY. Rom files systems ignore this argument.
permsIgnored.
Returns:
File handle if successful, otherwise -1.
See Also:
ssize websPageReadData (Webs *wp, char *buf, ssize size)

Read data from the request page document.

Parameters:
wpWebs request object.
bufBuffer for the read data.
sizeSize of buf.
Returns:
Count of bytes read if successful, otherwise -1.
See Also:
void websPageSeek (Webs *wp, Offset offset, int origin)

Seek to a position in the request page document.

Parameters:
wpWebs request object.
offsetOffset of location in the file to seek to. This is relative to the specified origin.
originSet to SEEK_CUR, SEEK_SET or SEEK_END to position relative to the current position, beginning or end of the document.
See Also:
int websPageStat (Webs *wp, WebsFileInfo *sbuf)

Get file status for the current request document.

Parameters:
wpWebs request object.
sbufFile information structure to modify with file status.
Returns:
Zero if successful, otherwise -1.
See Also:
int websProcessCgiData (Webs *wp)

Process CGI request body data.

Parameters:
wpWebs request object.
Returns:
Zero if successful, otherwise -1.
See Also:
int websProcessUploadData (Webs *wp)

Process upload data for form, multipart mime file upload.

Parameters:
wpWebs request object.
Returns:
Zero if successful, otherwise -1.
See Also:
void websPump (Webs *wp)

Pump the state machine.

Description:
This routine will advance the connection state machine in response to events.
Parameters:
wpWebs request object.
See Also:
ssize websReadFile (int fd, char *buf, ssize size)

Read data from an open file.

Parameters:
fdOpen file handle returned by websOpenFile.
bufBuffer for the read data.
sizeSize of buf.
Returns:
Count of bytes read if successful, otherwise -1.
See Also:
char * websReadWholeFile (char *path)

Read all the data from a file.

Parameters:
pathFile path to read from.
Returns:
An allocated buffer containing the file data with an appended null. Caller must free.
See Also:
void websRedirect (Webs *wp, char *url)

Redirect the client to a new URL.

Description:
This creates a response to the client with a Location header directing the client to a new location. The response uses a 302 HTTP status code.
Parameters:
wpWebs request object.
urlURL to direct the client to.
See Also:
int websRedirectByStatus (Webs *wp, int status)

Redirect the client to a new URI.

Description:
The routing configuration file can define redirection routes for various HTTP status codes. This routine will utilize the appropriate route redirection based on the request route and specified status code.
Parameters:
wpWebs request object.
statusHTTP status code to use in selecting the route redirection.
Returns:
Zero if successful, otherwise -1.
See Also:
void websResponse (Webs *wp, int status, char *msg)

Create and send a request response.

Description:
This creates a response for the current request using the specified HTTP status code and the supplied message.
Parameters:
wpWebs request object.
statusHTTP status code.
msgResponse message body.
Returns:
Zero if successful, otherwise -1.
See Also:
int websRewriteRequest (Webs *wp, char *url)

Rewrite a request.

Description:
Handlers may choose to not process a request but rather rewrite requests and then reroute.
Parameters:
wpWebs request object.
urlNew request URL.
Returns:
Zero if successful, otherwise -1.
See Also:
void websRuntimeClose ()

Close the runtime code.

Description:
Called from websClose.
See Also:
int websRuntimeOpen ()

Open the runtime code.

Description:
Called from websOpen.
Returns:
Zero if successful.
See Also:
Offset websSeekFile (int fd, Offset offset, int origin)

Seek to a position in the current request page document.

Parameters:
fdOpen file handle returned by websOpenFile.
offsetLocation in the file to seek to.
originSet to SEEK_CUR, SEEK_SET or SEEK_END to position relative to the current position, beginning or end of the document.
See Also:
int websServer (char *endpoint, char *documents)

One line embedding API.

Description:
This call will also open auth.txt and route.txt for authentication and routing configuration.
Parameters:
endpointIP:PORT address on which to listen.
documentsDirectory containing web documents to serve.
See Also:
void websServiceEvents (int *finished)

Service I/O events until finished.

Description:
This will wait for socket events and service those until *finished is set to true.
Parameters:
finishedInteger location to test. If set to true, then exit. Note: setting finished will not automatically wake up the service routine.
See Also:
void websSetBackground (int on)

Set the background processing flag.

Parameters:
onValue to set the background flag to.
See Also:
void websSetCookie (Webs *wp, char *name, char *value, char *path, char *domain, WebsTime lifespan, int flags)

Define a cookie to include in the response.

Parameters:
wpWebs request object.
nameCookie name.
valueCookie value.
pathURI path prefix applicable for this cookie.
domainDomain applicable for this cookie.
lifespanCookie lifespan in secons.
flagsSet to WEBS_COOKIE_SECURE for https only. Set to WEBS_COOKIE_HTTP for http only. Otherwise the cookie applies to both http and https requests.
Returns:
Zero if successful, otherwise -1.
See Also:
void websSetDebug (int on)

Set the debug processing flag.

Parameters:
onValue to set the debug flag to.
See Also:
void websSetDocuments (char *dir)

Set the web documents directory.

Description:
The web documents directory is used when resolving request URIs into filenames.
Parameters:
dirDirectory path to use.
See Also:
void websSetEnv (Webs *wp)

Create the CGI environment variables for the current request.

Parameters:
wpWebs request object.
See Also:
void websSetFormVars (Webs *wp)

Create request variables for query and POST body data.

Description:
This creates request variables if the request is a POST form (has a Content-Type of application/x-www-form-urlencoded). The POST body data is consumed from the input buffer.
Parameters:
wpWebs request object.
See Also:
void websSetHost (char *host)

Define the host name for the server.

Parameters:
hostString host name.
See Also:
void websSetIndex (char *filename)

Create and send a request response.

Description:
This creates a response for the current request using the specified HTTP status code and the supplied message.
Parameters:
filenameWeb document name to use as the index. This should not contain any directory components.
See Also:
void websSetIpAddr (char *ipaddr)

Define the host IP address.

Parameters:
ipaddrHost IP address.
See Also:
void websSetQueryVars (Webs *wp)

Create request variables for query string data.

Parameters:
wpWebs request object.
See Also:
void websSetStatus (Webs *wp, int status)

Set the response HTTP status code.

Parameters:
wpWebs request object.
statusHTTP status code.
See Also:
void websSetTxLength (Webs *wp, ssize length)

Set the response body content length.

Parameters:
wpWebs request object.
lengthLength value to use.
See Also:
void websSetVar (Webs *wp, char *name, char *value)

Set a request variable to a string value.

Description:
Request variables are defined for HTTP headers of the form HTTP_*. Some request handlers also define their own variables. For example: CGI environment variables.
Parameters:
wpWebs request object.
nameVariable name to set.
valueValue to set.
See Also:
void websSetVarFmt (Webs *wp, char *name, char *fmt, ...)

Set a request variable to a formatted string value.

Description:
Request variables are defined for HTTP headers of the form HTTP_*. Some request handlers also define their own variables. For example: CGI environment variables.
Parameters:
wpWebs request object.
nameVariable name to set.
fmtValue format string.
...Args to format.
See Also:
int websStatFile (char *path, WebsFileInfo *sbuf)

Get file status for a file.

Parameters:
pathFilename path.
sbufFile information structure to modify with file status.
Returns:
Zero if successful, otherwise -1.
See Also:
char * websTempFile (char *dir, char *prefix)

Create a temporary filename This does not guarantee the filename is unique or that it is not already in use by another application.

Parameters:
dirDirectory to locate the temp file. Defaults to the O/S default temporary directory (usually /tmp).
prefixFilename prefix.
Returns:
An allocated filename string.
See Also:
bool websTestVar (Webs *wp, char *name)

Test if a request variable is defined.

Parameters:
wpWebs request object.
nameVariable name.
Returns:
True if the variable is defined.
See Also:
int websUrlParse (char *url, char **buf, char **protocol, char **host, char **port, char **path, char **ext, char **reference, char **query)

Parse a URL into its components.

Parameters:
urlURL to parse.
bufBuffer to hold storage for various parsed components. Caller must free. NOTE: the parsed components may point to locations in this buffer.
protocolParsed URL protocol component.
hostParsed hostname.
portParsed URL port.
pathParsed URL path component.
extParsed URL extension.
referenceParsed URL reference portion (#reference).
queryParsed URL query component.
Returns:
Zero if successful, otherwise -1.
See Also:
bool websValid (Webs *wp)

Test if a webs object is valid.

Description:
After calling websDone, the websFree routine will have been called and the memory for the webs object will be released. Call websValid to test an object hand for validity.
Parameters:
wpWebs request object.
Returns:
True if the webs object is still valid and the request has not been completed.
See Also:
ssize websWrite (Webs *wp, char *fmt, ...)

Write data to the response.

Description:
The data is buffered and will be sent to the client when the buffer is full or websFlush is called.
Parameters:
wpWebs request object.
fmtPrintf style format string.
...Arguments to the format string.
Returns:
Count of bytes written.
See Also:
ssize websWriteBlock (Webs *wp, char *buf, ssize size)

Write a block of data to the response.

Description:
The data is buffered and will be sent to the client when the buffer is full or websFlush is called.
Parameters:
wpWebs request object.
bufBuffer of data to write.
sizeLength of buf.
Returns:
Count of bytes written. This will always equal size if there are not errors.
See Also:
void websWriteEndHeaders (Webs *wp)

Signify the end of the response headers.

Description:
This call concludes the response headers and writes a blank line to the response.
Parameters:
wpWebs request object.
See Also:
ssize websWriteFile (int fd, char *buf, ssize size)

Write data to the open file.

Parameters:
fdOpen file handle returned by websOpenFile.
bufBuffer for the read data.
sizeSize of buf.
Returns:
Count of bytes read if successful, otherwise -1.
See Also:
int websWriteHeader (Webs *wp, char *key, char *fmt, ...)

Write a response header.

Description:
This routine writes a response header. It should be invoked after calling websWriteHeaders to write the standard headers and before websWriteEndHeaders. This routine differs from websWrite in that it traces header values to the log.
Parameters:
wpWebs request object.
keyHeader key value.
fmtHeader value format string.
...Arguments to the format string.
Returns:
Zero if successful, otherwise -1.
See Also:
void websWriteHeaders (Webs *wp, ssize contentLength, char *redirect)

Write a set of standard response headers.

Parameters:
wpWebs request object.
contentLengthValue for the Content-Length header which describes the length of the response body.
redirectValue for the Location header which redirects the client to a new URL.
See Also:
websSetStatus
ssize websWriteSocket (Webs *wp, char *buf, ssize size)

Write a block of data to the network.

Description:
This bypassed output buffering and is the lowest level write.
Parameters:
wpWebs request object.
bufBuffer of data to write.
sizeLength of buf.
Returns:
Count of bytes written. Returns -1 on errors. May return having written less than requested.
See Also:

WebsAuth

WebsAuth

GoAhead Authentication.

Fields:
WebsRole * websAddRole (char *role, WebsHash abilities)

Add a role.

Description:
The role is added to the list of roles.
Parameters:
roleRole name.
abilitiesHash of abilities for the role.
Returns:
The allocated role.
See Also:
WebsUser * websAddUser (char *username, char *password, char *roles)

Add a user.

Description:
The user is added to the list of users.
Parameters:
usernameUser name.
passwordUser password (encrypted).
rolesSpace separated list of roles. This may also contain abilities.
Returns:
User object.
See Also:
bool websAuthenticate (Webs *wp)

Authenticate a user.

Description:
The user is authenticated if required by the selected request route.
Returns:
True if the route does not require authentication or the user is authenticated successfully.
See Also:
bool websCan (Webs *wp, WebsHash ability)

Test if a user possesses the required ability.

Parameters:
wpWebs request object.
abilitySet of required abilities.
Returns:
True if the user has the required ability.
See Also:
void websCloseAuth ()

Close the authentication module.

See Also:
void websComputeAllUserAbilities ()

Compute the abilities for all users by resolving roles into abilities.

See Also:
WebsVerify websGetPasswordStoreVerify ()

Set the password store verify callback.

Returns:
Verify WebsVerify callback function.
See Also:
WebsHash websGetRoles ()

Get the roles hash.

Returns:
The roles hash object.
See Also:
WebsHash websGetUsers ()

Get the users hash.

Returns:
The users hash object.
See Also:
bool websLoginUser (Webs *wp, char *username, char *password)

Login a user by verifying the login credentials.

Description:
This may be called by handlers to manually authenticate a user.
Parameters:
wpWebs request object.
usernameUser name.
passwordUser password (encrypted).
Returns:
True if the user can be authenticated.
See Also:
WebsUser * websLookupUser (char *username)

Lookup if a user exists.

Parameters:
usernameUser name to search for.
Returns:
User object or null if the user cannot be found.
See Also:
int websOpenAuth (int minimal)

Open the authentication module.

Parameters:
minimalReserved. Set to zero.
Returns:
True if the user has the required ability.
See Also:
int websRemoveRole (char *role)

Remove a role from the system.

Parameters:
roleRole name.
Returns:
Zero if successful, otherwise -1.
See Also:
int websRemoveUser (char *name)

Remove a user from the system.

Parameters:
nameUser name.
Returns:
Zero if successful, otherwise -1.
See Also:
void websSetPasswordStoreVerify (WebsVerify verify)

Set the password store verify callback.

Parameters:
verifyWebsVerify callback function.
See Also:
int websSetUserRoles (char *username, char *roles)

Define the set of roles for a user.

Parameters:
usernameUser name.
rolesSpace separated list of roles or abilities.
Returns:
Zero if successful, otherwise -1.
See Also:
bool websVerifyPasswordFromCustom (Webs *wp)

User password verification routine from a custom password back-end store.

Parameters:
wpWebs request object.
Returns:
True if the user password verifies.
See Also:
bool websVerifyPasswordFromFile (Webs *wp)

User password verification routine from auth.txt.

Parameters:
wpWebs request object.
Returns:
True if the user password verifies.
See Also:

WebsBuf

WebsBuf

A WebsBuf (ring queue) allows maximum utilization of memory for data storage and is ideal for input/output buffering.

Fields:
char *buf Holding buffer for data.
ssizebuflen Length of ring queue.
char *endbuf Pointer to end of buffer.
char *endp Pointer to end of data.
intincrement Growth increment.
ssizemaxsize Maximum size.
char *servp Pointer to start of data.
void bufAddNull (WebsBuf *bp)

Add a trailing null to the buffer.

The end pointer is not changed
Parameters:
bpBuffer reference.
See Also:
void bufAdjustEnd (WebsBuf *bp, ssize size)

Adjust the endp pointer by the specified size.

Description:
This is useful after manually copying data into the buffer and needing to adjust the end pointer.
Parameters:
bpBuffer reference.
sizeSize of adjustment. May be positive or negative value.
See Also:
void bufAdjustStart (WebsBuf *bp, ssize count)

Adjust the start (servp) reference.

Parameters:
bpBuffer reference.
countNumber of bytes to adjust.
See Also:
void bufCompact (WebsBuf *bp)

Compact the data in the buffer and move to the start of the buffer.

Parameters:
bpBuffer reference.
See Also:
int bufCreate (WebsBuf *bp, int increment, int maxsize)

Create a buffer.

Parameters:
bpBuffer reference.
incrementIncremental size to grow the buffer. This will be increased by a power of two each time the buffer grows.
maxsizeMaximum size of the buffer.
Returns:
Zero if successful.
See Also:
void bufFlush (WebsBuf *bp)

Flush all data in the buffer and reset the pointers.

Parameters:
bpBuffer reference.
See Also:
void bufFree (WebsBuf *bp)

Free allocated storage for the buffer.

Parameters:
bpBuffer reference.
Returns:
Zero if successful.
See Also:
ssize bufGetBlk (WebsBuf *bp, char *blk, ssize len)

Copy a block of from the buffer and adjust the servp.

Parameters:
bpBuffer reference.
blkBlock into which to place the data.
lenLength of the block.
Returns:
Number of bytes copied.
See Also:
ssize bufGetBlkMax (WebsBuf *bp)

Return the maximum number of bytes the buffer can provide via a single block copy.

Description:
Useful if the user is doing their own data retrieval.
Parameters:
bpBuffer reference.
Returns:
Number of bytes available for copying.
See Also:
int bufGetc (WebsBuf *bp)

Get a character from the buffer and increment the servp.

Parameters:
bpBuffer reference.
Returns:
The next character or -1 if the buffer is empty.
See Also:
bool bufGrow (WebsBuf *bp, ssize room)

Grow the buffer by at least the required amount of room.

Parameters:
bpBuffer reference.
roomAvailable size required after growing the buffer.
Returns:
True if the buffer can be grown to have the required amount of room.
See Also:
int bufInsertc (WebsBuf *bp, char c)

Insert a character to the buffer before the servp position and decrement the servp.

Parameters:
bpBuffer reference.
cCharacter to insert.
Returns:
Zero if successful.
See Also:
ssize bufLen (WebsBuf *bp)

Get the length of available data in the buffer.

Parameters:
bpBuffer reference.
Returns:
Size of available data in bytes.
See Also:
ssize bufPutBlk (WebsBuf *bp, char *blk, ssize len)

Put a block to the buffer.

Parameters:
bpBuffer reference.
blkBlock to append to the buffer.
lenSize of the block.
Returns:
Length of data appended. Should equal len.
See Also:
int bufPutc (WebsBuf *bp, char c)

Append a character to the buffer at the endp position and increment the endp.

Parameters:
bpBuffer reference.
cCharacter to append.
Returns:
Zero if successful.
See Also:
ssize bufPutStr (WebsBuf *bp, char *str)

Append a string to the buffer at the endp position and increment the endp.

Parameters:
bpBuffer reference.
strString to append.
Returns:
Count of characters appended. Returns negative if there is an allocation error.
See Also:
void bufReset (WebsBuf *bp)

Reset the buffer pointers to the start of the buffer if empty.

Parameters:
bpBuffer reference.
See Also:
ssize bufRoom (WebsBuf *bp)

Determine the room available in the buffer.

Description:
This returns the maximum number of bytes the buffer can absorb in a single block copy.
Parameters:
bpBuffer reference.
Returns:
Number of bytes of availble space.
See Also:
char * bufStart (WebsBuf *bp)

Get a reference to the start of buffer data.

Parameters:
bpBuffer reference.
Returns:
A string pointer.
See Also:

WebsHash

WebsHash

Hash table entry structure.

Description:
The hash structure supports growable hash tables with high performance, collision resistant hashes. Each hash entry has a descriptor entry. This is used to manage the hash table link chains.
See Also:
hashCreate, hashDelete, hashEnter, hashFirst, hashFree, hashLookup, hashNext
Fields:
WebsHash hashCreate (int size)

Create a hash table.

Parameters:
sizeMinimum size of the hash index.
Returns:
Hash table ID.
See Also:
hashDelete, hashEnter, hashFirst, hashFree, hashLookup, hashNext
int hashDelete (WebsHash id, char *name)

Delete a key by name.

Parameters:
idHash table id returned by hashCreate.
nameKey name to delete.
Returns:
Zero if the delete was successful. Otherwise -1 if the key was not found.
See Also:
hashCreate, hashEnter, hashFirst, hashFree, hashLookup, hashNext
WebsKey * hashEnter (WebsHash id, char *name, WebsValue value, int arg)

Enter a new key and value into the hash table.

Parameters:
idHash table id returned by hashCreate.
nameKey name to create.
valueKey value to enter.
argOptional extra argument to store with the value.
Returns:
Reference to the WebKey object storing the key and value.
See Also:
hashCreate, hashDelete, hashFirst, hashFree, hashLookup, hashNext
WebsKey * hashFirst (WebsHash id)

Start walking the hash keys by returning the first key entry in the hash.

Parameters:
idHash table id returned by hashCreate.
Returns:
Reference to the first WebKey object. Return null if there are no keys in the hash.
See Also:
hashCreate, hashDelete, hashEnter, hashFree, hashLookup, hashNext
void hashFree (WebsHash id)

Free a hash table.

Parameters:
idHash table id returned by hashCreate.
See Also:
hashCreate, hashDelete, hashEnter, hashFirst, hashLookup, hashNext
WebsKey * hashLookup (WebsHash id, char *name)

Lookup a name in the hash table.

Parameters:
idHash table id returned by hashCreate.
nameKey name to search for.
Returns:
Reference to the WebKey object storing the key and value.
See Also:
hashCreate, hashDelete, hashEnter, hashFirst, hashFree, hashNext
WebsKey * hashNext (WebsHash id, WebsKey *last)

Continue walking the hash keys by returning the next key entry in the hash.

Parameters:
idHash table id returned by hashCreate.
lastReference to a WebsKey to hold the current traversal key state.
Returns:
Reference to the next WebKey object. Returns null if no more keys exist to be traversed.
See Also:
hashCreate, hashDelete, hashEnter, hashFirst, hashFree, hashLookup

WebsRoute

WebsRoute

Request route structure.

Fields:
WebsHashabilities Required user abilities.
WebsAskLoginaskLogin Route path prefix.
char *authType Authentication type.
char *dir Filesystem base directory for route documents.
WebsHashextensions Permissible URI extensions.
intflags Route control flags.
WebsHandler *handler Request handler to service requests.
WebsHashmethods Supported HTTP methods.
WebsParseAuthparseAuth Parse authentication details callback.
char *prefix Route path prefix.
ssizeprefixLen Prefix length.
char *protocol HTTP protocol to use for this route.
WebsHashredirects Response redirections.
WebsVerifyverify Verify password callback.
WebsRoute * websAddRoute (char *uri, char *handler, int pos)

Add a route to the routing tables.

Parameters:
uriMatching URI prefix.
handlerRequest handler to service routed requests.
posPosition in the list of routes. Zero inserts at the front of the list. A value of -1 will append to the end of the list.
Returns:
A route object.
See Also:
void websCloseRoute ()

Close the route module.

See Also:
int websLoad (char *path)

Load routing tables from the specified filename.

Parameters:
pathRoute configuration filename.
Returns:
Zero if successful, otherwise -1.
See Also:
int websOpenRoute ()

Open the routing module.

See Also:
int websRemoveRoute (char *uri)

Remove a route from the routing tables.

Parameters:
uriMatching URI prefix.
Returns:
Zero if successful, otherwise -1.
See Also:
void websRouteRequest (Webs *wp)

Route a request.

Description:
This routine will select a matching route and will invoke the selected route handler to service the request. In the process, authentication and request rewriting may take place.
Parameters:
wpWebs request object.
See Also:
int websSetRouteAuth (WebsRoute *route, char *authType)

Set route authentication scheme.

Parameters:
routeRoute to modify.
authTypeSet to "basic", "digest" or "form".
Returns:
Zero if successful, otherwise -1.
See Also:
int websSetRouteMatch (WebsRoute *route, char *dir, char *protocol, WebsHash methods, WebsHash extensions, WebsHash abilities, WebsHash redirects)

Configure a route by adding matching criteria.

Parameters:
routeRoute to modify.
dirSet the route documents directory filename.
protocolSet the matching HTTP protocol (http or https).
methodsHash of permissible HTTP methods. (GET, HEAD, POST, PUT).
extensionsHash of permissible URI filename extensions.
abilitiesRequired user abilities. The user must be authenticated.
abilitiesRequired user abilities. If abilities are required, the user must be authenticated.
redirectsSet of applicable response redirections when completing the request.
Returns:
Zero if successful, otherwise -1.
See Also:

WebsRuntime

WebsRuntime

GoAhead Web Server Runtime.

Description:
GoAhead provides a secure runtime environment for safe string manipulation and to help prevent buffer overflows and other potential security traps.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
Fields:
char * fmt (char *buf, ssize maxSize, char *format, ...)

Format a string into a static buffer.

Description:
This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.
Parameters:
bufPointer to the buffer.
maxSizeSize of the buffer.
formatPrintf style format string.
...Variable arguments to format.
Returns:
The buffer.
See Also:
hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
uint hextoi (char *str)

Convert a hex string to an integer.

Description:
This call converts the supplied string to an integer using base 16.
Parameters:
strPointer to the string to parse.
Returns:
The integer equivalent value of the string.
See Also:
fmt, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
char * itosbuf (char *buf, ssize size, int64 value, int radix)

Convert an integer to a string buffer.

Description:
This call converts the supplied 64 bit integer into a string formatted into the supplied buffer according to the specified radix.
Parameters:
bufPointer to the buffer that will hold the string.
sizeSize of the buffer.
valueInteger value to convert.
radixThe base radix to use when encoding the number.
Returns:
Returns a reference to the string.
See Also:
fmt, hextoi, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
int scaselesscmp (char *s1, char *s2)

Compare strings ignoring case.

This is a safe replacement for strcasecmp. It can handle NULL args
Description:
Compare two strings ignoring case differences. This call operates similarly to strcmp.
Parameters:
s1First string to compare.
s2Second string to compare.
Returns:
Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.
See Also:
fmt, hextoi, itosbuf, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
bool scaselessmatch (char *s1, char *s2)

Compare strings ignoring case.

This is similar to scaselesscmp but it returns a boolean
Description:
Compare two strings ignoring case differences.
Parameters:
s1First string to compare.
s2Second string to compare.
Returns:
Returns true if the strings are equivalent, otherwise false.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
char * sclone (char *str)

Clone a string.

Description:
Copy a string into a newly allocated block.
Parameters:
strPointer to the block to duplicate.
Returns:
Returns a newly allocated string.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
int scmp (char *s1, char *s2)

Compare strings.

Description:
Compare two strings. This is a safe replacement for strcmp. It can handle null args.
Parameters:
s1First string to compare.
s2Second string to compare.
Returns:
Returns zero if the strings are identical. Return -1 if the first string is less than the second. Return 1 if the first string is greater than the second.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
ssize scopy (char *dest, ssize destMax, char *src)

Copy a string.

Description:
Safe replacement for strcpy. Copy a string and ensure the destination buffer is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is always terminated with a null.
Parameters:
destPointer to a pointer that will hold the address of the allocated block.
destMaxMaximum size of the target string in characters.
srcString to copy.
Returns:
The number of characters in the target string.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
char * sfmt (char *format, ...)

Format a string.

This is a secure verion of printf that can handle null args
Description:
Format the given arguments according to the printf style format. See fmt() for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.
Parameters:
formatPrintf style format string.
...Variable arguments for the format string.
Returns:
Returns a newly allocated string.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
char * sfmtv (char *format, va_list args)

Format a string with varargs.

This is a secure verion of printf that can handle null args
Description:
Format the given arguments according to the printf style format. See fmt() for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.
Parameters:
formatPrintf style format string.
argsVarargs argument obtained from va_start.
Returns:
Returns a newly allocated string.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
ssize slen (char *str)

Return the length of a string.

Description:
Safe replacement for strlen. This call returns the length of a string and tests if the length is less than a given maximum. It will return zero for NULL args.
Parameters:
strString to measure.
Returns:
The length of the string.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
char * slower (char *str)

Convert a string to lower case.

Description:
Convert a string to its lower case equivalent.
Parameters:
strString to convert. This string is modified.
Returns:
Reference to the supplied str.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
bool smatch (char *s1, char *s2)

Compare strings.

Description:
Compare two strings. This is similar to scmp but it returns a boolean.
Parameters:
s1First string to compare.
s2Second string to compare.
Returns:
Returns true if the strings are equivalent, otherwise false.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
int sncaselesscmp (char *s1, char *s2, ssize len)

Compare strings ignoring case.

Description:
Compare two strings ignoring case differences for a given string length. This call operates similarly to strncasecmp.
Parameters:
s1First string to compare.
s2Second string to compare.
lenLength of characters to compare.
Returns:
Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
int sncmp (char *s1, char *s2, ssize len)

Compare strings.

Description:
Compare two strings for a given string length. This call operates similarly to strncmp.
Parameters:
s1First string to compare.
s2Second string to compare.
lenLength of characters to compare.
Returns:
Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
ssize sncopy (char *dest, ssize destMax, char *src, ssize count)

Copy characters from a string.

Description:
Safe replacement for strncpy. Copy bytes from a string and ensure the target string is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is terminated with a null.
Parameters:
destPointer to a pointer that will hold the address of the allocated block.
destMaxMaximum size of the target string in characters.
srcString to copy.
countMaximum count of characters to copy.
Returns:
Returns a reference to the destination if successful or NULL if the string won't fit.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, stok, supper, wallocHandle, wallocObject, wfreeHandle
char * stok (char *str, char *delim, char **last)

Tokenize a string.

Description:
Split a string into tokens.
Parameters:
strString to tokenize.
delimString of characters to use as token separators.
lastLast token pointer.
Returns:
Returns a pointer to the next token.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, supper, wallocHandle, wallocObject, wfreeHandle
char * supper (char *str)

Convert a string to upper case.

Description:
Convert a string to its upper case equivalent.
Parameters:
strString to convert. This string is modified.
Returns:
Returns a pointer to the converted string. Will always equal str.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, wallocHandle, wallocObject, wfreeHandle
int wallocHandle (void *map)

Allocate a handle from a map.

Parameters:
mapReference to a location holding the map reference. On the first call, the map is allocated.
Returns:
Integer handle index. Otherwise return -1 on allocation errors.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocObject, wfreeHandle
int wallocObject (void *map, int *max, int size)

Allocate an object in a halloc map.

Parameters:
mapReference to a location holding the map reference. On the first call, the map is allocated.
maxReference to an integer that holds the maximum handle in the map.
sizeSize of the object to allocate.
Returns:
Integer handle index. Otherwise return -1 on allocation errors.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wfreeHandle
void websRestartEvent (int id, int delay)

Restart an event.

Parameters:
idEvent id allocated by websStartEvent.
delayDelay in milliseconds till the event next runs.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
WebsTime websRunEvents ()

Run due events.

Returns:
Time till the next event.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
int websStartEvent (int delay, WebsEventProc proc, void *data)

Start a callback event.

Description:
This schedules an event to run once. The event can be rescheduled in the callback by invoking websRestartEvent.
Parameters:
delayDelay in milliseconds in which to run the callback.
procCallback procedure function. Signature is: void (*fn)(void *data, int id).
dataData reference to pass to the callback.
Returns:
A positive integer event ID.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
void websStopEvent (int id)

Stop an event.

Parameters:
idEvent id allocated by websStartEvent.
Returns:
Integer handle index. Otherwise return -1 on allocation errors.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
int wfreeHandle (void *map, int handle)

Free a handle in the map.

Parameters:
mapReference to a location to hold the map reference.
handleHandle to free in the map.
Returns:
Integer handle index. Otherwise return -1 on allocation errors.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject

WebsSession

WebsSession

Session state storage.

Fields:
WebsHashcache Cache of session variables.
WebsTimeexpires When the session expires.
char *id Session ID key.
WebsTimelifespan Session inactivity timeout (msecs).
WebsSession * websAllocSession (Webs *wp, char *id, WebsTime lifespan)

Test if a user possesses the required ability.

Parameters:
wpWebs request object.
idSession ID to use. Set to null to allocate a new session ID.
lifespanLifespan of the session in seconds.
Returns:
Allocated session object.
See Also:
WebsSession * websGetSession (Webs *wp, int create)

Get the session state object for the current request.

Parameters:
wpWebs request object.
createSet to true to create a new session if one does not already exist.
Returns:
Session object.
See Also:
char * websGetSessionID (Webs *wp)

Get the session ID.

Parameters:
wpWebs request object.
Returns:
The session ID if session state storage is defined for this request.
See Also:
char * websGetSessionVar (Webs *wp, char *name, char *defaultValue)

Get a session variable.

Parameters:
wpWebs request object.
nameSession variable name.
defaultValueDefault value to return if the variable does not exist.
Returns:
Session variable value or default value if it does not exist.
See Also:
void websRemoveSessionVar (Webs *wp, char *name)

Remove a session variable.

Parameters:
wpWebs request object.
nameSession variable name.
See Also:
int websSetSessionVar (Webs *wp, char *name, char *value)

Set a session variable name value.

Parameters:
wpWebs request object.
nameSession variable name.
valueValue to set the variable to.
Returns:
Zero if successful, otherwise -1.
See Also:

WebsSocket

WebsSocket

Socket control structure.

See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
Fields:
SocketAcceptaccept Accept handler.
intcurrentEvents Mask of ready events (FD_xx).
interror Last error.
intfileHandle ID of the file handler.
intflags Current state flags.
SocketHandlerhandler User I/O handler.
void *handler_data User handler data.
inthandlerMask Handler events of interest.
intinterestEvents Mask of events to watch for.
char *ip Server listen address or remote client address.
WebsBuflineBuf Line ring queue.
intport Port to listen on.
intsaveMask saved Mask for socketFlush.
intsecure Socket is using SSL.
intselectEvents Events being selected.
intsid Index into socket[].
Socketsock Actual socket handle.
int socketAddress (struct sockaddr *addr, int addrlen, char *ipbuf, int ipLen, int *port)

Extract the numerical IP address and port for the given socket info.

Parameters:
addrReference to the socket address.
addrlenLength of the socket address.
ipbufBuffer to contain the parsed IP address.
ipLenSize of ipbuf.
portReference to an integer to hold the parsed port.
Returns:
Zero if successful. Otherwise -1 for parse errors.
See Also:
socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
int socketAlloc (char *host, int port, SocketAccept accept, int flags)

Allocate a socket object.

Parameters:
hostString host IP address.
portSocket port.
acceptOptional SocketAccept accept callback function.
flagsControl flags.
Returns:
Socket ID handle to use with other APIs.
See Also:
socketAddress, socketAddressIsV6, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
int socketConnect (char *host, int port, int flags)

Connect to a server and create a new socket.

Parameters:
hostHost IP address.
portPort number to connect to.
flagsSet to SOCKET_BLOCK for blocking I/O. Otherwise non-blocking I/O is used.
Returns:
True if the address is an IPv6 address.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
void socketCreateHandler (int sid, int mask, SocketHandler handler, void *arg)

Create a socket handler that will be invoked when I/O events occur.

Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
maskMask of events of interest. Set to SOCKET_READABLE | SOCKET_WRITABLE | SOCKET_EXCEPTION.
handlerSocket handler function.
argArbitrary object reference to pass to the SocketHandler callback function.
Returns:
True if the address is an IPv6 address.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
bool socketEof (int sid)

Determine if the socket is at end-of-file for input.

Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
Returns:
True if the address is at EOF.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
int socketGetBlock (int sid)
Socket socketGetHandle (int sid)

Get the underlying socket operating system socket/file handle.

Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
Returns:
The socket handle.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
int socketGetPort (int sid)
void socketHiddenData (WebsSocket *sp, ssize len, int dir)

Indicate that the application layer has buffered data for the socket.

Description:
This is used by SSL and other network stacks that buffer pending data.
Parameters:
spSocket object returned from socketPtr
lenLength of buffered data in bytes.
dirBuffer direction. Set to MPR_READABLE for buffered read data and MPR_WRITABLE for buffered write data.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
int socketInfo (char *ip, int port, int *family, int *protocol, struct sockaddr_storage *addr, Socklen *addrlen)

Get a socket address structure for the specified IP:Port.

Description:
This returns address details in *family, *protocol, *addr, and *addrlen.
Parameters:
ipIP address to parse.
portTCP/IP port number.
familyReference to an integer to hold the address family.
protocolReference to an integer to hold the address protocol.
addrReference to an integer to hold the address structure.
addrlenReference to an integer to hold the address structure length.
Returns:
Zero if successful, otherwise -1.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
bool socketIsV6 (int sid)

Determine if a socket is bound to an IPv6 address.

Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
Returns:
True if the socket is using IPv6.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
int socketListen (char *host, int port, SocketAccept accept, int flags)

Open a listening socket.

Parameters:
hostHost IP address on which to listen. Set to NULL to listen on all interfaces.
portTCP/IP port on which to listen.
acceptSocketAccept callback function to invoke to receive incoming connections.
flagsReserved.
Returns:
Zero if successful, otherwise -1.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
int socketParseAddress (char *ipAddrPort, char **pip, int *pport, int *secure, int defaultPort)

Parse an IP address into its constituent parts.

Description:
Parse the IP address and return the IP address and port components. Handles ipv4 and ipv6 addresses. If the IP portion is absent, pip is set to null. If the port portion is absent, port is set to the defaultPort. If a ":</em>" port specifier is used, *pport is set to -1; When an address contains an ipv6 port it should be written as aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh:iiii or If supplied an IPv6 address, the backets are stripped in the returned IP address.
Parameters:
ipAddrPortIP address which may contain an optional ":port" component.
pipReturns a reference to an allocated string containing the IP address portion. Caller must free.
pportReference to an integer to hold the port component.
secureReference to an integer to be set to true if the address is using SSL/TLS.
defaultPortDefault port number to use if no port specifier is included in ipAddrPort.
Returns:
Zero if successful, otherwise -1.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
WebsSocket * socketPtr (int sid)
ssize socketRead (int sid, void *buf, ssize len)

Read data from a socket.

Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
bufBuffer to hold read data.
lenSize of the buffer.
Returns:
Count of bytes actually read. Returns -1 for errors and EOF. Distinguish between errors and EOF via socketEof()
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
void socketRegisterInterest (int sid, int mask)

Register interest in socket I/OEvents.

Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
maskMask of events of interest. Set to SOCKET_READABLE | SOCKET_WRITABLE | SOCKET_EXCEPTION.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
void socketReservice (int sid)

Request that the socket be reserviced.

Description:
This routine is useful when upper layers have unprocessed, buffered data for the socket. This routine will cause the socket I/O callback handler to be invoked soon in the future.
Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
int socketSelect (int sid, WebsTime timeout)

Wait for I/O on a socket.

Description:
This call uses the mask of events of interest defined by socketRegisterInterest. It blocks the caller until a suitable I/O event or timeout occurs.
Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
timeoutTimeout in milliseconds.
Returns:
Number of I/O events.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSetBlock, socketWaitForEvent, socketWrite
int socketSetBlock (int sid, int on)

Set the socket blocking mode.

Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
onSet to 1 to enable blocking.
Returns:
The previous blocking mode.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketWaitForEvent, socketWrite
int socketSetNoDelay (int sid, bool on)

Set the socket delay mode.

Description:
This is used to enable or disable the TCP Nagle algorithm.
Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
onSet to 1 to disable the Nagle algorithm.
Returns:
The previous blocking mode.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
int socketWaitForEvent (WebsSocket *sp, int mask)

Wait for a socket I/O event.

Parameters:
spSocket object.
maskMask of events of interest. Set to SOCKET_READABLE | SOCKET_WRITABLE | SOCKET_EXCEPTION.
Returns:
Zero if successful in waiting for the desired event, othewise return -1.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWrite
ssize socketWrite (int sid, void *buf, ssize len)

Write data to the socket.

Parameters:
sidSocket ID handle returned from socketConnect or socketAccept.
bufBuffer containing data to write.
lenSize of buf.
Returns:
Count of bytes written. May be less than len if the socket is in non-blocking mode. Returns -1 for errors.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent

WebsUpload

WebsUpload

File upload structure.

See Also:
websGetUpload, websLookupUpload, websUploadOpen
Fields:
char *clientFilename Client side name of the file.
char *contentType Content type.
char *filename Local (temp) name of the file.
ssizesize Uploaded file size.
WebsHash websGetUpload (struct Webs *wp)

Get the hash of uploaded files for the request.

Parameters:
wpWebs request object.
Returns:
Hash table of uploaded files.
See Also:
websLookupUpload, websUploadOpen
WebsUpload * websLookupUpload (struct Webs *wp, char *key)

Open the file upload filter.

Parameters:
wpWebs request object.
keyForm upload name.
Returns:
Upload object for the uploaded file.
See Also:
websGetUpload, websUploadOpen
void websUploadOpen ()

Open the file upload filter.

See Also:
websGetUpload, websLookupUpload

Functions

void assert (bool cond)

Assure that an assert condition is true.

Parameters:
condBoolean result of a conditional test.
void error (char *fmt, ...)

Emit an error message.

Returns:
Zero if successful.
void logClose ()

Close the log logging module.

void logmsgProc (int level, char *fmt, ...)

Emit a message to the log.

Description:
This emits a message at the specified level. GoAhead filters logging messages by defining a verbosity level at startup. Level 0 is the least verbose where only the most important messages will be output. Level 9 is the Logging support is enabled by the Bit setting: "logging: true" which creates the BIT_GOAHEAD_LOGGING define in bit.h most verbose. Level 2-4 are the most useful for debugging.
Parameters:
levelInteger verbosity level (0-9).
fmtPrintf style format string.
...Arguments for the format string.
int logOpen ()

Open the log logging module.

Returns:
Zero if successful.
WebsLogHandler logSetHandler (WebsLogHandler handler)

Set a log callback.

Parameters:
handlerCallback handler function of type WebsLogHandler.
Returns:
The previous callback function.
void logSetPath (char *path)

Set the filename to save logging output.

Parameters:
pathFilename path to use.
char * strim (char *str, char *set, int where)

Trim a string.

Description:
Trim leading and trailing characters off a string.
Parameters:
strString to trim.
setString of characters to remove.
whereFlags to indicate trim from the start, end or both. Use WEBS_TRIM_START, WEBS_TRIM_END, WEBS_TRIM_BOTH.
Returns:
Returns a pointer to the trimmed string. May not equal str.
void traceProc (int level, char *fmt, ...)

Emit a debug trace message to the log.

Description:
This emits a message at the specified level. GoAhead filters logging messages by defining a verbosity level at startup. Level 0 is the least verbose where only the most important messages will be output. Level 9 is the most verbose. Level 2-4 are the most useful for debugging. Debug trace support is enabled by the Bit setting: "tracing: true" which creates the BIT_GOAHEAD_TRACING define in bit.h.
Parameters:
levelInteger verbosity level (0-9).
fmtPrintf style format string.
...Arguments for the format string.
void valueFree (WebsValue *value)

Free any allocated string in a value.

Parameters:
valueValue object.
WebsValue valueInteger (long value)

Create an integer value.

Parameters:
valueInteger long value.
Returns:
Value object containing the integer.
WebsValue valueString (char *value, int flags)

Create an string value.

Parameters:
valueString long value.
flagsSet to VALUE_ALLOCATE to store a copy of the string reference.
Returns:
Value object containing the string.
WebsValue valueSymbol (void *value)

Create an symbol value containing an object reference.

Parameters:
valueValue reference.
Returns:
Value object containing the symbol reference.
void websSetBackgroundWriter (Webs *wp, WebsWriteProc proc)

Define a background write I/O event callback.

Parameters:
wpWebs request object.
procWrite callback.

Typedefs

typedef int WebsHash.

Hash table ID returned by hashCreate.

typedef void(* WebsLogHandler)(int level, char *msg).

Callback for emitting trace log output.

Parameters:
levelInteger between 0 and 9. Zero is the lowest trace level used for the most important messages.
msgMessage to log.
Returns:
Zero if successful.
typedef struct stat WebsStat.

File status structure.

typedef time_t WebsTime.

System native time type.

typedef void(* WebsWriteProc)(struct Webs *wp).

Callback for write I/O events.

typedef void(* WebsAction)(Webs *wp).

Action callback.

Parameters:
wpWebs request object.
See Also:
typedef void(* WebsAskLogin)(Webs *wp).

Callback to prompt the user for their password.

Parameters:
wpWebs request object.
See Also:
typedef void(* WebsHandlerClose)().

GoAhead handler close to release memory prior to shutdown.

Description:
This callback is invoked when GoAhead is shutting down.
See Also:
typedef bool(* WebsHandlerProc)(Webs *wp).

GoAhead handler service callback.

Parameters:
wpWebs request object.
Returns:
True if the handler serviced the request.
See Also:
typedef int(* WebsJstProc)(int jid, Webs *wp, int argc, char **argv).

Javascript native function.

Parameters:
jidJavaScript engine ID.
wpWebs request object.
argcCount of function arguments.
argvArray of function arguments.
defaultValueDefault value to return if the variable is not defined.
Returns:
Return zero if successful, otherwise -1.
See Also:
typedef bool(* WebsParseAuth)(Webs *wp).

Callback to parse authentication details submitted with the web request.

Parameters:
wpWebs request object.
Returns:
True if the details can be parsed.
See Also:
typedef bool(* WebsVerify)(Webs *wp).

Callback to verify the username and password.

Parameters:
wpWebs request object.
Returns:
True if the password is verified.
See Also:
typedef void(* WebsEventProc)(void *data, int id).

Callback function for events.

Parameters:
dataOpaque data argument.
idEvent ID.
See Also:
fmt, hextoi, itosbuf, scaselesscmp, scaselessmatch, sclone, scmp, scopy, sfmt, sfmtv, slen, slower, smatch, sncaselesscmp, sncmp, sncopy, stok, supper, wallocHandle, wallocObject, wfreeHandle
typedef int(* SocketAccept)(int sid, char *ipaddr, int port, int listenSid).

Socket accept callback.

Parameters:
sidSocket ID handle for the newly accepted socket.
ipaddrIP address of the connecting client.
portPort of the connecting client.
listenSidSocket ID for the listening socket.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
typedef void(* SocketHandler)(int sid, int mask, void *data).

Socket I/O callback.

Parameters:
sidSocket ID handle returned from socketConnect or when a new socket is passed to a SocketAccept callback.
maskMask of events of interest. Set to SOCKET_READABLE | SOCKET_WRITABLE | SOCKET_EXCEPTION.
dataData argument to pass to the callback function.
See Also:
socketAddress, socketAddressIsV6, socketAlloc, socketClose, socketCloseConnection, socketCreateHandler, socketEof, socketFree, socketGetBlock, socketGetError, socketGetHandle, socketGetPort, socketInfo, socketIsV6, socketListen, socketOpen, socketParseAddress, socketProcess, socketPtr, socketRead, socketRegisterInterest, socketReservice, socketSelect, socketSetBlock, socketWaitForEvent, socketWrite
WebsError

Error code list.

Fields:
intcode HTTP error code.
char *msg HTTP error message.
WebsFileInfo

File information structure.

Fields:
intisDir Set if directory.
WebsTimemtime Modified time.
ulongsize File length.
WebsHandler

GoAhead handler object.

Fields:
WebsHandlerCloseclose Handler close callback.
intflags Handler control flags.
char *name Handler name.
WebsHandlerProcservice Handler service callback.
WebsMime

Mime type list.

Fields:
char *ext File extension.
char *type Mime type.
WebsRole

Role definition structure.

Fields:
WebsHashabilities Resolved role abilities.
WebsRomIndex

Compiled Rom Page Index.

Fields:
uchar *page Web page data.
char *path Web page URL path.
Offsetpos Current read position.
intsize Size of web page in bytes.
WebsUser

User definition structure.

Fields:
WebsHashabilities Resolved user abilities.
char *name User name.
char *password User password (encrypted).
char *roles User roles.
WebsValue

Value union to store primitive value types.

Fields:

© Embedthis Software LLC, 2003-2013. All rights reserved. Embedthis and Embedthis GoAhead are trademarks of Embedthis Software LLC.