4181 lines
140 KiB
C
4181 lines
140 KiB
C
/*
|
|
goahead.h -- GoAhead Web Server Header
|
|
|
|
Copyright (c) All Rights Reserved. See details at the end of the file.
|
|
*/
|
|
|
|
#ifndef _h_GOAHEAD
|
|
#define _h_GOAHEAD 1
|
|
|
|
/************************************ Overrides *******************************/
|
|
/*
|
|
Override osdep defaults
|
|
*/
|
|
#define ME_MAX_IP 64 /**< Maximum IP address size */
|
|
|
|
/************************************ Includes ********************************/
|
|
|
|
#include "me.h"
|
|
#include "osdep.h"
|
|
|
|
/************************************ Defaults ********************************/
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#if (ME_COM_MBEDTLS + ME_COM_MATRIXSSL + ME_COM_NANOSSL + ME_COM_OPENSSL) > 1
|
|
#error "Cannot have more than one SSL provider configured"
|
|
#endif
|
|
|
|
#ifndef ME_GOAHEAD_LOGGING
|
|
#define ME_GOAHEAD_LOGGING 1 /**< Default for logging is "on" */
|
|
#endif
|
|
#ifndef ME_GOAHEAD_TRACING
|
|
#define ME_GOAHEAD_TRACING 1 /**< Default for tracing "on" */
|
|
#endif
|
|
#ifndef ME_GOAHEAD_DEBUG
|
|
#if ME_DEBUG
|
|
#define ME_GOAHEAD_DEBUG 1 /**< Debug logging on in debug builds by default */
|
|
#else
|
|
#define ME_GOAHEAD_DEBUG 0
|
|
#endif
|
|
#endif
|
|
#if ECOS
|
|
#if ME_GOAHEAD_CGI
|
|
#error "Ecos does not support CGI. Disable ME_GOAHEAD_CGI"
|
|
#endif
|
|
#endif /* ECOS */
|
|
|
|
#if QNX
|
|
typedef long fd_mask;
|
|
#define NFDBITS (sizeof (fd_mask) * NBBY) /* bits per mask */
|
|
#endif
|
|
|
|
#if MACOSX
|
|
typedef int32_t fd_mask;
|
|
#endif
|
|
#if WINDOWS
|
|
typedef fd_set fd_mask;
|
|
#endif
|
|
|
|
#if !LINUX
|
|
PUBLIC char *basename(char *name);
|
|
#endif
|
|
|
|
#if VXWORKS
|
|
PUBLIC int vxchdir(char *dirname);
|
|
#endif
|
|
|
|
#if DOXYGEN
|
|
typedef int Socket;
|
|
typedef int Socklen;
|
|
typedef int64 Offset;
|
|
#endif
|
|
|
|
/**
|
|
File status structure
|
|
*/
|
|
typedef struct stat WebsStat;
|
|
|
|
/*
|
|
Copyright. The software license requires that this not be modified or removed.
|
|
*/
|
|
#define EMBEDTHIS_GOAHEAD_COPYRIGHT \
|
|
"Copyright (c) Embedthis Software Inc., 1993-2014. All Rights Reserved." \
|
|
"Copyright (c) GoAhead Software Inc., 2003. All Rights Reserved."
|
|
|
|
/************************************* Main ***********************************/
|
|
|
|
#define ME_MAX_ARGC 32
|
|
#if VXWORKS
|
|
#define MAIN(name, _argc, _argv, _envp) \
|
|
static int innerMain(int argc, char **argv, char **envp); \
|
|
int name(char *arg0, ...) { \
|
|
va_list args; \
|
|
char *argp, *largv[ME_MAX_ARGC]; \
|
|
int largc = 0; \
|
|
va_start(args, arg0); \
|
|
largv[largc++] = #name; \
|
|
if (arg0) { \
|
|
largv[largc++] = arg0; \
|
|
} \
|
|
for (argp = va_arg(args, char*); argp && largc < ME_MAX_ARGC; argp = va_arg(args, char*)) { \
|
|
largv[largc++] = argp; \
|
|
} \
|
|
return innerMain(largc, largv, NULL); \
|
|
} \
|
|
static int innerMain(_argc, _argv, _envp)
|
|
#elif ME_WIN_LIKE
|
|
#define MAIN(name, _argc, _argv, _envp) \
|
|
APIENTRY WinMain(HINSTANCE inst, HINSTANCE junk, char *command, int junk2) { \
|
|
extern int main(); \
|
|
char *largv[ME_MAX_ARGC]; \
|
|
int largc; \
|
|
largc = websParseArgs(command, &largv[1], ME_MAX_ARGC - 1); \
|
|
largv[0] = #name; \
|
|
main(largc, largv, NULL); \
|
|
} \
|
|
int main(_argc, _argv, _envp)
|
|
#else
|
|
#define MAIN(name, _argc, _argv, _envp) int main(_argc, _argv, _envp)
|
|
#endif
|
|
|
|
PUBLIC int websParseArgs(char *args, char **argv, int maxArgc);
|
|
|
|
#if WINDOWS
|
|
PUBLIC void websSetInst(HINSTANCE inst);
|
|
PUBLIC HINSTANCE websGetInst();
|
|
#endif
|
|
|
|
/************************************ Tunables ********************************/
|
|
|
|
#define WEBS_MAX_LISTEN 8 /**< Maximum number of listen endpoints */
|
|
#define WEBS_SMALL_HASH 31 /**< General small hash size */
|
|
#define WEBS_MAX_PASSWORD 32 /**< Default maximum password */
|
|
|
|
/************************************* Error **********************************/
|
|
#if ME_GOAHEAD_LOGGING
|
|
|
|
#define WEBS_L __FILE__, __LINE__
|
|
#define WEBS_ARGS_DEC char *file, int line
|
|
#define WEBS_ARGS file, line
|
|
|
|
PUBLIC_DATA int logLevel;
|
|
|
|
/**
|
|
Standard logging trace levels are 0 to 9 with 0 being the most verbose. These are ored with the error source
|
|
and type flags. The WEBS_LOG_MASK is used to extract the trace level from a flags word. We expect most apps
|
|
to run with level 2 trace enabled.
|
|
*/
|
|
#define WEBS_ERROR 1 /**< Hard error trace level */
|
|
#define WEBS_WARN 2 /**< Soft warning trace level */
|
|
#define WEBS_CONFIG 2 /**< Configuration settings trace level. */
|
|
#define WEBS_VERBOSE 9 /**< Highest level of trace */
|
|
#define WEBS_LEVEL_MASK 0xF /**< Level mask */
|
|
|
|
/*
|
|
Log message flags
|
|
*/
|
|
#define WEBS_ASSERT_MSG 0x10 /**< Originated from assert */
|
|
#define WEBS_ERROR_MSG 0x20 /**< Originated from error */
|
|
#define WEBS_LOG_MSG 0x100 /**< Originated from logmsg */
|
|
#define WEBS_RAW_MSG 0x200 /**< Raw message output */
|
|
#define WEBS_TRACE_MSG 0x400 /**< Originated from trace */
|
|
|
|
|
|
#if ME_GOAHEAD_TRACING && ME_GOAHEAD_LOGGING
|
|
#if ME_COMPILER_HAS_MACRO_VARARGS
|
|
#define trace(l, ...) if (((l) & WEBS_LEVEL_MASK) <= websGetLogLevel()) { traceProc(l, __VA_ARGS__); } else {}
|
|
#else
|
|
inline void trace(int level, cchar *fmt, ...) {
|
|
WebsLogHandler logHandler = logGetHandler();
|
|
if ((level & WEBS_LEVEL_MASK) <= logLevel && logHandler) {
|
|
va_list args; va_start(args, fmt);
|
|
char *message = sfmtv((char*) fmt, args);
|
|
logHandler(level | WEBS_TRACE_MSG, message);
|
|
wfree(message);
|
|
va_end(args);
|
|
}
|
|
}
|
|
#endif
|
|
#else
|
|
#define trace(l, ...) if (1) ; else {}
|
|
#endif
|
|
|
|
#if ME_GOAHEAD_LOGGING
|
|
#if ME_COMPILER_HAS_MACRO_VARARGS
|
|
#define logmsg(l, ...) if ((l) <= logLevel) { logmsgProc(l, __VA_ARGS__); } else {}
|
|
#else
|
|
inline void logmsg(int level, cchar *fmt, ...) {
|
|
WebsLogHandler logHandler = logGetHandler();
|
|
if ((level & WEBS_LEVEL_MASK) <= logLevel && logHandler) {
|
|
va_list args; va_start(args, fmt);
|
|
char *message = sfmtv((char*) fmt, args);
|
|
logHandler(level | WEBS_TRACE_MSG, message);
|
|
wfree(message);
|
|
va_end(args);
|
|
}
|
|
}
|
|
#endif
|
|
#else
|
|
#define logmsg(l, ...) if (1) ; else {}
|
|
#endif
|
|
|
|
|
|
#if DOXYGEN
|
|
#undef assert
|
|
/**
|
|
Assure that an assert condition is true
|
|
@param cond Boolean result of a conditional test
|
|
@stability Stable
|
|
*/
|
|
extern void assert(bool cond);
|
|
#elif ME_GOAHEAD_DEBUG
|
|
#define assert(C) if (C) ; else assertError(WEBS_L, "%s", #C)
|
|
PUBLIC void assertError(WEBS_ARGS_DEC, char *fmt, ...);
|
|
#else
|
|
#define assert(C) if (1) ; else {}
|
|
#endif
|
|
|
|
/**
|
|
Callback for emitting trace log output
|
|
@param level Integer between 0 and 9. Zero is the lowest trace level used for the most important messages.
|
|
@param msg Message to log
|
|
@return Zero if successful
|
|
@internal
|
|
*/
|
|
typedef void (*WebsLogHandler)(int level, cchar *msg);
|
|
|
|
/**
|
|
Emit an error message
|
|
@return Zero if successful
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void error(cchar *fmt, ...);
|
|
|
|
/**
|
|
Open the log logging module
|
|
@return Zero if successful
|
|
@internal
|
|
*/
|
|
PUBLIC int logOpen(void);
|
|
|
|
/**
|
|
Close the log logging module
|
|
@internal
|
|
*/
|
|
PUBLIC void logClose(void);
|
|
|
|
/**
|
|
Get the log callback
|
|
@return handler Callback handler function of type WebsLogHandler
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsLogHandler logGetHandler(void);
|
|
|
|
/**
|
|
Set a log callback
|
|
@param handler Callback handler function of type WebsLogHandler
|
|
@return The previous callback function
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsLogHandler logSetHandler(WebsLogHandler handler);
|
|
|
|
/**
|
|
Get the current trace log level
|
|
@return Number between 0 and 9
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websGetLogLevel(void);
|
|
|
|
/**
|
|
Set the current trace log level
|
|
@return Number between 0 and 9
|
|
@ingroup Webs
|
|
@stability Prototype
|
|
*/
|
|
void websSetLogLevel(int level);
|
|
|
|
/**
|
|
Set the filename to save logging output
|
|
@param path Filename path to use
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void logSetPath(cchar *path);
|
|
|
|
/**
|
|
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 MakeMe setting: "logging: true" which creates the ME_GOAHEAD_LOGGING define in me.h
|
|
most verbose. Level 2-4 are the most useful for debugging.
|
|
@param level Integer verbosity level (0-9).
|
|
@param fmt Printf style format string
|
|
@param ... Arguments for the format string
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void logmsgProc(int level, cchar *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 MakeMe setting: "tracing: true" which creates the ME_GOAHEAD_TRACING define in
|
|
me.h.
|
|
@param level Integer verbosity level (0-9).
|
|
@param fmt Printf style format string
|
|
@param ... Arguments for the format string
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void traceProc(int level, cchar *fmt, ...);
|
|
|
|
#else /*! ME_GOAHEAD_LOGGING */
|
|
#define assert(C) if (1) ; else {}
|
|
#define error(l, ...) if (1) ; else {}
|
|
#define trace(l, ...) if (1) ; else {}
|
|
#define logOpen() if (1) ; else {}
|
|
#define logClose() if (1) ; else {}
|
|
#define websGetLogLevel() 0
|
|
#define logmsg(l, ...) if (1) ; else {}
|
|
#define logSetPath(p) if (1) ; else {}
|
|
#endif
|
|
|
|
/*********************************** HTTP Codes *******************************/
|
|
/*
|
|
Standard HTTP/1.1 status codes
|
|
*/
|
|
#define HTTP_CODE_CONTINUE 100 /**< Continue with request, only partial content transmitted */
|
|
#define HTTP_CODE_OK 200 /**< The request completed successfully */
|
|
#define HTTP_CODE_CREATED 201 /**< The request has completed and a new resource was created */
|
|
#define HTTP_CODE_ACCEPTED 202 /**< The request has been accepted and processing is continuing */
|
|
#define HTTP_CODE_NOT_AUTHORITATIVE 203 /**< The request has completed but content may be from another source */
|
|
#define HTTP_CODE_NO_CONTENT 204 /**< The request has completed and there is no response to send */
|
|
#define HTTP_CODE_RESET 205 /**< The request has completed with no content. Client must reset view */
|
|
#define HTTP_CODE_PARTIAL 206 /**< The request has completed and is returning partial content */
|
|
#define HTTP_CODE_MOVED_PERMANENTLY 301 /**< The requested URI has moved permanently to a new location */
|
|
#define HTTP_CODE_MOVED_TEMPORARILY 302 /**< The URI has moved temporarily to a new location */
|
|
#define HTTP_CODE_SEE_OTHER 303 /**< The requested URI can be found at another URI location */
|
|
#define HTTP_CODE_NOT_MODIFIED 304 /**< The requested resource has changed since the last request */
|
|
#define HTTP_CODE_USE_PROXY 305 /**< The requested resource must be accessed via the location proxy */
|
|
#define HTTP_CODE_TEMPORARY_REDIRECT 307 /**< The request should be repeated at another URI location */
|
|
#define HTTP_CODE_BAD_REQUEST 400 /**< The request is malformed */
|
|
#define HTTP_CODE_UNAUTHORIZED 401 /**< Authentication for the request has failed */
|
|
#define HTTP_CODE_PAYMENT_REQUIRED 402 /**< Reserved for future use */
|
|
#define HTTP_CODE_FORBIDDEN 403 /**< The request was legal, but the server refuses to process */
|
|
#define HTTP_CODE_NOT_FOUND 404 /**< The requested resource was not found */
|
|
#define HTTP_CODE_BAD_METHOD 405 /**< The request HTTP method was not supported by the resource */
|
|
#define HTTP_CODE_NOT_ACCEPTABLE 406 /**< The requested resource cannot generate the required content */
|
|
#define HTTP_CODE_REQUEST_TIMEOUT 408 /**< The server timed out waiting for the request to complete */
|
|
#define HTTP_CODE_CONFLICT 409 /**< The request had a conflict in the request headers and URI */
|
|
#define HTTP_CODE_GONE 410 /**< The requested resource is no longer available*/
|
|
#define HTTP_CODE_LENGTH_REQUIRED 411 /**< The request did not specify a required content length*/
|
|
#define HTTP_CODE_PRECOND_FAILED 412 /**< The server cannot satisfy one of the request preconditions */
|
|
#define HTTP_CODE_REQUEST_TOO_LARGE 413 /**< The request is too large for the server to process */
|
|
#define HTTP_CODE_REQUEST_URL_TOO_LARGE 414 /**< The request URI is too long for the server to process */
|
|
#define HTTP_CODE_UNSUPPORTED_MEDIA_TYPE 415 /**< The request media type is not supported by the server or resource */
|
|
#define HTTP_CODE_RANGE_NOT_SATISFIABLE 416 /**< The request content range does not exist for the resource */
|
|
#define HTTP_CODE_EXPECTATION_FAILED 417 /**< The server cannot satisfy the Expect header requirements */
|
|
#define HTTP_CODE_NO_RESPONSE 444 /**< The connection was closed with no response to the client */
|
|
#define HTTP_CODE_INTERNAL_SERVER_ERROR 500 /**< Server processing or configuration error. No response generated */
|
|
#define HTTP_CODE_NOT_IMPLEMENTED 501 /**< The server does not recognize the request or method */
|
|
#define HTTP_CODE_BAD_GATEWAY 502 /**< The server cannot act as a gateway for the given request */
|
|
#define HTTP_CODE_SERVICE_UNAVAILABLE 503 /**< The server is currently unavailable or overloaded */
|
|
#define HTTP_CODE_GATEWAY_TIMEOUT 504 /**< The server gateway timed out waiting for the upstream server */
|
|
#define HTTP_CODE_BAD_VERSION 505 /**< The server does not support the HTTP protocol version */
|
|
#define HTTP_CODE_INSUFFICIENT_STORAGE 507 /**< The server has insufficient storage to complete the request */
|
|
|
|
/*
|
|
Proprietary HTTP status codes
|
|
*/
|
|
#define HTTP_CODE_START_LOCAL_ERRORS 550
|
|
#define HTTP_CODE_COMMS_ERROR 550 /**< The server had a communications error responding to the client */
|
|
|
|
/************************************* WebsValue ******************************/
|
|
|
|
#ifdef WITH_QT
|
|
/*
|
|
QT creates a global "hex" -- Ugh!
|
|
*/
|
|
#define hex hexvalue
|
|
#endif
|
|
|
|
/**
|
|
Value types.
|
|
*/
|
|
typedef enum WebsType {
|
|
undefined = 0,
|
|
byteint = 1,
|
|
shortint = 2,
|
|
integer = 3,
|
|
hex = 4,
|
|
percent = 5,
|
|
octal = 6,
|
|
big = 7,
|
|
flag = 8,
|
|
floating = 9,
|
|
string = 10,
|
|
bytes = 11,
|
|
symbol = 12,
|
|
errmsg = 13
|
|
} WebsType;
|
|
|
|
/**
|
|
System native time type. This is the time in seconds.
|
|
This may be 32 or 64 bits and may be signed or unsigned on some systems.
|
|
*/
|
|
typedef time_t WebsTime;
|
|
|
|
/**
|
|
Value union to store primitive value types
|
|
*/
|
|
typedef struct WebsValue {
|
|
union {
|
|
char flag;
|
|
char byteint;
|
|
short shortint;
|
|
char percent;
|
|
long integer;
|
|
long hex;
|
|
long octal;
|
|
long big[2];
|
|
#if ME_FLOAT
|
|
double floating;
|
|
#endif
|
|
char *string;
|
|
char *bytes;
|
|
char *errmsg;
|
|
void *symbol;
|
|
} value;
|
|
WebsType type;
|
|
uint valid : 8;
|
|
uint allocated : 8; /* String was allocated */
|
|
} WebsValue;
|
|
|
|
/**
|
|
The value is a numeric type
|
|
*/
|
|
#define value_numeric(t) (t >= byteint && t <= big)
|
|
|
|
/**
|
|
The value is a string type
|
|
*/
|
|
#define value_str(t) (t >= string && t <= bytes)
|
|
|
|
/**
|
|
The value is valid supported type
|
|
*/
|
|
#define value_ok(t) (t > undefined && t <= symbol)
|
|
|
|
/**
|
|
Allocate strings using malloc
|
|
*/
|
|
#define VALUE_ALLOCATE 0x1
|
|
|
|
/**
|
|
Create an integer value
|
|
@param value Integer long value
|
|
@return Value object containing the integer
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsValue valueInteger(long value);
|
|
|
|
/**
|
|
Create an string value
|
|
@param value String long value
|
|
@param flags Set to VALUE_ALLOCATE to store a copy of the string reference
|
|
@return Value object containing the string
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsValue valueString(cchar *value, int flags);
|
|
|
|
/**
|
|
Create an symbol value containing an object reference
|
|
@param value Value reference
|
|
@return Value object containing the symbol reference
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsValue valueSymbol(void *value);
|
|
|
|
/**
|
|
Free any allocated string in a value
|
|
@param value Value object
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void valueFree(WebsValue *value);
|
|
|
|
/************************************* Ringq **********************************/
|
|
/**
|
|
A WebsBuf (ring queue) allows maximum utilization of memory for data storage and is
|
|
ideal for input/output buffering. This module provides a highly efficient
|
|
implementation and a vehicle for dynamic strings.
|
|
\n\n
|
|
WARNING: This is a public implementation and callers have full access to
|
|
the queue structure and pointers. Change this module very carefully.
|
|
\n\n
|
|
This module follows the open/close model.
|
|
\n\n
|
|
Operation of a WebsBuf where bp is a pointer to a WebsBuf :
|
|
|
|
bp->buflen contains the size of the buffer.
|
|
bp->buf will point to the start of the buffer.
|
|
bp->servp will point to the first (un-consumed) data byte.
|
|
bp->endp will point to the next free location to which new data is added
|
|
bp->endbuf will point to one past the end of the buffer.
|
|
\n\n
|
|
Eg. If the WebsBuf contains the data "abcdef", it might look like :
|
|
\n\n
|
|
+-------------------------------------------------------------------+
|
|
| | | | | | | | a | b | c | d | e | f | | | | |
|
|
+-------------------------------------------------------------------+
|
|
^ ^ ^ ^
|
|
| | | |
|
|
bp->buf bp->servp bp->endp bp->enduf
|
|
\n\n
|
|
The queue is empty when servp == endp. This means that the queue will hold
|
|
at most bp->buflen -1 bytes. It is the fillers responsibility to ensure
|
|
the WebsBuf is never filled such that servp == endp.
|
|
\n\n
|
|
It is the fillers responsibility to "wrap" the endp back to point to
|
|
bp->buf when the pointer steps past the end. Correspondingly it is the
|
|
consumers responsibility to "wrap" the servp when it steps to bp->endbuf.
|
|
The bufPutc and bufGetc routines will do this automatically.
|
|
@defgroup WebsBuf WebsBuf
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsBuf {
|
|
char *buf; /**< Holding buffer for data */
|
|
char *servp; /**< Pointer to start of data */
|
|
char *endp; /**< Pointer to end of data */
|
|
char *endbuf; /**< Pointer to end of buffer */
|
|
ssize buflen; /**< Length of ring queue */
|
|
ssize maxsize; /**< Maximum size */
|
|
int increment; /**< Growth increment */
|
|
} WebsBuf;
|
|
|
|
/**
|
|
Add a trailing null to the buffer. The end pointer is not changed.
|
|
@param bp Buffer reference
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void bufAddNull(WebsBuf *bp);
|
|
|
|
/**
|
|
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.
|
|
@param bp Buffer reference
|
|
@param size Size of adjustment. May be positive or negative value.
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void bufAdjustEnd(WebsBuf *bp, ssize size);
|
|
|
|
/**
|
|
Adjust the start (servp) reference
|
|
@param bp Buffer reference
|
|
@param count Number of bytes to adjust
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void bufAdjustStart(WebsBuf *bp, ssize count);
|
|
|
|
/**
|
|
Compact the data in the buffer and move to the start of the buffer
|
|
@param bp Buffer reference
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void bufCompact(WebsBuf *bp);
|
|
|
|
/**
|
|
Create a buffer
|
|
@param bp Buffer reference
|
|
@param increment Incremental size to grow the buffer. This will be increased by a power of two each time
|
|
the buffer grows.
|
|
@param maxsize Maximum size of the buffer
|
|
@return Zero if successful
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int bufCreate(WebsBuf *bp, int increment, int maxsize);
|
|
|
|
/**
|
|
Flush all data in the buffer and reset the pointers.
|
|
@param bp Buffer reference
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void bufFlush(WebsBuf *bp);
|
|
|
|
/**
|
|
Free allocated storage for the buffer
|
|
@param bp Buffer reference
|
|
@return Zero if successful
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void bufFree(WebsBuf *bp);
|
|
|
|
/**
|
|
Copy a block of from the buffer and adjust the servp.
|
|
@param bp Buffer reference
|
|
@param blk Block into which to place the data
|
|
@param len Length of the block
|
|
@return Number of bytes copied.
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize bufGetBlk(WebsBuf *bp, char *blk, ssize len);
|
|
|
|
/**
|
|
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.
|
|
@param bp Buffer reference
|
|
@return Number of bytes available for copying.
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize bufGetBlkMax(WebsBuf *bp);
|
|
|
|
/**
|
|
Get a character from the buffer and increment the servp
|
|
@param bp Buffer reference
|
|
@return The next character or -1 if the buffer is empty
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int bufGetc(WebsBuf *bp);
|
|
|
|
/**
|
|
Grow the buffer by at least the required amount of room
|
|
@param bp Buffer reference
|
|
@param room Available size required after growing the buffer
|
|
@return True if the buffer can be grown to have the required amount of room.
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool bufGrow(WebsBuf *bp, ssize room);
|
|
|
|
/**
|
|
Get the length of available data in the buffer
|
|
@param bp Buffer reference
|
|
@return Size of available data in bytes
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize bufLen(WebsBuf *bp);
|
|
|
|
/**
|
|
Insert a character to the buffer before the servp position and decrement the servp
|
|
@param bp Buffer reference
|
|
@param c Character to insert
|
|
@return Zero if successful
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int bufInsertc(WebsBuf *bp, char c);
|
|
|
|
/**
|
|
Append a character to the buffer at the endp position and increment the endp
|
|
@param bp Buffer reference
|
|
@param c Character to append
|
|
@return Zero if successful
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int bufPutc(WebsBuf *bp, char c);
|
|
/**
|
|
Put a block to the buffer.
|
|
@param bp Buffer reference
|
|
@param blk Block to append to the buffer
|
|
@param len Size of the block
|
|
@return Length of data appended. Should equal len.
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize bufPutBlk(WebsBuf *bp, cchar *blk, ssize len);
|
|
|
|
/**
|
|
Append a formatted string to the buffer at the endp position and increment the endp
|
|
@param bp Buffer reference
|
|
@param fmt Printf style format string
|
|
@param ... Variable arguments for the format string
|
|
@return Count of characters appended. Returns negative if there is an allocation error.
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize bufPut(WebsBuf *bp, cchar *fmt, ...) PRINTF_ATTRIBUTE(2,3);
|
|
|
|
/**
|
|
Append a string to the buffer at the endp position and increment the endp
|
|
@param bp Buffer reference
|
|
@param str String to append
|
|
@return Count of characters appended. Returns negative if there is an allocation error.
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize bufPutStr(WebsBuf *bp, cchar *str);
|
|
|
|
/**
|
|
Reset the buffer pointers to the start of the buffer if empty
|
|
@param bp Buffer reference
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void bufReset(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.
|
|
@param bp Buffer reference
|
|
@return Number of bytes of available space.
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize bufRoom(WebsBuf *bp);
|
|
|
|
/**
|
|
Get a reference to the start of buffer data
|
|
@param bp Buffer reference
|
|
@return A string pointer.
|
|
@ingroup WebsBuf
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *bufStart(WebsBuf *bp);
|
|
|
|
/******************************* Malloc Replacement ***************************/
|
|
#if ME_GOAHEAD_REPLACE_MALLOC
|
|
/**
|
|
GoAhead allocator memory block
|
|
Memory block classes are: 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536.
|
|
@defgroup WebsAlloc WebsAlloc
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsAlloc {
|
|
union {
|
|
void *next; /**< Pointer to next in q */
|
|
int size; /**< Actual requested size */
|
|
} u;
|
|
int flags; /**< Per block allocation flags */
|
|
} WebsAlloc;
|
|
|
|
#define WEBS_DEFAULT_MEM (64 * 1024) /**< Default memory allocation */
|
|
#define WEBS_MAX_CLASS 13 /**< Maximum class number + 1 */
|
|
#define WEBS_SHIFT 4 /**< Convert size to class */
|
|
#define WEBS_ROUND ((1 << (B_SHIFT)) - 1)
|
|
#define WEBS_MALLOCED 0x80000000 /* Block was malloced */
|
|
#define WEBS_FILL_CHAR (0x77) /* Fill byte for buffers */
|
|
#define WEBS_FILL_WORD (0x77777777) /* Fill word for buffers */
|
|
|
|
/*
|
|
Flags. The integrity value is used as an arbitrary value to fill the flags.
|
|
*/
|
|
#define WEBS_USE_MALLOC 0x1 /**< Okay to use malloc if required */
|
|
#define WEBS_USER_BUF 0x2 /* User supplied buffer for mem */
|
|
#define WEBS_INTEGRITY 0x8124000 /* Integrity value */
|
|
#define WEBS_INTEGRITY_MASK 0xFFFF000 /* Integrity mask */
|
|
#endif /* ME_GOAHEAD_REPLACE_MALLOC */
|
|
|
|
/**
|
|
Close the GoAhead memory allocator
|
|
@ingroup WebsAlloc
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void wcloseAlloc(void);
|
|
|
|
/**
|
|
Initialize the walloc module.
|
|
@description The wopenAlloc function should be called the very first thing after the application starts and wclose
|
|
should be called the last thing before exiting. If wopenAlloc is not called, it will be called on the first allocation
|
|
with default values. "buf" points to memory to use of size "bufsize". If buf is NULL, memory is allocated using malloc.
|
|
flags may be set to WEBS_USE_MALLOC if using malloc is okay. This routine will allocate * an initial buffer of size
|
|
bufsize for use by the application.
|
|
@param buf Optional user supplied block of memory to use for allocations
|
|
@param bufsize Size of buf
|
|
@param flags Allocation flags. Set to WEBS_USE_MALLOC to permit the use of malloc() to grow memory.
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsAlloc
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int wopenAlloc(void *buf, int bufsize, int flags);
|
|
|
|
/**
|
|
Allocate a block of the requested size
|
|
@param size Memory size required
|
|
@return A reference to the allocated block
|
|
@ingroup WebsAlloc
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void *walloc(ssize size);
|
|
|
|
/**
|
|
Free an allocated block of memory
|
|
@param blk Reference to the memory block to free.
|
|
@ingroup WebsAlloc
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void wfree(void *blk);
|
|
|
|
/**
|
|
Reallocate a block of memory and grow its size
|
|
@description If the new size is larger than the existing block, a new block will be allocated and the old data
|
|
will be copied to the new block.
|
|
@param blk Original block reference
|
|
@param newsize Size of the new block.
|
|
@return Reference to the new memory block
|
|
@ingroup WebsAlloc
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void *wrealloc(void *blk, ssize newsize);
|
|
|
|
/**
|
|
Duplicate memory
|
|
@param ptr Original block reference
|
|
@param usize Size to allocate
|
|
@return Reference to the new memory block
|
|
@ingroup WebsAlloc
|
|
*/
|
|
PUBLIC void *wdup(cvoid *ptr, size_t usize);
|
|
|
|
typedef void (*WebsMemNotifier)(ssize size);
|
|
|
|
/**
|
|
Define a global memory allocation notifier.
|
|
@description The notifier is called if any memory allocation fails. It is called with the requested allocation size
|
|
as its only parameter.
|
|
@param cback Callback function to invoke for allocation failures.
|
|
@ingroup WebsAlloc
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC void websSetMemNotifier(WebsMemNotifier cback);
|
|
|
|
#ifndef WEBS_SHIFT
|
|
#define WEBS_SHIFT 4
|
|
#endif
|
|
|
|
#if DEPRECATE
|
|
/*
|
|
Deprecated in 4.0.0
|
|
*/
|
|
PUBLIC ssize mtow(wchar *dest, ssize count, char *src, ssize len);
|
|
PUBLIC ssize wtom(char *dest, ssize count, wchar *src, ssize len);
|
|
PUBLIC wchar *amtow(char *src, ssize *len);
|
|
PUBLIC char *awtom(wchar *src, ssize *len);
|
|
#endif
|
|
|
|
/******************************* Hash Table *********************************/
|
|
/**
|
|
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 hashCreate hashFree hashLookup hashEnter hashDelete hashWalk hashFirst hashNext
|
|
@defgroup WebsHash WebsHash
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsKey {
|
|
struct WebsKey *forw; /* Pointer to next hash list */
|
|
WebsValue name; /* Name of symbol */
|
|
WebsValue content; /* Value of symbol */
|
|
int arg; /* Parameter value */
|
|
int bucket; /* Bucket index */
|
|
} WebsKey;
|
|
|
|
/**
|
|
Hash table ID returned by hashCreate
|
|
*/
|
|
typedef int WebsHash; /* Returned by symCreate */
|
|
|
|
/**
|
|
Create a hash table
|
|
@param size Minimum size of the hash index
|
|
@return Hash table ID. Negative if the hash cannot be created.
|
|
@ingroup WebsHash
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsHash hashCreate(int size);
|
|
|
|
/**
|
|
Free a hash table
|
|
@param id Hash table id returned by hashCreate
|
|
@ingroup WebsHash
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void hashFree(WebsHash id);
|
|
|
|
/**
|
|
Lookup a name in the hash table
|
|
@param id Hash table id returned by hashCreate
|
|
@param name Key name to search for
|
|
@return Reference to the WebKey object storing the key and value
|
|
@ingroup WebsHash
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsKey *hashLookup(WebsHash id, cchar *name);
|
|
|
|
/**
|
|
Lookup a name in the hash table and return a symbol reference
|
|
@param sd Hash table id returned by hashCreate
|
|
@param name Key name to search for
|
|
@return Reference to the symbole
|
|
@ingroup WebsHash
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC void *hashLookupSymbol(WebsHash sd, cchar *name);
|
|
|
|
/**
|
|
Enter a new key and value into the hash table
|
|
@param id Hash table id returned by hashCreate
|
|
@param name Key name to create
|
|
@param value Key value to enter
|
|
@param arg Optional extra argument to store with the value
|
|
@return Reference to the WebKey object storing the key and value
|
|
@ingroup WebsHash
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsKey *hashEnter(WebsHash id, cchar *name, WebsValue value, int arg);
|
|
|
|
/**
|
|
Delete a key by name
|
|
@param id Hash table id returned by hashCreate
|
|
@param name Key name to delete
|
|
@return Zero if the delete was successful. Otherwise -1 if the key was not found.
|
|
@ingroup WebsHash
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int hashDelete(WebsHash id, cchar *name);
|
|
|
|
/**
|
|
Start walking the hash keys by returning the first key entry in the hash
|
|
@param id Hash table id returned by hashCreate
|
|
@return Reference to the first WebKey object. Return null if there are no keys in the hash.
|
|
@ingroup WebsHash
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsKey *hashFirst(WebsHash id);
|
|
|
|
/**
|
|
Continue walking the hash keys by returning the next key entry in the hash
|
|
@param id Hash table id returned by hashCreate
|
|
@param last Reference to a WebsKey to hold the current traversal key state.
|
|
@return Reference to the next WebKey object. Returns null if no more keys exist to be traversed.
|
|
@ingroup WebsHash
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsKey *hashNext(WebsHash id, WebsKey *last);
|
|
|
|
/************************************ Socket **********************************/
|
|
/*
|
|
Socket flags
|
|
*/
|
|
#define SOCKET_EOF 0x1 /**< Seen end of file */
|
|
#define SOCKET_CONNECTING 0x2 /**< Connect in progress */
|
|
#define SOCKET_RESERVICE 0x4 /**< Socket needs re-servicing */
|
|
#define SOCKET_ASYNC 0x8 /**< Use async connect */
|
|
#define SOCKET_BLOCK 0x10 /**< Use blocking I/O */
|
|
#define SOCKET_LISTENING 0x20 /**< Socket is server listener */
|
|
#define SOCKET_CLOSING 0x40 /**< Socket is closing */
|
|
#define SOCKET_CONNRESET 0x80 /**< Socket connection was reset */
|
|
#define SOCKET_HANDSHAKING 0x100 /**< Doing SSL handshake */
|
|
#define SOCKET_BUFFERED_READ 0x200 /**< Message pending on this socket */
|
|
#define SOCKET_BUFFERED_WRITE 0x400 /**< Message pending on this socket */
|
|
#define SOCKET_NODELAY 0x800 /**< Disable Nagle algorithm */
|
|
|
|
#define SOCKET_PORT_MAX 0xffff /**< Max Port size */
|
|
|
|
#ifndef ME_MAX_IP
|
|
#define ME_MAX_IP 64 /**< Maximum IP address size */
|
|
#endif
|
|
|
|
/*
|
|
Socket error values
|
|
*/
|
|
#define SOCKET_WOULDBLOCK 1 /**< Socket would block on I/O */
|
|
#define SOCKET_RESET 2 /**< Socket has been reset */
|
|
#define SOCKET_NETDOWN 3 /**< Network is down */
|
|
#define SOCKET_AGAIN 4 /**< Issue the request again */
|
|
#define SOCKET_INTR 5 /**< Call was interrupted */
|
|
#define SOCKET_INVAL 6 /**< Invalid */
|
|
|
|
/*
|
|
Handler event masks
|
|
*/
|
|
#define SOCKET_READABLE 0x2 /**< Make socket readable */
|
|
#define SOCKET_WRITABLE 0x4 /**< Make socket writable */
|
|
#define SOCKET_EXCEPTION 0x8 /**< Interested in exceptions */
|
|
|
|
/**
|
|
Socket I/O callback
|
|
@param sid Socket ID handle returned from socketConnect or when a new socket is passed to a SocketAccept
|
|
callback..
|
|
@param mask Mask of events of interest. Set to SOCKET_READABLE | SOCKET_WRITABLE | SOCKET_EXCEPTION.
|
|
@param data Data argument to pass to the callback function.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
typedef void (*SocketHandler)(int sid, int mask, void *data);
|
|
|
|
/**
|
|
Socket accept callback
|
|
@param sid Socket ID handle for the newly accepted socket
|
|
@param ipaddr IP address of the connecting client.
|
|
@param port Port of the connecting client.
|
|
@param listenSid Socket ID for the listening socket
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
typedef int (*SocketAccept)(int sid, cchar *ipaddr, int port, int listenSid);
|
|
|
|
/**
|
|
Socket control structure
|
|
@see socketAddress socketAddressIsV6 socketClose socketCloseConnection socketCreateHandler
|
|
socketDeletehandler socketReservice socketEof socketGetPort socketInfo socketIsV6
|
|
socketOpen socketListen socketParseAddress socketProcess socketRead socketWrite socketWriteString
|
|
socketSelect socketGetHandle socketSetBlock socketGetBlock socketAlloc socketFree socketGetError
|
|
socketSetError socketPtr socketWaitForEvent socketRegisterInterest
|
|
@defgroup WebsSocket WebsSocket
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsSocket {
|
|
WebsBuf lineBuf; /**< Line ring queue */
|
|
SocketAccept accept; /**< Accept handler */
|
|
SocketHandler handler; /**< User I/O handler */
|
|
char *ip; /**< Server listen address or remote client address */
|
|
void *handler_data; /**< User handler data */
|
|
int handlerMask; /**< Handler events of interest */
|
|
int sid; /**< Index into socket[] */
|
|
int port; /**< Port to listen on */
|
|
int flags; /**< Current state flags */
|
|
Socket sock; /**< Actual socket handle */
|
|
int fileHandle; /**< ID of the file handler */
|
|
int interestEvents; /**< Mask of events to watch for */
|
|
int currentEvents; /**< Mask of ready events (FD_xx) */
|
|
int selectEvents; /**< Events being selected */
|
|
int saveMask; /**< saved Mask for socketFlush */
|
|
int error; /**< Last error */
|
|
int secure; /**< Socket is using SSL */
|
|
int handshakes; /**< Number of renegotiations */
|
|
} WebsSocket;
|
|
|
|
|
|
/**
|
|
Extract the numerical IP address and port for the given socket info
|
|
@param addr Reference to the socket address.
|
|
@param addrlen Length of the socket address
|
|
@param ipbuf Buffer to contain the parsed IP address
|
|
@param ipLen Size of ipbuf
|
|
@param port Reference to an integer to hold the parsed port.
|
|
@return Zero if successful. Otherwise -1 for parse errors.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketAddress(struct sockaddr *addr, int addrlen, char *ipbuf, int ipLen, int *port);
|
|
|
|
/**
|
|
Determine if an IP address is an IPv6 address.
|
|
@param ip String IP address.
|
|
@return True if the address is an IPv6 address.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool socketAddressIsV6(cchar *ip);
|
|
|
|
/**
|
|
Allocate a socket object
|
|
@param host String host IP address.
|
|
@param port Socket port
|
|
@param accept Optional SocketAccept accept callback function
|
|
@param flags Control flags
|
|
@return Socket ID handle to use with other APIs.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketAlloc(cchar *host, int port, SocketAccept accept, int flags);
|
|
|
|
/**
|
|
Close the socket module
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void socketClose(void);
|
|
|
|
/**
|
|
Close a socket connection
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void socketCloseConnection(int sid);
|
|
|
|
/**
|
|
Connect to a server and create a new socket
|
|
@param host Host IP address.
|
|
@param port Port number to connect to
|
|
@param flags Set to SOCKET_BLOCK for blocking I/O. Otherwise non-blocking I/O is used.
|
|
@return True if the address is an IPv6 address.
|
|
@ingroup WebsSocket
|
|
@internal
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketConnect(cchar *host, int port, int flags);
|
|
|
|
/**
|
|
Create a socket handler that will be invoked when I/O events occur.
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@param mask Mask of events of interest. Set to SOCKET_READABLE | SOCKET_WRITABLE | SOCKET_EXCEPTION.
|
|
@param handler Socket handler function.
|
|
@param arg Arbitrary object reference to pass to the SocketHandler callback function.
|
|
@return True if the address is an IPv6 address.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void socketCreateHandler(int sid, int mask, SocketHandler handler, void *arg);
|
|
|
|
/**
|
|
Delete a socket handler created via socketCreateHandler
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void socketDeleteHandler(int sid);
|
|
|
|
/**
|
|
Determine if the socket is at end-of-file for input.
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@return True if the address is at EOF
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool socketEof(int sid);
|
|
|
|
/**
|
|
Free (and close) the socket
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void socketFree(int sid);
|
|
|
|
/**
|
|
Get the current blocking mode
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@return True if the socket is in blocking mode.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketGetBlock(int sid);
|
|
|
|
/**
|
|
Get the error code for the last socket operation on this thread.
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@return Integer error code. See errno or GetLastError() on windows.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketGetError(int sid);
|
|
|
|
/**
|
|
Get the underlying socket operating system socket/file handle
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@return The socket handle
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC Socket socketGetHandle(int sid);
|
|
|
|
/**
|
|
Get the list of sockets
|
|
@return The socket list pointer
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsSocket **socketGetList(void);
|
|
|
|
/**
|
|
Get the IP port associated with this socket.
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@return The TCP/IP port for this socket
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketGetPort(int sid);
|
|
|
|
/**
|
|
Indicate if the system has a dual IPv4 and IPv6 stack
|
|
@return True if IPv4 and IPv6 are supported on a single stack
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool socketHasDualNetworkStack(void);
|
|
|
|
/**
|
|
Indicate if the system has IPv6 support
|
|
@return True if IPv6 is supported on this system
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool socketHasIPv6(void);
|
|
|
|
/**
|
|
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
|
|
@param sp Socket object returned from #socketPtr
|
|
@param len Length of buffered data in bytes
|
|
@param dir Buffer direction. Set to MPR_READABLE for buffered read data and MPR_WRITABLE for buffered write data.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void socketHiddenData(WebsSocket *sp, ssize len, int dir);
|
|
|
|
/**
|
|
Get a socket address structure for the specified IP:Port
|
|
@description This returns address details in *family, *protocol, *addr, and *addrlen.
|
|
@param ip IP address to parse
|
|
@param port TCP/IP port number
|
|
@param family Reference to an integer to hold the address family
|
|
@param protocol Reference to an integer to hold the address protocol
|
|
@param addr Reference to an integer to hold the address structure
|
|
@param addrlen Reference to an integer to hold the address structure length
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketInfo(cchar *ip, int port, int *family, int *protocol, struct sockaddr_storage *addr, Socklen *addrlen);
|
|
|
|
/**
|
|
Determine if a socket is bound to an IPv6 address.
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@return True if the socket is using IPv6.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool socketIsV6(int sid);
|
|
|
|
/**
|
|
Open a listening socket
|
|
@param host Host IP address on which to listen. Set to NULL to listen on all interfaces.
|
|
@param port TCP/IP port on which to listen
|
|
@param accept SocketAccept callback function to invoke to receive incoming connections.
|
|
@param flags Reserved
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketListen(cchar *host, int port, SocketAccept accept, int flags);
|
|
|
|
/**
|
|
Open the socket module
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketOpen(void);
|
|
|
|
/**
|
|
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 ":*" 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
|
|
[aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh:iiii]:port
|
|
If supplied an IPv6 address, the backets are stripped in the returned IP address.
|
|
@param ipAddrPort IP address which may contain an optional ":port" component.
|
|
@param pip Returns a reference to an allocated string containing the IP address portion. Caller must free.
|
|
@param pport Reference to an integer to hold the port component.
|
|
@param secure Reference to an integer to be set to true if the address is using SSL/TLS.
|
|
@param defaultPort Default port number to use if no port specifier is included in ipAddrPort.
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketParseAddress(cchar *ipAddrPort, char **pip, int *pport, int *secure, int defaultPort);
|
|
|
|
/**
|
|
Process pending socket I/O events.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
@internal
|
|
*/
|
|
PUBLIC void socketProcess(void);
|
|
|
|
/**
|
|
Read data from a socket
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@param buf Buffer to hold read data
|
|
@param len Size of the buffer
|
|
@return Count of bytes actually read. Returns -1 for errors and EOF. Distinguish between errors and EOF
|
|
via socketEof().
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize socketRead(int sid, void *buf, ssize len);
|
|
|
|
/**
|
|
Register interest in socket I/OEvents
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@param mask Mask of events of interest. Set to SOCKET_READABLE | SOCKET_WRITABLE | SOCKET_EXCEPTION.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void socketRegisterInterest(int sid, int mask);
|
|
|
|
/**
|
|
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.
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void socketReservice(int sid);
|
|
|
|
/**
|
|
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.
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@param timeout Timeout in milliseconds.
|
|
@return Number of I/O events.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketSelect(int sid, int timeout);
|
|
|
|
/**
|
|
Set the socket blocking mode
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@param on Set to 1 to enable blocking
|
|
@return The previous blocking mode
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketSetBlock(int sid, int on);
|
|
|
|
/**
|
|
Set the error code for the last socket operation on this thread.
|
|
@param error Integer error code. See errno or GetLastError() on windows.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void socketSetError(int error);
|
|
|
|
/**
|
|
Set the socket delay mode
|
|
@description This is used to enable or disable the TCP Nagle algorithm
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@param on Set to 1 to disable the Nagle algorithm
|
|
@return The previous blocking mode
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketSetNoDelay(int sid, bool on);
|
|
|
|
/**
|
|
Wait for a socket I/O event
|
|
@param sp Socket object
|
|
@param mask Mask of events of interest. Set to SOCKET_READABLE | SOCKET_WRITABLE | SOCKET_EXCEPTION.
|
|
@return Zero if successful in waiting for the desired event, otherwise return -1.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int socketWaitForEvent(WebsSocket *sp, int mask);
|
|
|
|
/**
|
|
Write data to the socket
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@param buf Buffer containing data to write
|
|
@param len Size of buf
|
|
@return Count of bytes written. May be less than len if the socket is in non-blocking mode.
|
|
Returns -1 for errors and if the socket cannot absorb any more data. If the transport is saturated,
|
|
will return a negative error and errno will be set to EAGAIN or EWOULDBLOCK.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize socketWrite(int sid, void *buf, ssize len);
|
|
|
|
/**
|
|
Return the socket object for the socket ID.
|
|
@param sid Socket ID handle returned from socketConnect or socketAccept.
|
|
@return Corresponding socket object.
|
|
@ingroup WebsSocket
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsSocket *socketPtr(int sid);
|
|
|
|
/*********************************** Runtime **********************************/
|
|
|
|
/**
|
|
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.
|
|
@defgroup WebsRuntime WebsRuntime
|
|
@see fmt wallocHandle wallocObject wfreeHandle hextoi itosbuf scaselesscmp scaselessmatch
|
|
sclone scmp scopy sfmt sfmtv slen slower smatch sstarts sncaselesscmp sncmp sncopy stok strim supper
|
|
@stability Stable
|
|
*/
|
|
|
|
/**
|
|
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.
|
|
@param buf Pointer to the buffer.
|
|
@param maxSize Size of the buffer.
|
|
@param format Printf style format string
|
|
@param ... Variable arguments to format
|
|
@return Returns the buffer.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *fmt(char *buf, ssize maxSize, cchar *format, ...);
|
|
|
|
/**
|
|
Allocate a handle from a map
|
|
@param map Reference to a location holding the map reference. On the first call, the map is allocated.
|
|
@return Integer handle index. Otherwise return -1 on allocation errors.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int wallocHandle(void *map);
|
|
|
|
/**
|
|
Allocate an object in a halloc map
|
|
@param map Reference to a location holding the map reference. On the first call, the map is allocated.
|
|
@param max Reference to an integer that holds the maximum handle in the map.
|
|
@param size Size of the object to allocate.
|
|
@return Integer handle index. Otherwise return -1 on allocation errors.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int wallocObject(void *map, int *max, int size);
|
|
|
|
/**
|
|
Free a handle in the map
|
|
@param map Reference to a location to hold the map reference.
|
|
@param handle Handle to free in the map.
|
|
@return Integer handle index. Otherwise return -1 on allocation errors.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int wfreeHandle(void *map, int handle);
|
|
|
|
/**
|
|
Convert a hex string to an integer
|
|
@description This call converts the supplied string to an integer using base 16.
|
|
@param str Pointer to the string to parse.
|
|
@return Returns the integer equivalent value of the string.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC uint hextoi(cchar *str);
|
|
|
|
/**
|
|
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.
|
|
@param buf Pointer to the buffer that will hold the string.
|
|
@param size Size of the buffer.
|
|
@param value Integer value to convert
|
|
@param radix The base radix to use when encoding the number
|
|
@return Returns a reference to the string.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *itosbuf(char *buf, ssize size, int64 value, int radix);
|
|
|
|
/**
|
|
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.
|
|
@param s1 First string to compare.
|
|
@param s2 Second string to compare.
|
|
@return Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence
|
|
or > 0 if it sorts higher.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int scaselesscmp(cchar *s1, cchar *s2);
|
|
|
|
/**
|
|
Compare strings ignoring case. This is similar to scaselesscmp but it returns a boolean.
|
|
@description Compare two strings ignoring case differences.
|
|
@param s1 First string to compare.
|
|
@param s2 Second string to compare.
|
|
@return Returns true if the strings are equivalent, otherwise false.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool scaselessmatch(cchar *s1, cchar *s2);
|
|
|
|
/**
|
|
Clone a string
|
|
@description Copy a string into a newly allocated block.
|
|
@param str Pointer to the block to duplicate.
|
|
@return Returns a newly allocated string.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *sclone(cchar *str);
|
|
|
|
/**
|
|
Clone a substring.
|
|
@description Copy a substring into a newly allocated block.
|
|
@param str Pointer to the block to duplicate.
|
|
@param len Number of bytes to copy. The actual length copied is the minimum of the given length and the length of
|
|
the supplied string. The result is null terminated.
|
|
@return Returns a newly allocated string.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *snclone(cchar *str, ssize len);
|
|
|
|
/**
|
|
Compare strings.
|
|
@description Compare two strings. This is a safe replacement for strcmp. It can handle null args.
|
|
@param s1 First string to compare.
|
|
@param s2 Second string to compare.
|
|
@return 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.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int scmp(cchar *s1, cchar *s2);
|
|
|
|
/**
|
|
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.
|
|
@param dest Pointer to a pointer that will hold the address of the allocated block.
|
|
@param destMax Maximum size of the target string in characters.
|
|
@param src String to copy
|
|
@return Returns the number of characters in the target string.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize scopy(char *dest, ssize destMax, cchar *src);
|
|
|
|
/*
|
|
String trim flags
|
|
*/
|
|
#define WEBS_TRIM_START 0x1 /**< Flag for strim to trim from the start of the string */
|
|
#define WEBS_TRIM_END 0x2 /**< Flag for strim to trim from the end of the string */
|
|
#define WEBS_TRIM_BOTH 0x3 /**< Flag for strim to trim from both the start and the end of the string */
|
|
|
|
/**
|
|
Format a string. This is a secure version 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.
|
|
@param format Printf style format string
|
|
@param ... Variable arguments for the format string
|
|
@return Returns a newly allocated string
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *sfmt(cchar *format, ...);
|
|
|
|
/**
|
|
Format a string with varargs. This is a secure version 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.
|
|
@param format Printf style format string
|
|
@param args Varargs argument obtained from va_start.
|
|
@return Returns a newly allocated string
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *sfmtv(cchar *format, va_list args);
|
|
|
|
/**
|
|
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.
|
|
@param str String to measure.
|
|
@return Returns the length of the string
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize slen(cchar *str);
|
|
|
|
/**
|
|
Convert a string to lower case.
|
|
@description Convert a string to its lower case equivalent.
|
|
@param str String to convert. This string is modified.
|
|
@return Reference to the supplied str. Caller must not free.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *slower(char *str);
|
|
|
|
/**
|
|
Compare strings
|
|
@description Compare two strings. This is similar to #scmp but it returns a boolean.
|
|
@param s1 First string to compare.
|
|
@param s2 Second string to compare.
|
|
@return Returns true if the strings are equivalent, otherwise false.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool smatch(cchar *s1, cchar *s2);
|
|
|
|
/**
|
|
Compare strings ignoring case.
|
|
@description Compare two strings ignoring case differences for a given string length. This call operates
|
|
similarly to strncasecmp.
|
|
@param s1 First string to compare.
|
|
@param s2 Second string to compare.
|
|
@param len Length of characters to compare.
|
|
@return Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence
|
|
or > 0 if it sorts higher.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int sncaselesscmp(cchar *s1, cchar *s2, ssize len);
|
|
|
|
/**
|
|
Compare strings.
|
|
@description Compare two strings for a given string length. This call operates similarly to strncmp.
|
|
@param s1 First string to compare.
|
|
@param s2 Second string to compare.
|
|
@param len Length of characters to compare.
|
|
@return Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence
|
|
or > 0 if it sorts higher.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int sncmp(cchar *s1, cchar *s2, ssize len);
|
|
|
|
/**
|
|
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.
|
|
@param dest Pointer to a pointer that will hold the address of the allocated block.
|
|
@param destMax Maximum size of the target string in characters.
|
|
@param src String to copy
|
|
@param count Maximum count of characters to copy
|
|
@return Returns a reference to the destination if successful or NULL if the string won't fit.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize sncopy(char *dest, ssize destMax, cchar *src, ssize count);
|
|
|
|
/*
|
|
Test if a string is a radix 10 number.
|
|
@description The supported format is: [(+|-)][DIGITS]
|
|
@return true if all characters are digits or '+' or '-'
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool snumber(cchar *s);
|
|
|
|
/**
|
|
Split a string at a delimiter
|
|
@description Split a string and return parts. The string is modified.
|
|
This routiner never returns null. If there are leading delimiters, the empty string will be returned
|
|
and *last will be set to the portion after the delimiters.
|
|
If str is null, an empty string will be returned.
|
|
If there are no characters after the delimiter, then *last will be set to the empty string.
|
|
@param str String to tokenize.
|
|
@param delim Set of characters that are used as token separators.
|
|
@param last Reference to the portion after the delimiters. Will return an empty string if is not trailing portion.
|
|
@return Returns a pointer to the first part before the delimiters. If the string begins with delimiters, the empty
|
|
string will be returned.
|
|
@ingroup WebsRuntime
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC char *ssplit(char *str, cchar *delim, char **last);
|
|
|
|
/**
|
|
Test if the string starts with a given pattern.
|
|
@param str String to examine
|
|
@param prefix Pattern to search for
|
|
@return Returns TRUE if the pattern was found. Otherwise returns zero.
|
|
@ingroup MprString
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool sstarts(cchar *str, cchar *prefix);
|
|
|
|
/**
|
|
Tokenize a string
|
|
@description Split a string into tokens.
|
|
@param str String to tokenize.
|
|
@param delim String of characters to use as token separators.
|
|
@param last Last token pointer.
|
|
@return Returns a pointer to the next token.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *stok(char *str, cchar *delim, char **last);
|
|
|
|
/**
|
|
Trim a string.
|
|
@description Trim leading and trailing characters off a string.
|
|
@param str String to trim.
|
|
@param set String of characters to remove.
|
|
@param where Flags to indicate trim from the start, end or both. Use WEBS_TRIM_START, WEBS_TRIM_END, WEBS_TRIM_BOTH.
|
|
@return Returns a pointer to the trimmed string. May not equal \a str.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *strim(char *str, cchar *set, int where);
|
|
|
|
/**
|
|
Convert a string to upper case.
|
|
@description Convert a string to its upper case equivalent.
|
|
@param str String to convert. This string is modified.
|
|
@return Returns a pointer to the converted string. Will always equal str. Caller must not free.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *supper(char *str);
|
|
|
|
/**
|
|
Callback function for events
|
|
@param data Opaque data argument
|
|
@param id Event ID
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
typedef void (*WebsEventProc)(void *data, int id);
|
|
|
|
/**
|
|
Start a callback event
|
|
@description This schedules an event to run once. The event can be rescheduled in the callback by invoking
|
|
websRestartEvent.
|
|
@param delay Delay in milliseconds in which to run the callback
|
|
@param proc Callback procedure function. Signature is: void (*fn)(void *data, int id)
|
|
@param data Data reference to pass to the callback
|
|
@return A positive integer event ID
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websStartEvent(int delay, WebsEventProc proc, void *data);
|
|
|
|
/**
|
|
Stop an event
|
|
@param id Event id allocated by websStartEvent
|
|
@return Integer handle index. Otherwise return -1 on allocation errors.
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websStopEvent(int id);
|
|
|
|
/**
|
|
Restart an event
|
|
@param id Event id allocated by websStartEvent
|
|
@param delay Delay in milliseconds till the event next runs
|
|
@ingroup WebsRuntime
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websRestartEvent(int id, int delay);
|
|
|
|
/**
|
|
Run due events
|
|
@ingroup WebsRuntime
|
|
@return Time delay till the next event
|
|
@internal
|
|
*/
|
|
PUBLIC int websRunEvents(void);
|
|
|
|
/* Forward declare */
|
|
struct WebsRoute;
|
|
struct WebsUser;
|
|
struct WebsSession;
|
|
struct Webs;
|
|
|
|
/********************************** Upload ************************************/
|
|
#if ME_GOAHEAD_UPLOAD
|
|
|
|
/**
|
|
File upload structure
|
|
@see websUploadOpen websLookupUpload websGetUpload
|
|
@defgroup WebsUpload WebsUpload
|
|
*/
|
|
typedef struct WebsUpload {
|
|
char *filename; /**< Local (temp) name of the file */
|
|
char *clientFilename; /**< Client side name of the file */
|
|
char *contentType; /**< Content type */
|
|
ssize size; /**< Uploaded file size */
|
|
} WebsUpload;
|
|
|
|
/**
|
|
Open the file upload filter
|
|
@ingroup WebsUpload
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websUploadOpen(void);
|
|
|
|
/**
|
|
Get the hash of uploaded files for the request
|
|
@param wp Webs request object
|
|
@return Hash table of uploaded files
|
|
@ingroup WebsUpload
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsHash websGetUpload(struct Webs *wp);
|
|
|
|
/**
|
|
Open the file upload filter
|
|
@param wp Webs request object
|
|
@param key Form upload name
|
|
@return Upload object for the uploaded file
|
|
@ingroup WebsUpload
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsUpload *websLookupUpload(struct Webs *wp, cchar *key);
|
|
#endif
|
|
/********************************** Defines ***********************************/
|
|
|
|
#define WEBS_MAX_PORT_LEN 16 /* Max digits in port number */
|
|
#define WEBS_HASH_INIT 67 /* Hash size for form table */
|
|
#define WEBS_SESSION_HASH 31 /* Hash size for session stores */
|
|
#define WEBS_SESSION_PRUNE (60*1000) /* Prune sessions every minute */
|
|
|
|
/*
|
|
The license agreement stipulates that you must not change this definition.
|
|
*/
|
|
#define WEBS_NAME "Server: GoAhead-http"
|
|
|
|
/*
|
|
Request flags
|
|
*/
|
|
#define WEBS_ACCEPTED 0x1 /**< TLS connection accepted */
|
|
#define WEBS_CHUNKING 0x2 /**< Currently chunking output body data */
|
|
#define WEBS_CLOSED 0x4 /**< Connection closed, ready to free */
|
|
#define WEBS_COOKIE 0x8 /**< Cookie supplied in request */
|
|
#if DEPRECATED || 1
|
|
#define WEBS_FINALIZED 0x10 /**< Output is finalized */
|
|
#endif
|
|
#define WEBS_FORM 0x20 /**< Request is a form (url encoded data) */
|
|
#define WEBS_HEADERS_CREATED 0x40 /**< Headers have been created and buffered */
|
|
#define WEBS_HTTP11 0x80 /**< Request is using HTTP/1.1 */
|
|
#define WEBS_JSON 0x100 /**< Request has a JSON payload */
|
|
#define WEBS_KEEP_ALIVE 0x200 /**< HTTP/1.1 keep alive */
|
|
#define WEBS_REROUTE 0x400 /**< Restart route matching */
|
|
#define WEBS_RESPONSE_TRACED 0x800 /**< Started tracing the response */
|
|
#define WEBS_SECURE 0x1000 /**< Connection uses SSL */
|
|
#define WEBS_UPLOAD 0x2000 /**< Multipart-mime file upload */
|
|
#define WEBS_VARS_ADDED 0x4000 /**< Query and body form vars added */
|
|
#if ME_GOAHEAD_LEGACY
|
|
#define WEBS_LOCAL 0x8000 /**< Request from local system */
|
|
#endif
|
|
|
|
/*
|
|
Incoming chunk encoding states. Used for tx and rx chunking.
|
|
*/
|
|
#define WEBS_CHUNK_UNCHUNKED 0 /**< Data is not transfer-chunk encoded */
|
|
#define WEBS_CHUNK_START 1 /**< Start of a new chunk */
|
|
#define WEBS_CHUNK_HEADER 2 /**< Preparing tx chunk header */
|
|
#define WEBS_CHUNK_DATA 3 /**< Start of chunk data */
|
|
|
|
/*
|
|
Webs state
|
|
*/
|
|
#define WEBS_BEGIN 0 /**< Beginning state */
|
|
#define WEBS_CONTENT 1 /**< Ready for body data */
|
|
#define WEBS_READY 2 /**< Ready to route and start handler */
|
|
#define WEBS_RUNNING 3 /**< Processing request */
|
|
#define WEBS_COMPLETE 4 /**< Request complete */
|
|
|
|
/*
|
|
Session names
|
|
*/
|
|
#define WEBS_SESSION "-goahead-session-"
|
|
#define WEBS_SESSION_USERNAME "_:USERNAME:_" /* Username variable */
|
|
|
|
/*
|
|
WebsDone flags
|
|
*/
|
|
#define WEBS_CODE_MASK 0xFFFF /**< Mask valid status codes */
|
|
#define WEBS_CLOSE 0x20000 /**< Close connection */
|
|
#define WEBS_NOLOG 0x40000 /**< Don't write error to log */
|
|
|
|
/**
|
|
Callback for write I/O events
|
|
*/
|
|
typedef void (*WebsWriteProc)(struct Webs *wp);
|
|
|
|
/**
|
|
GoAhead request structure. This is a per-socket connection structure.
|
|
@defgroup Webs Webs
|
|
*/
|
|
typedef struct Webs {
|
|
WebsBuf rxbuf; /**< Raw receive buffer */
|
|
WebsBuf input; /**< Receive buffer after de-chunking */
|
|
WebsBuf output; /**< Transmit buffer after chunking */
|
|
WebsBuf chunkbuf; /**< Pre-chunking data buffer */
|
|
WebsBuf *txbuf;
|
|
WebsTime since; /**< Parsed if-modified-since time */
|
|
WebsTime timestamp; /**< Last transaction with browser */
|
|
WebsHash vars; /**< CGI standard variables */
|
|
int timeout; /**< Timeout handle */
|
|
char ipaddr[ME_MAX_IP]; /**< Connecting ipaddress */
|
|
char ifaddr[ME_MAX_IP]; /**< Local interface ipaddress */
|
|
|
|
int rxChunkState; /**< Rx chunk encoding state */
|
|
ssize rxChunkSize; /**< Rx chunk size */
|
|
char *rxEndp; /**< Pointer to end of raw data in input beyond endp */
|
|
ssize lastRead; /**< Number of bytes last read from the socket */
|
|
bool eof; /**< If at the end of the request content */
|
|
|
|
char txChunkPrefix[16]; /**< Transmit chunk prefix */
|
|
char *txChunkPrefixNext; /**< Current I/O pos in txChunkPrefix */
|
|
ssize txChunkPrefixLen; /**< Length of prefix */
|
|
ssize txChunkLen; /**< Length of the chunk */
|
|
int txChunkState; /**< Transmit chunk state */
|
|
|
|
char *authDetails; /**< Http header auth details */
|
|
char *authResponse; /**< Outgoing auth header */
|
|
char *authType; /**< Authorization type (Basic/DAA) */
|
|
char *contentType; /**< Body content type */
|
|
char *cookie; /**< Request cookie string */
|
|
char *decodedQuery; /**< Decoded request query */
|
|
char *digest; /**< Password digest */
|
|
char *ext; /**< Path extension */
|
|
char *filename; /**< Document path name */
|
|
char *host; /**< Requested host */
|
|
char *method; /**< HTTP request method */
|
|
char *password; /**< Authorization password */
|
|
char *path; /**< Path name without query. This is decoded. */
|
|
char *protoVersion; /**< Protocol version (HTTP/1.1)*/
|
|
char *protocol; /**< Protocol scheme (normally http|https) */
|
|
char *putname; /**< PUT temporary filename */
|
|
char *query; /**< Request query. This is decoded. */
|
|
char *realm; /**< Realm field supplied in auth header */
|
|
char *referrer; /**< The referring page */
|
|
char *url; /**< Full request url. This is not decoded. */
|
|
char *userAgent; /**< User agent (browser) */
|
|
char *username; /**< Authorization username */
|
|
int sid; /**< Socket id (handler) */
|
|
int listenSid; /**< Listen Socket id */
|
|
int port; /**< Request port number */
|
|
int state; /**< Current state */
|
|
int flags; /**< Current flags -- see above */
|
|
int code; /**< Response status code */
|
|
int routeCount; /**< Route count limiter */
|
|
ssize rxLen; /**< Rx content length */
|
|
ssize rxRemaining; /**< Remaining content to read from client */
|
|
ssize txLen; /**< Tx content length header value */
|
|
int wid; /**< Index into webs */
|
|
#if ME_GOAHEAD_CGI
|
|
char *cgiStdin; /**< Filename for CGI program input */
|
|
int cgifd; /**< File handle for CGI program input */
|
|
#endif
|
|
#if !ME_ROM
|
|
int putfd; /**< File handle to write PUT data */
|
|
#endif
|
|
int docfd; /**< File descriptor for document being served */
|
|
ssize written; /**< Bytes actually transferred */
|
|
ssize putLen; /**< Bytes read by a PUT request */
|
|
|
|
int finalized: 1; /**< Request has been completed */
|
|
int error: 1; /**< Request has an error */
|
|
int connError: 1; /**< Request has a connection error */
|
|
|
|
WebsHash responseCookies; /**< Outgoing cookies */
|
|
struct WebsSession *session; /**< Session record */
|
|
struct WebsRoute *route; /**< Request route */
|
|
struct WebsUser *user; /**< User auth record */
|
|
WebsWriteProc writeData; /**< Handler write I/O event callback. Used by fileHandler */
|
|
int encoded; /**< True if the password is MD5(username:realm:password) */
|
|
#if ME_GOAHEAD_DIGEST
|
|
char *cnonce; /**< check nonce */
|
|
char *digestUri; /**< URI found in digest header */
|
|
char *nonce; /**< opaque-to-client string sent by server */
|
|
char *nc; /**< nonce count */
|
|
char *opaque; /**< opaque value passed from server */
|
|
char *qop; /**< quality operator */
|
|
#endif
|
|
#if ME_GOAHEAD_UPLOAD
|
|
int upfd; /**< Upload file handle */
|
|
WebsHash files; /**< Uploaded files */
|
|
char *boundary; /**< Mime boundary (static) */
|
|
ssize boundaryLen; /**< Boundary length */
|
|
int uploadState; /**< Current file upload state */
|
|
WebsUpload *currentFile; /**< Current file context */
|
|
char *clientFilename; /**< Current file filename */
|
|
char *uploadTmp; /**< Current temp filename for upload data */
|
|
char *uploadVar; /**< Current upload form variable name */
|
|
#endif
|
|
void *ssl; /**< SSL context */
|
|
} Webs;
|
|
|
|
#if ME_GOAHEAD_LEGACY
|
|
#define WEBS_LEGACY_HANDLER 0x1 /* Using legacy calling sequence */
|
|
#endif
|
|
|
|
|
|
/**
|
|
GoAhead handler service callback
|
|
@param wp Webs request object
|
|
@return True if the handler serviced the request
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef bool (*WebsHandlerProc)(Webs *wp);
|
|
|
|
/**
|
|
GoAhead handler close to release memory prior to shutdown.
|
|
@description This callback is invoked when GoAhead is shutting down.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef void (*WebsHandlerClose)(void);
|
|
|
|
/**
|
|
GoAhead handler object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsHandler {
|
|
char *name; /**< Handler name */
|
|
WebsHandlerProc match; /**< Handler match callback */
|
|
WebsHandlerProc service; /**< Handler service callback */
|
|
WebsHandlerClose close; /**< Handler close callback */
|
|
int flags; /**< Handler control flags */
|
|
} WebsHandler;
|
|
|
|
/**
|
|
Action callback
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef void (*WebsAction)(Webs *wp);
|
|
|
|
#if ME_GOAHEAD_LEGACY
|
|
typedef void (*WebsProc)(Webs *wp, char *path, char *query);
|
|
#endif
|
|
|
|
/**
|
|
Error code list
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsError {
|
|
int code; /**< HTTP error code */
|
|
char *msg; /**< HTTP error message */
|
|
} WebsError;
|
|
|
|
/**
|
|
Mime type list
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsMime {
|
|
char *type; /**< Mime type */
|
|
char *ext; /**< File extension */
|
|
} WebsMime;
|
|
|
|
/**
|
|
File information structure.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsFileInfo {
|
|
ulong size; /**< File length */
|
|
int isDir; /**< Set if directory */
|
|
WebsTime mtime; /**< Modified time */
|
|
} WebsFileInfo;
|
|
|
|
/**
|
|
Compiled Rom Page Index
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsRomIndex {
|
|
char *path; /**< Web page URL path */
|
|
uchar *page; /**< Web page data */
|
|
int size; /**< Size of web page in bytes */
|
|
Offset pos; /**< Current read position */
|
|
} WebsRomIndex;
|
|
|
|
#if ME_ROM
|
|
/**
|
|
List of documents to service when built with ROM support
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC_DATA WebsRomIndex websRomIndex[];
|
|
#endif
|
|
|
|
#define WEBS_DECODE_TOKEQ 1 /**< Decode base 64 blocks up to a NULL or equals */
|
|
|
|
/**
|
|
Accept a new connection
|
|
@param sid Socket ID handle for the newly accepted socket
|
|
@param ipaddr IP address originating the connection.
|
|
@param port Port number originating the connection.
|
|
@param listenSid Socket ID of the listening socket
|
|
@return Zero if successful, otherwise -1
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websAccept(int sid, cchar *ipaddr, int port, int listenSid);
|
|
|
|
/**
|
|
Open the action handler
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websActionOpen(void);
|
|
|
|
/**
|
|
Allocate a new Webs object
|
|
@param sid Socket ID handle for the newly accepted socket
|
|
@return The webs[] handle index for the allocated Webs object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websAlloc(int sid);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websCancelTimeout(Webs *wp);
|
|
|
|
#if ME_GOAHEAD_CGI
|
|
/**
|
|
Open the CGI handler
|
|
@return Zero if successful, otherwise -1
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websCgiOpen(void);
|
|
|
|
/**
|
|
CGI handler service callback
|
|
@param wp Webs object
|
|
@return Returns 1 if the request was handled.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websCgiHandler(Webs *wp);
|
|
|
|
/**
|
|
Poll for output from CGI processes and output.
|
|
@return Time delay till next poll
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websCgiPoll(void);
|
|
|
|
/* Internal */
|
|
PUBLIC bool cgiHandler(Webs *wp);
|
|
|
|
#endif /* ME_GOAHEAD_CGI */
|
|
|
|
/**
|
|
Close the core GoAhead web server module
|
|
@description Invoked when GoAhead is shutting down.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websClose(void);
|
|
|
|
/**
|
|
Close an open file
|
|
@param fd Open file handle returned by websOpenFile
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websCloseFile(int fd);
|
|
|
|
/**
|
|
Compare a request variable
|
|
@param wp Webs request object
|
|
@param var Variable name
|
|
@param value Value to compare with
|
|
@return True if the value matches. Otherwise return 0
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websCompareVar(Webs *wp, cchar *var, cchar *value);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@param nbytes Number of bytes the handler has consumed from the input buffer.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websConsumeInput(Webs *wp, ssize nbytes);
|
|
|
|
/**
|
|
Decode the string using base-64 encoding
|
|
@description This modifies the original string
|
|
@param str String to decode
|
|
@return The original string. Caller must not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websDecode64(char *str);
|
|
|
|
/**
|
|
Decode a block using base-46 encoding
|
|
@param str String to decode. The string must be null terminated.
|
|
@param len Reference to an integer holding the length of the decoded string.
|
|
@param flags Reserved.
|
|
@return The original string.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websDecode64Block(char *str, ssize *len, int flags);
|
|
|
|
/**
|
|
Decode a URL expanding %NN encoding
|
|
@description Supports insitu decoding. i.e. Input and output buffers may be the same.
|
|
@param decoded Buffer to hold the decoded URL
|
|
@param input Input URL or buffer to decode
|
|
@param len Length of the decoded buffer.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
|
|
PUBLIC void websDecodeUrl(char *decoded, char *input, ssize len);
|
|
|
|
/**
|
|
Define a request handler
|
|
@param name Name of the handler
|
|
@param match Handler callback match procedure. Invoked to match the request with the handler.
|
|
The handler should return true to accept the request.
|
|
@param service Handler callback service procedure. Invoked to service each request.
|
|
@param close Handler callback close procedure. Called when GoAhead is shutting down.
|
|
@param flags Set to WEBS_LEGACY_HANDLER to support the legacy handler API calling sequence.
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websDefineHandler(cchar *name, WebsHandlerProc match, WebsHandlerProc service, WebsHandlerClose close, int flags);
|
|
|
|
/**
|
|
Complete a request.
|
|
@description A handler should call websDone() to complete the request.
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websDone(Webs *wp);
|
|
|
|
/**
|
|
Encode a string using base-64 encoding
|
|
@description The string is encoded insitu.
|
|
@param str String to encode
|
|
@return The original string.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websEncode64(char *str);
|
|
|
|
/**
|
|
Encode a block using base-64 encoding
|
|
@description The string is encoded insitu.
|
|
@param str String to encode.
|
|
@param len Length of string to encode
|
|
@return The original string.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websEncode64Block(char *str, ssize len);
|
|
|
|
/**
|
|
Escape unsafe characters in a string
|
|
@param str String to escape
|
|
@return An allocated block containing the escaped string. Caller must free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websEscapeHtml(cchar *str);
|
|
|
|
/**
|
|
Complete a request with an error response
|
|
@param wp Webs request object
|
|
@param code HTTP status code
|
|
@param fmt Message printf style format
|
|
@param ... Format args
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websError(Webs *wp, int code, cchar *fmt, ...);
|
|
|
|
/**
|
|
Get a message for a HTTP status code
|
|
@param code HTTP status code
|
|
@return Http status message. Caller must not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websErrorMsg(int code);
|
|
|
|
/**
|
|
Open and initialize the file handler
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websFileOpen(void);
|
|
|
|
/**
|
|
Flush buffered transmit data and compact the transmit buffer to make room for more data
|
|
@description This call initiates sending buffered data. If blocking mode is selected via the block parameter,
|
|
this call will wait until all the data has been sent to the O/S for transmission to the client.
|
|
If block is false, the flush will be initiated and the call will return immediately without blocking.
|
|
@param wp Webs request object
|
|
@param block Set to true to wait for all data to be written to the socket. Set to false to
|
|
write whatever the socket can absorb without blocking.
|
|
@return -1 for I/O errors. Return zero if there is more data remaining in the buffer. Return 1 if the
|
|
contents of the transmit buffer are fully written and the buffer is now empty.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websFlush(Webs *wp, bool block);
|
|
|
|
/**
|
|
Free the webs request object.
|
|
@description Callers should call websDone to complete requests prior to invoking websFree.
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websFree(Webs *wp);
|
|
|
|
/**
|
|
Get the background execution flag
|
|
@description If GoAhead is invoked with --background, it will run as a daemon in the background.
|
|
@return True if GoAhead is running in the background.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websGetBackground(void);
|
|
|
|
#if ME_GOAHEAD_CGI
|
|
/**
|
|
Get a unique temporary filename for CGI communications
|
|
@return Allocated filename string. Caller must free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websGetCgiCommName(void);
|
|
#endif /* ME_GOAHEAD_CGI */
|
|
|
|
/**
|
|
Get the request cookie if supplied
|
|
@param wp Webs request object
|
|
@return Cookie string if defined, otherwise null. Caller must not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetCookie(Webs *wp);
|
|
|
|
/**
|
|
Get a date as a string
|
|
@description If sbuf is supplied, it is used to calculate the date. Otherwise, the current time is used.
|
|
@param sbuf File info object
|
|
@return An allocated date string. Caller should free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websGetDateString(WebsFileInfo *sbuf);
|
|
|
|
/**
|
|
Get the debug flag
|
|
@description If GoAhead is invoked with --debugger, the debug flag will be set to true
|
|
@return True if GoAhead is running in debug mode.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websGetDebug(void);
|
|
|
|
/**
|
|
Get the base file directory for a request
|
|
@description Returns the request route directory if defined, otherwise returns the documents directory.
|
|
@param wp Webs request object
|
|
@return Path name string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetDir(Webs *wp);
|
|
|
|
/**
|
|
Get the GoAhead base documents directory
|
|
@description The documents directory is defined at build time and may be overridden by the GoAhead command line.
|
|
@return Path string for the documents directory.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websGetDocuments(void);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@return True if all the request body data has been received.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websGetEof(Webs *wp);
|
|
|
|
/**
|
|
Get the request URI extension
|
|
@param wp Webs request object
|
|
@return The URI filename extension component. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetExt(Webs *wp);
|
|
|
|
/**
|
|
Get the request filename
|
|
@description The URI is mapped to a filename by decoding and prepending with the request directory.
|
|
@param wp Webs request object
|
|
@return Filename string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetFilename(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.
|
|
@param wp Webs request object
|
|
@return Host string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetHost(Webs *wp);
|
|
|
|
/**
|
|
Get the request interface address
|
|
@param wp Webs request object
|
|
@return Network interface string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetIfaddr(Webs *wp);
|
|
|
|
/**
|
|
Get the default index document name
|
|
@description The default index is "index.html" and can be updated via websSetIndex.
|
|
@return Index name string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetIndex(void);
|
|
|
|
/**
|
|
Get the request method
|
|
@param wp Webs request object
|
|
@return HTTP method string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetMethod(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.
|
|
@param wp Webs request object
|
|
@return Password string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetPassword(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 "/".
|
|
@param wp Webs request object
|
|
@return Request path string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetPath(Webs *wp);
|
|
|
|
/**
|
|
Get the request TCP/IP port
|
|
@param wp Webs request object
|
|
@return TCP/IP Port integer
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websGetPort(Webs *wp);
|
|
|
|
/**
|
|
Get the request HTTP protocol
|
|
@description This will be set to either "http" or "https"
|
|
@param wp Webs request object
|
|
@return Protocol string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetProtocol(Webs *wp);
|
|
|
|
/**
|
|
Get the request query component
|
|
@param wp Webs request object
|
|
@return Request query string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetQuery(Webs *wp);
|
|
|
|
/**
|
|
Get the server host name
|
|
@return Host name string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetServer(void);
|
|
|
|
/**
|
|
Get the server host name with port number.
|
|
@return Host name string with port number. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetServerUrl(void);
|
|
|
|
/**
|
|
Get the server IP address
|
|
@return Server IP address string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetServerAddress(void);
|
|
|
|
/**
|
|
Get the server IP address with port number
|
|
@return Server IP:PORT address string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetServerAddressUrl(void);
|
|
|
|
/**
|
|
Get the request URI
|
|
@description This returns the request URI. This may be modified if the request is rewritten via websRewrite
|
|
@param wp Webs request object
|
|
@return URI string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetUrl(Webs *wp);
|
|
|
|
/**
|
|
Get the client User-Agent HTTP header
|
|
@param wp Webs request object
|
|
@return User-Agent string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetUserAgent(Webs *wp);
|
|
|
|
/**
|
|
Get the request username
|
|
@description If the request is authenticated, this call returns the username supplied during authentication.
|
|
@param wp Webs request object
|
|
@return Username string if defined, otherwise null. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetUsername(Webs *wp);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@param name Variable name
|
|
@param defaultValue Default value to return if the variable is not defined
|
|
@return Variable value string. Caller should not free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetVar(Webs *wp, cchar *name, cchar *defaultValue);
|
|
|
|
/**
|
|
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.
|
|
@param endpoint IPv4 or IPv6 address on which to listen.
|
|
@return Positive integer holding a Socket ID handle if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websListen(cchar *endpoint);
|
|
|
|
/**
|
|
Get an MD5 digest of a string
|
|
@param str String to analyze.
|
|
@return Allocated MD5 checksum. Caller should free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websMD5(cchar *str);
|
|
|
|
/**
|
|
Get an MD5 digest of a block and optionally prepend a prefix.
|
|
@param buf Block to analyze
|
|
@param length Length of block
|
|
@param prefix Optional prefix to prepend to the MD5 sum.
|
|
@return Allocated MD5 checksum. Caller should free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websMD5Block(cchar *buf, ssize length, cchar *prefix);
|
|
|
|
/**
|
|
Normalize a URI path
|
|
@description This removes "./", "../" and redundant separators.
|
|
@param path URI path to normalize
|
|
@return An allocated normalized URI path. Caller must free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websNormalizeUriPath(cchar *path);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websNoteRequestActivity(Webs *wp);
|
|
|
|
/**
|
|
Close the runtime code.
|
|
@description Called from websClose
|
|
@ingroup Webs
|
|
@internal
|
|
*/
|
|
PUBLIC void websRuntimeClose(void);
|
|
|
|
/**
|
|
Open the runtime code.
|
|
@description Called from websOpen
|
|
@return Zero if successful
|
|
@ingroup Webs
|
|
@internal
|
|
*/
|
|
PUBLIC int websRuntimeOpen(void);
|
|
|
|
/**
|
|
Open the web server
|
|
@description This initializes the web server and defines the documents directory.
|
|
@param documents Optional web documents directory. If set to null, the build time ME_GOAHEAD_DOCUMENTS value
|
|
is used for the documents directory.
|
|
@param routes Optional filename for a route configuration file to load. Additional route or
|
|
authentication configuration files can be loaded via websLoad.
|
|
@param routes Webs request object
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websOpen(cchar *documents, cchar *routes);
|
|
|
|
/**
|
|
Close the O/S dependent code.
|
|
@description Called from websClose
|
|
@ingroup Webs
|
|
@internal
|
|
*/
|
|
PUBLIC void websOsClose(void);
|
|
|
|
/**
|
|
Open the O/S dependent code.
|
|
@description Called from websOpen
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@internal
|
|
*/
|
|
PUBLIC int websOsOpen(void);
|
|
|
|
/**
|
|
Open the web page document for the current request
|
|
@param path Filename path to open
|
|
@param flags File open flags
|
|
@param mode Permissions mask
|
|
@return Positive file handle if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websOpenFile(cchar *path, int flags, int mode);
|
|
|
|
/**
|
|
Open the options handler
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websOptionsOpen(void);
|
|
|
|
/**
|
|
Close the document page
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websPageClose(Webs *wp);
|
|
|
|
/**
|
|
Test if the document page for the request corresponds to a directory
|
|
@param wp Webs request object
|
|
@return True if the filename is a directory
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websPageIsDirectory(Webs *wp);
|
|
|
|
/**
|
|
Open a web page document for a request
|
|
@param wp Webs request object
|
|
@param mode File open mode. Select from O_RDONLY and O_BINARY. Rom files systems ignore this argument.
|
|
@param perms Ignored
|
|
@return File handle if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websPageOpen(Webs *wp, int mode, int perms);
|
|
|
|
/**
|
|
Read data from the request page document
|
|
@param wp Webs request object
|
|
@param buf Buffer for the read data
|
|
@param size Size of buf
|
|
@return Count of bytes read if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize websPageReadData(Webs *wp, char *buf, ssize size);
|
|
|
|
/**
|
|
Seek to a position in the request page document
|
|
@param wp Webs request object
|
|
@param offset Offset of location in the file to seek to. This is relative to the specified origin.
|
|
@param origin Set to SEEK_CUR, SEEK_SET or SEEK_END to position relative to the current position,
|
|
beginning or end of the document.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websPageSeek(Webs *wp, Offset offset, int origin);
|
|
|
|
/**
|
|
Get file status for the current request document
|
|
@param wp Webs request object
|
|
@param sbuf File information structure to modify with file status
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websPageStat(Webs *wp, WebsFileInfo *sbuf);
|
|
|
|
#if !ME_ROM
|
|
/**
|
|
Process request PUT body data
|
|
@description This routine is called by the core HTTP engine to process request PUT data.
|
|
@param wp Webs request object
|
|
@return True if processing the request can proceed.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websProcessPutData(Webs *wp);
|
|
#endif
|
|
|
|
/**
|
|
Pump the state machine
|
|
@description This routine will advance the connection state machine in response to events.
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websPump(Webs *wp);
|
|
|
|
/**
|
|
Define an action callback for use with the action handler.
|
|
@description The action handler binds a C function to a URI under "/action".
|
|
@param name URI path suffix. This suffix is added to "/action" to form the bound URI path.
|
|
@param fun Callback function. The signature is void (*WebsAction)(Webs *wp);
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websDefineAction(cchar *name, void *fun);
|
|
|
|
/**
|
|
Read data from an open file
|
|
@param fd Open file handle returned by websOpenFile
|
|
@param buf Buffer for the read data
|
|
@param size Size of buf
|
|
@return Count of bytes read if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize websReadFile(int fd, char *buf, ssize size);
|
|
|
|
/**
|
|
Read all the data from a file
|
|
@param path File path to read from
|
|
@return An allocated buffer containing the file data with an appended null. Caller must free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websReadWholeFile(cchar *path);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@param url URL to direct the client to.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websRedirect(Webs *wp, cchar *url);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@param status HTTP status code to use in selecting the route redirection.
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websRedirectByStatus(Webs *wp, int status);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@param status HTTP status code.
|
|
@param msg Response message body
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websResponse(Webs *wp, int status, cchar *msg);
|
|
|
|
/**
|
|
Rewrite a request
|
|
@description Handlers may choose to not process a request but rather rewrite requests and then reroute.
|
|
@param wp Webs request object
|
|
@param url New request URL.
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websRewriteRequest(Webs *wp, cchar *url);
|
|
|
|
/**
|
|
Open the file system module
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websFsOpen(void);
|
|
|
|
/**
|
|
Close the file system module
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websFsClose(void);
|
|
|
|
/**
|
|
Seek to a position in the current request page document
|
|
@param fd Open file handle returned by websOpenFile
|
|
@param offset Location in the file to seek to.
|
|
@param origin Set to SEEK_CUR, SEEK_SET or SEEK_END to position relative to the current position,
|
|
beginning or end of the document.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC Offset websSeekFile(int fd, Offset offset, int origin);
|
|
|
|
/**
|
|
Get file status for a file
|
|
@param path Filename path
|
|
@param sbuf File information structure to modify with file status
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websStatFile(cchar *path, WebsFileInfo *sbuf);
|
|
|
|
/**
|
|
One line embedding API.
|
|
@description This call will also open auth.txt and route.txt for authentication and routing configuration.
|
|
@param endpoint IP:PORT address on which to listen
|
|
@param documents Directory containing web documents to serve
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websServer(cchar *endpoint, cchar *documents);
|
|
|
|
/**
|
|
Service I/O events until finished
|
|
@description This will wait for socket events and service those until *finished is set to true
|
|
@param finished Integer location to test. If set to true, then exit. Note: setting finished will not
|
|
automatically wake up the service routine.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websServiceEvents(int *finished);
|
|
|
|
/**
|
|
Set the background processing flag
|
|
@param on Value to set the background flag to.
|
|
@ingroup Webs
|
|
@internal
|
|
*/
|
|
PUBLIC void websSetBackground(int on);
|
|
|
|
/**
|
|
Define a background write I/O event callback
|
|
@param wp Webs request object
|
|
@param proc Write callback
|
|
*/
|
|
PUBLIC void websSetBackgroundWriter(Webs *wp, WebsWriteProc proc);
|
|
|
|
/*
|
|
Flags for websSetCookie
|
|
*/
|
|
#define WEBS_COOKIE_SECURE 0x1 /**< Flag for websSetCookie for secure cookies (https only) */
|
|
#define WEBS_COOKIE_HTTP 0x2 /**< Flag for websSetCookie for http cookies (http only) */
|
|
#define WEBS_COOKIE_SAME_LAX 0x4 /**< Flag for websSetCookie for SameSite=Lax */
|
|
#define WEBS_COOKIE_SAME_STRICT 0x8 /**< Flag for websSetCookie for SameSite=Strict */
|
|
|
|
/**
|
|
Define a cookie to include in the response
|
|
@param wp Webs request object
|
|
@param name Cookie name
|
|
@param value Cookie value
|
|
@param path URI path prefix applicable for this cookie
|
|
@param domain Domain applicable for this cookie
|
|
@param lifespan Cookie lifespan in seconds
|
|
@param flags Set 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. Or in WEBS_COOKIE_SAME_LAX for SameSite=Lax
|
|
and WEBS_COOKIE_SAME_STRICT for SameSite=Strict.
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetCookie(Webs *wp, cchar *name, cchar *value, cchar *path, cchar *domain, int lifespan, int flags);
|
|
|
|
/**
|
|
Set the debug processing flag
|
|
@param on Value to set the debug flag to.
|
|
@ingroup Webs
|
|
@internal
|
|
*/
|
|
PUBLIC void websSetDebug(int on);
|
|
|
|
/**
|
|
Set the web documents directory
|
|
@description The web documents directory is used when resolving request URIs into filenames.
|
|
@param dir Directory path to use
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetDocuments(cchar *dir);
|
|
|
|
/**
|
|
Create the CGI environment variables for the current request.
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetEnv(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.
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetFormVars(Webs *wp);
|
|
|
|
/**
|
|
Define the host name for the server
|
|
@param host String host name
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetHost(cchar *host);
|
|
|
|
/**
|
|
Define the host IP address
|
|
@param ipaddr Host IP address
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetIpAddr(cchar *ipaddr);
|
|
|
|
/**
|
|
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.
|
|
@param filename Web document name to use as the index. This should not contain any directory components.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetIndex(cchar *filename);
|
|
|
|
/**
|
|
Create request variables for query string data
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetQueryVars(Webs *wp);
|
|
|
|
/**
|
|
Set the response HTTP status code
|
|
@param wp Webs request object
|
|
@param status HTTP status code
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetStatus(Webs *wp, int status);
|
|
|
|
/**
|
|
Set the response body content length
|
|
@param wp Webs request object
|
|
@param length Length value to use
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetTxLength(Webs *wp, ssize length);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@param name Variable name to set
|
|
@param fmt Value format string
|
|
@param ... Args to format
|
|
@return the allocated WebsKey
|
|
@ingroup Webs
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC WebsKey *websSetVarFmt(Webs *wp, cchar *name, cchar *fmt, ...);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@param name Variable name to set
|
|
@param value Value to set
|
|
@return the allocated WebsKey
|
|
@ingroup Webs
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC WebsKey *websSetVar(Webs *wp, cchar *name, cchar *value);
|
|
|
|
/**
|
|
Test if a request variable is defined
|
|
@param wp Webs request object
|
|
@param name Variable name
|
|
@return True if the variable is defined
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websTestVar(Webs *wp, cchar *name);
|
|
|
|
/**
|
|
Create a temporary filename
|
|
This does not guarantee the filename is unique or that it is not already in use by another application.
|
|
@param dir Directory to locate the temp file. Defaults to the O/S default temporary directory (usually /tmp)
|
|
@param prefix Filename prefix
|
|
@return An allocated filename string
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websTempFile(cchar *dir, cchar *prefix);
|
|
|
|
/**
|
|
Open the date/time parsing module
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC int websTimeOpen(void);
|
|
|
|
/**
|
|
Close the date/time parsing module
|
|
@ingroup Webs
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC void websTimeClose(void);
|
|
|
|
/**
|
|
Parse a date/time string
|
|
@description Try to intelligently parse a date.
|
|
This is a tolerant parser. It is not validating and will do its best to parse any possible date string.
|
|
Supports the following date/time formats:
|
|
\n\n
|
|
ISO dates: 2009-05-21t16:06:05.000z
|
|
\n\n
|
|
Date: 07/28/2014, 07/28/08, Jan/28/2014, Jaunuary-28-2014, 28-jan-2014.
|
|
\n\n
|
|
Support date order: dd/mm/yy, mm/dd/yy and yyyy/mm/dd
|
|
\n\n
|
|
Support separators "/", ".", "-"
|
|
\n\n
|
|
Timezones: GMT|UTC[+-]NN[:]NN
|
|
\n\n
|
|
Time: 10:52[:23]
|
|
\n\n
|
|
@param time Reference to a
|
|
@param date Date/time string to parse
|
|
@param defaults Optionally supply missing components for the date/time. Set to NULL if not used.
|
|
@return Zero if successful, otherwise -1
|
|
@ingroup Webs
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC int websParseDateTime(WebsTime *time, cchar *date, struct tm *defaults);
|
|
|
|
/**
|
|
Parse a URL into its components
|
|
@param url URL to parse
|
|
@param buf Buffer to hold storage for various parsed components. Caller must free. NOTE: the parsed components may
|
|
point to locations in this buffer.
|
|
@param protocol Parsed URL protocol component
|
|
@param host Parsed hostname
|
|
@param port Parsed URL port
|
|
@param path Parsed URL path component
|
|
@param ext Parsed URL extension
|
|
@param reference Parsed URL reference portion (\#reference)
|
|
@param query Parsed URL query component
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC int websUrlParse(cchar *url, char **buf, char **protocol, char **host, char **port, char **path, char **ext,
|
|
char **reference, char **query);
|
|
|
|
/**
|
|
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 a Webs object for validity.
|
|
@param wp Webs request object
|
|
@return True if the webs object is still valid and the request has not been completed.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websValid(Webs *wp);
|
|
|
|
/**
|
|
Validate a URI path as expected in a HTTP request line
|
|
@description This expects a URI beginning with "/" and containing only valid URI characters.
|
|
The URI is decoded, and normalized removing "../" and "." segments.
|
|
The URI must begin with a "/" both before and after decoding and normalization.
|
|
@param uri URI to validate.
|
|
@return A validated, normalized URI path. Caller must free.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websValidateUriPath(cchar *uri);
|
|
|
|
/**
|
|
Test if a URI is using only valid characters
|
|
Note this does not test if the URI is fully legal. Some components of the URI have restricted character sets
|
|
that this routine does not test. This tests if the URI has only characters valid to use in a URI before decoding.
|
|
i.e. It will permit %NN encodings. The set of valid characters is:
|
|
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%"
|
|
@param uri Uri to test
|
|
@return True if the URI string is comprised of legal URI characters.
|
|
@ingroup Webs
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC bool websValidUriChars(cchar *uri);
|
|
|
|
/**
|
|
Write a set of standard response headers
|
|
@param wp Webs request object
|
|
@param contentLength Value for the Content-Length header which describes the length of the response body
|
|
@param redirect Value for the Location header which redirects the client to a new URL.
|
|
@ingroup Webs
|
|
@see websSetStatus
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websWriteHeaders(Webs *wp, ssize contentLength, cchar *redirect);
|
|
|
|
/**
|
|
Signify the end of the response headers
|
|
@description This call concludes the response headers and writes a blank line to the response.
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websWriteEndHeaders(Webs *wp);
|
|
|
|
/**
|
|
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.
|
|
@param wp Webs request object
|
|
@param key Header key value
|
|
@param fmt Header value format string.
|
|
@param ... Arguments to the format string.
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websWriteHeader(Webs *wp, cchar *key, cchar *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.
|
|
@param wp Webs request object
|
|
@param fmt Printf style format string.
|
|
@param ... Arguments to the format string.
|
|
@return Count of bytes written
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize websWrite(Webs *wp, cchar *fmt, ...);
|
|
|
|
/**
|
|
Write data to the open file
|
|
@param fd Open file handle returned by websOpenFile
|
|
@param buf Buffer for the read data
|
|
@param size Size of buf
|
|
@return Count of bytes read if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize websWriteFile(int fd, cchar *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. This routine will never return "short", it will always write all the data unless there are errors.
|
|
@param wp Webs request object
|
|
@param buf Buffer of data to write
|
|
@param size Length of buf
|
|
@return Count of bytes written or -1. This will always equal size if there are no errors.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize websWriteBlock(Webs *wp, cchar *buf, ssize size);
|
|
|
|
/**
|
|
Write a block of data to the network
|
|
@description This bypassed output buffering and is the lowest level write.
|
|
@param wp Webs request object
|
|
@param buf Buffer of data to write
|
|
@param size Length of buf
|
|
@return Count of bytes written. May be less than len if the socket is in non-blocking mode.
|
|
Returns -1 for errors and if the socket cannot absorb any more data. If the transport is saturated,
|
|
will return a negative error and errno will be set to EAGAIN or EWOULDBLOCK.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize websWriteSocket(Webs *wp, cchar *buf, ssize size);
|
|
|
|
#if ME_GOAHEAD_UPLOAD
|
|
/**
|
|
Process upload data for form, multipart mime file upload.
|
|
@param wp Webs request object
|
|
@return True if processing the request can proceed.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websProcessUploadData(Webs *wp);
|
|
|
|
/**
|
|
Free file upload data structures.
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websFreeUpload(Webs *wp);
|
|
#endif
|
|
|
|
#if ME_GOAHEAD_CGI
|
|
/**
|
|
Process CGI request body data.
|
|
@param wp Webs request object
|
|
@return True if processing the request can proceed.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websProcessCgiData(Webs *wp);
|
|
#endif
|
|
|
|
/************************************** Crypto ********************************/
|
|
|
|
/**
|
|
Get some random data
|
|
@param buf Reference to a buffer to hold the random data
|
|
@param length Size of the buffer
|
|
@param block Set to true if it is acceptable to block while accumulating entropy sufficient to provide good
|
|
random data. Setting to false will cause this API to not block and may return random data of a lower quality.
|
|
@ingroup Crypto
|
|
@stability Prototype.
|
|
*/
|
|
PUBLIC int websGetRandomBytes(char *buf, ssize length, bool block);
|
|
|
|
/**
|
|
Encrypt a password using the Blowfish algorithm
|
|
@param password User's password to encrypt
|
|
@param salt Salt text to add to password. Helps to make each user's password unique.
|
|
@param rounds Number of times to encrypt. More times, makes the routine slower and passwords harder to crack.
|
|
@return The encrypted password.
|
|
@ingroup Crypto
|
|
@stability Prototype
|
|
*/
|
|
PUBLIC char *websCryptPassword(cchar *password, cchar *salt, int rounds);
|
|
|
|
/**
|
|
Make salt for adding to a password.
|
|
@param size Size in bytes of the salt text.
|
|
@return The random salt text. Caller must free.
|
|
@ingroup Crypto
|
|
@stability Prototype
|
|
*/
|
|
PUBLIC char *websMakeSalt(ssize size);
|
|
|
|
/**
|
|
Make a password hash for a plain-text password using the Blowfish algorithm.
|
|
@param password User's password to encrypt
|
|
@param saltLength Length of salt text to add to password. Helps to make each user's password unique.
|
|
@param rounds Number of times to encrypt. More times, makes the routine slower and passwords harder to crack.
|
|
@return The encrypted password. Caller must free.
|
|
@ingroup Crypto
|
|
@stability Prototype
|
|
*/
|
|
PUBLIC char *websMakePassword(cchar *password, int saltLength, int rounds);
|
|
|
|
/**
|
|
Check a plain-text password against the defined hashed password.
|
|
@param plainTextPassword User's plain-text-password to check
|
|
@param passwordHash Required password in hashed format previously computed by websMakePassword.
|
|
@return True if the password is correct.
|
|
@ingroup Crypto
|
|
@stability Prototype
|
|
*/
|
|
PUBLIC bool websCheckPassword(cchar *plainTextPassword, cchar *passwordHash);
|
|
|
|
/**
|
|
Get a password from the terminal console
|
|
@param prompt Text prompt to display before reading the password
|
|
@return The entered password. Caller must free.
|
|
@ingroup Crypto
|
|
@stability Prototype
|
|
*/
|
|
PUBLIC char *websReadPassword(cchar *prompt);
|
|
|
|
/*************************************** JST ***********************************/
|
|
|
|
#if ME_GOAHEAD_JAVASCRIPT
|
|
/**
|
|
Javascript native function
|
|
@param jid JavaScript engine ID
|
|
@param wp Webs request object
|
|
@param argc Count of function arguments
|
|
@param argv Array of function arguments
|
|
@param defaultValue Default value to return if the variable is not defined
|
|
@return Return zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef int (*WebsJstProc)(int jid, Webs *wp, int argc, char **argv);
|
|
|
|
/**
|
|
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.
|
|
@param name Javascript function name
|
|
@param fn C function to invoke
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websDefineJst(cchar *name, WebsJstProc fn);
|
|
|
|
/**
|
|
Open the Javascript module.
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websJstOpen(void);
|
|
|
|
/**
|
|
Write data to the response
|
|
@param jid Javascript ID handle
|
|
@param wp Webs request object
|
|
@param argc Count of arguments
|
|
@param argv Array arguments
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websJstWrite(int jid, Webs *wp, int argc, char **argv);
|
|
#endif
|
|
|
|
/*************************************** SSL ***********************************/
|
|
|
|
#if ME_COM_SSL
|
|
/*
|
|
Default MakeMe settings
|
|
*/
|
|
#ifndef ME_GOAHEAD_SSL_AUTHORITY
|
|
#define ME_GOAHEAD_SSL_AUTHORITY ""
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_CACHE
|
|
#define ME_GOAHEAD_SSL_CACHE 512
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_CERTIFICATE
|
|
#define ME_GOAHEAD_SSL_CERTIFICATE ""
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_CIPHERS
|
|
#define ME_GOAHEAD_SSL_CIPHERS ""
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_KEY
|
|
#define ME_GOAHEAD_SSL_KEY ""
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_LOG_LEVEL
|
|
#define ME_GOAHEAD_SSL_LOG_LEVEL 4
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_RENEGOTIATE
|
|
#define ME_GOAHEAD_SSL_RENEGOTIATE 1
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_REVOKE
|
|
#define ME_GOAHEAD_SSL_REVOKE ""
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_TICKET
|
|
#define ME_GOAHEAD_SSL_TICKET 1
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_TIMEOUT
|
|
#define ME_GOAHEAD_SSL_TIMEOUT 86400
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_VERIFY
|
|
#define ME_GOAHEAD_SSL_VERIFY 0
|
|
#endif
|
|
#ifndef ME_GOAHEAD_SSL_VERIFY_ISSUER
|
|
#define ME_GOAHEAD_SSL_VERIFY_ISSUER 0
|
|
#endif
|
|
|
|
/**
|
|
Open the ssl module
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int sslOpen(void);
|
|
|
|
/**
|
|
Close the ssl module
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void sslClose(void);
|
|
|
|
/**
|
|
Free a ssl connection associated with a request
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void sslFree(Webs *wp);
|
|
|
|
/**
|
|
Upgrade a request connection to utilize SSL
|
|
@description This routine is invoked on a connection received on a secure listening socket
|
|
@param wp Webs request object
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int sslUpgrade(Webs *wp);
|
|
|
|
/**
|
|
Read data from a secure socket
|
|
@param wp Webs request object
|
|
@param buf Buffer into which to read data
|
|
@param len Size of buf
|
|
@return Count of bytes read if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize sslRead(Webs *wp, void *buf, ssize len);
|
|
|
|
/**
|
|
WRite data to a secure socket
|
|
@param wp Webs request object
|
|
@param buf Buffer from which to write data
|
|
@param len Size of buf
|
|
@return Count of bytes written if successful, otherwise -1.
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
PUBLIC ssize sslWrite(Webs *wp, void *buf, ssize len);
|
|
#endif /* ME_COM_SSL */
|
|
|
|
/*************************************** Route *********************************/
|
|
/**
|
|
Callback to prompt the user for their password
|
|
@param wp Webs request object
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef void (*WebsAskLogin)(Webs *wp);
|
|
|
|
/**
|
|
Callback to verify the username and password
|
|
@param wp Webs request object
|
|
@return True if the password is verified
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef bool (*WebsVerify)(Webs *wp);
|
|
|
|
/**
|
|
Callback to parse authentication details submitted with the web request
|
|
@param wp Webs request object
|
|
@return True if the details can be parsed
|
|
@ingroup Webs
|
|
@stability Stable
|
|
*/
|
|
typedef bool (*WebsParseAuth)(Webs *wp);
|
|
|
|
/**
|
|
Request route structure
|
|
@defgroup WebsRoute WebsRoute
|
|
*/
|
|
typedef struct WebsRoute {
|
|
char *prefix; /**< Route path prefix */
|
|
ssize prefixLen; /**< Prefix length */
|
|
char *dir; /**< Filesystem base directory for route documents */
|
|
char *protocol; /**< HTTP protocol to use for this route */
|
|
char *authType; /**< Authentication type */
|
|
WebsHandler *handler; /**< Request handler to service requests */
|
|
WebsHash abilities; /**< Required user abilities */
|
|
WebsHash extensions; /**< Permissible URI extensions */
|
|
WebsHash redirects; /**< Response redirections */
|
|
WebsHash methods; /**< Supported HTTP methods */
|
|
WebsAskLogin askLogin; /**< Route path prefix */
|
|
WebsParseAuth parseAuth; /**< Parse authentication details callback*/
|
|
WebsVerify verify; /**< Verify password callback */
|
|
int flags; /**< Route control flags */
|
|
} WebsRoute;
|
|
|
|
/**
|
|
Add a route to the routing tables
|
|
@param uri Matching URI prefix
|
|
@param handler Request handler to service routed requests
|
|
@param pos Position 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.
|
|
@return A route object
|
|
@ingroup WebsRoute
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsRoute *websAddRoute(cchar *uri, cchar *handler, int pos);
|
|
|
|
/**
|
|
Close the route module
|
|
@ingroup WebsRoute
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websCloseRoute(void);
|
|
|
|
/**
|
|
Load routing tables from the specified filename
|
|
@param path Route configuration filename
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsRoute
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websLoad(cchar *path);
|
|
|
|
/**
|
|
Open the routing module
|
|
@ingroup WebsRoute
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websOpenRoute(void);
|
|
|
|
/**
|
|
Remove a route from the routing tables
|
|
@param uri Matching URI prefix
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsRoute
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websRemoveRoute(cchar *uri);
|
|
|
|
/**
|
|
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.
|
|
This routine is called internally by the request pipeline.
|
|
@param wp Webs request object
|
|
@ingroup WebsRoute
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websRouteRequest(Webs *wp);
|
|
|
|
/**
|
|
Run a request handler
|
|
@description This routine will run the handler and route selected by #websRouteRequest.
|
|
This routine is called internally by the request pipeline.
|
|
@param wp Webs request object
|
|
@return True if the handler serviced the request. Return false to test other routes to handle this request.
|
|
This is for legacy handlers that do not have a match callback.
|
|
@ingroup WebsRoute
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websRunRequest(Webs *wp);
|
|
|
|
/**
|
|
Configure a route by adding matching criteria
|
|
@param route Route to modify
|
|
@param dir Set the route documents directory filename
|
|
@param protocol Set the matching HTTP protocol (http or https)
|
|
@param methods Hash of permissible HTTP methods. (GET, HEAD, POST, PUT)
|
|
@param extensions Hash of permissible URI filename extensions.
|
|
@param abilities Required user abilities. The user must be authenticated.
|
|
@param abilities Required user abilities. If abilities are required, the user must be authenticated.
|
|
@param redirects Set of applicable response redirections when completing the request.
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsRoute
|
|
@stability Evolving
|
|
*/
|
|
PUBLIC int websSetRouteMatch(WebsRoute *route, cchar *dir, cchar *protocol, WebsHash methods, WebsHash extensions,
|
|
WebsHash abilities, WebsHash redirects);
|
|
|
|
/**
|
|
Set route authentication scheme
|
|
@param route Route to modify
|
|
@param authType Set to "basic", "digest" or "form".
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsRoute
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websSetRouteAuth(WebsRoute *route, cchar *authType);
|
|
|
|
/*************************************** Auth **********************************/
|
|
#if ME_GOAHEAD_AUTH
|
|
|
|
#define WEBS_USIZE 128 /* Size of realm:username */
|
|
|
|
/**
|
|
GoAhead Authentication
|
|
@defgroup WebsAuth WebsAuth
|
|
*/
|
|
/**
|
|
User definition structure
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsUser {
|
|
char *name; /**< User name */
|
|
char *password; /**< User password (encrypted) */
|
|
char *roles; /**< User roles */
|
|
WebsHash abilities; /**< Resolved user abilities */
|
|
} WebsUser;
|
|
|
|
/**
|
|
Role definition structure
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
typedef struct WebsRole {
|
|
WebsHash abilities; /**< Resolved role abilities */
|
|
} WebsRole;
|
|
|
|
/**
|
|
Add a role
|
|
@description The role is added to the list of roles
|
|
@param role Role name
|
|
@param abilities Hash of abilities for the role
|
|
@return The allocated role.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsRole *websAddRole(cchar *role, WebsHash abilities);
|
|
|
|
/**
|
|
Add a user
|
|
@description The user is added to the list of users
|
|
@param username User name
|
|
@param password User password (encrypted)
|
|
@param roles Space separated list of roles. This may also contain abilities.
|
|
@return User object.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsUser *websAddUser(cchar *username, cchar *password, cchar *roles);
|
|
|
|
/**
|
|
Authenticate a user
|
|
@description The user is authenticated if required by the selected request route.
|
|
@param wp Webs request object
|
|
@return True if the route does not require authentication or the user is authenticated successfully.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websAuthenticate(Webs *wp);
|
|
|
|
/**
|
|
Test if a user possesses the required ability
|
|
@param wp Webs request object
|
|
@param ability Set of required abilities.
|
|
@return True if the user has the required ability.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websCan(Webs *wp, WebsHash ability);
|
|
|
|
/**
|
|
Close the authentication module
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websCloseAuth(void);
|
|
|
|
/**
|
|
Compute the abilities for all users by resolving roles into abilities
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websComputeAllUserAbilities(void);
|
|
|
|
/**
|
|
Set the password store verify callback
|
|
@return verify WebsVerify callback function
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsVerify websGetPasswordStoreVerify(void);
|
|
|
|
/**
|
|
Get the roles hash
|
|
@return The roles hash object
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsHash websGetRoles(void);
|
|
|
|
/**
|
|
Get the users hash
|
|
@return The users hash object
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsHash websGetUsers(void);
|
|
|
|
/**
|
|
Login a user by verifying the login credentials.
|
|
@description This may be called by handlers to manually authenticate a user.
|
|
@param wp Webs request object
|
|
@param username User name
|
|
@param password User password (encrypted)
|
|
@return True if the user can be authenticated.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websLoginUser(Webs *wp, cchar *username, cchar *password);
|
|
|
|
/**
|
|
Logout a user and remove the user login session.
|
|
@param wp Webs request object
|
|
@return True if successful.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websLogoutUser(Webs *wp);
|
|
|
|
/**
|
|
Lookup if a user exists
|
|
@param username User name to search for
|
|
@return User object or null if the user cannot be found
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsUser *websLookupUser(cchar *username);
|
|
|
|
/**
|
|
Remove a role from the system
|
|
@param role Role name
|
|
@return Zero if successful, otherwise -1
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websRemoveRole(cchar *role);
|
|
|
|
/**
|
|
Remove a user from the system
|
|
@param name User name
|
|
@return Zero if successful, otherwise -1
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websRemoveUser(cchar *name);
|
|
|
|
/**
|
|
Open the authentication module
|
|
@param minimal Reserved. Set to zero.
|
|
@return True if the user has the required ability.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websOpenAuth(int minimal);
|
|
|
|
/**
|
|
Set the password store verify callback
|
|
@param verify WebsVerify callback function
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websSetPasswordStoreVerify(WebsVerify verify);
|
|
|
|
/**
|
|
Set a password for the user
|
|
@param username User name
|
|
@param password Null terminated password string
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websSetUserPassword(cchar *username, cchar *password);
|
|
|
|
|
|
/**
|
|
Define the set of roles for a user
|
|
@param username User name
|
|
@param roles Space separated list of roles or abilities
|
|
@return Zero if successful, otherwise -1.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websSetUserRoles(cchar *username, cchar *roles);
|
|
|
|
/**
|
|
User password verification routine from a custom password back-end store.
|
|
@param wp Webs request object
|
|
@return True if the user password verifies.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websVerifyPasswordFromCustom(Webs *wp);
|
|
|
|
/**
|
|
User password verification routine from auth.txt
|
|
@param wp Webs request object
|
|
@return True if the user password verifies.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websVerifyPasswordFromFile(Webs *wp);
|
|
|
|
#if ME_COMPILER_HAS_PAM
|
|
/**
|
|
Verify a password using the system PAM password database.
|
|
@param wp Webs request object
|
|
@return True if the user password verifies.
|
|
@ingroup WebsAuth
|
|
@stability Stable
|
|
*/
|
|
PUBLIC bool websVerifyPasswordFromPam(Webs *wp);
|
|
#endif
|
|
|
|
#endif /* ME_GOAHEAD_AUTH */
|
|
/************************************** Sessions *******************************/
|
|
/**
|
|
Session state storage
|
|
@defgroup WebsSession WebsSession
|
|
*/
|
|
typedef struct WebsSession {
|
|
char *id; /**< Session ID key */
|
|
int lifespan; /**< Session inactivity timeout (secs) */
|
|
WebsTime expires; /**< When the session expires */
|
|
WebsHash cache; /**< Cache of session variables */
|
|
} WebsSession;
|
|
|
|
/**
|
|
Test if a user possesses the required ability
|
|
@param wp Webs request object
|
|
@param id Session ID to use. Set to null to allocate a new session ID.
|
|
@param lifespan Lifespan of the session in seconds.
|
|
@return Allocated session object
|
|
@ingroup WebsSession
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsSession *websAllocSession(Webs *wp, cchar *id, int lifespan);
|
|
|
|
/**
|
|
Test if a user possesses the required ability
|
|
@param wp Webs request object
|
|
@return Allocated session object
|
|
@ingroup WebsSession
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsSession *websCreateSession(Webs *wp);
|
|
|
|
/**
|
|
Destroy the webs session object
|
|
@description Useful to be called as part of the user logout process
|
|
@param wp Webs request object
|
|
@ingroup WebsSession
|
|
@stability Prototype
|
|
*/
|
|
PUBLIC void websDestroySession(Webs *wp);
|
|
|
|
/**
|
|
Get the session ID
|
|
@param wp Webs request object
|
|
@return The session ID if session state storage is defined for this request. Caller must free.
|
|
@ingroup WebsSession
|
|
@stability Stable
|
|
*/
|
|
PUBLIC char *websGetSessionID(Webs *wp);
|
|
|
|
/**
|
|
Get the session state object for the current request
|
|
@param wp Webs request object
|
|
@param create Set to true to create a new session if one does not already exist.
|
|
@return Session object
|
|
@ingroup WebsSession
|
|
@stability Stable
|
|
*/
|
|
PUBLIC WebsSession *websGetSession(Webs *wp, int create);
|
|
|
|
/**
|
|
Get a session variable
|
|
@param wp Webs request object
|
|
@param name Session variable name
|
|
@param defaultValue Default value to return if the variable does not exist
|
|
@return Session variable value or default value if it does not exist
|
|
@ingroup WebsSession
|
|
@stability Stable
|
|
*/
|
|
PUBLIC cchar *websGetSessionVar(Webs *wp, cchar *name, cchar *defaultValue);
|
|
|
|
/**
|
|
Remove a session variable
|
|
@param wp Webs request object
|
|
@param name Session variable name
|
|
@ingroup WebsSession
|
|
@stability Stable
|
|
*/
|
|
PUBLIC void websRemoveSessionVar(Webs *wp, cchar *name);
|
|
|
|
/**
|
|
Set a session variable name value
|
|
@param wp Webs request object
|
|
@param name Session variable name
|
|
@param value Value to set the variable to
|
|
@return Zero if successful, otherwise -1
|
|
@ingroup WebsSession
|
|
@stability Stable
|
|
*/
|
|
PUBLIC int websSetSessionVar(Webs *wp, cchar *name, cchar *value);
|
|
|
|
/************************************ Legacy **********************************/
|
|
/*
|
|
Legacy mappings for pre GoAhead 3.X applications
|
|
This is a list of the name changes from GoAhead 2.X to GoAhead 3.x
|
|
To maximize forward compatibility, It is best to not use ME_GOAHEAD_LEGACY except as
|
|
a transitional compilation aid.
|
|
*/
|
|
#if ME_GOAHEAD_LEGACY
|
|
#define B_L 0
|
|
#define a_assert assert
|
|
#define balloc walloc
|
|
#define bclose wcloseAlloc
|
|
#define bfree(loc, p) wfree(p)
|
|
#define bfreeSafe(loc, p) wfree(p)
|
|
#define bopen wopenAlloc
|
|
#define brealloc wrealloc
|
|
#define bstrdup sclone
|
|
#define emfReschedCallback websRestartEvent
|
|
#define emfSchedCallback websStartEvent
|
|
#define emfSchedProc WebsEventProc
|
|
#define emfSchedProcess websRunEvents
|
|
#define emfUnschedCallback websStopEvent
|
|
#define fmtStatic fmt
|
|
#define gassert assert
|
|
#define galloc walloc
|
|
#define gallocEntry wallocObject
|
|
#define gfree wfree
|
|
#define gFree wfreeHandle
|
|
#define grealloc wrealloc
|
|
#define gaccess access
|
|
#define gasctime asctime
|
|
#define gatoi atoi
|
|
#define gchmod chmod
|
|
#define wclose close
|
|
#define wclosedir closedir
|
|
#define gcreat creat
|
|
#define gctime ctime
|
|
#define gexecvp execvp
|
|
#define gfgets fgets
|
|
#define gfindclose _findclose
|
|
#define gfinddata_t _finddata_t
|
|
#define gfindfirst _findfirst
|
|
#define gfindnext _findnext
|
|
#define gfopen fopen
|
|
#define gfprintf fprintf
|
|
#define gfputs fputs
|
|
#define gfscanf fscanf
|
|
#define ggetcwd getcwd
|
|
#define ggetenv getenv
|
|
#define ggets gets
|
|
#define gisalnum isalnum
|
|
#define gisalpha isalpha
|
|
#define gisdigit isdigit
|
|
#define gislower islower
|
|
#define gisspace isspace
|
|
#define gisupper isupper
|
|
#define gisxdigit isxdigit
|
|
#define gloadModule loadModule
|
|
#define glseek lseek
|
|
#define gopendir opendir
|
|
#define gprintf printf
|
|
#define gread read
|
|
#define greaddir readdir
|
|
#define gremove remove
|
|
#define grename rename
|
|
#define gsprintf sprintf
|
|
#define gsscanf sscanf
|
|
#define gstat stat
|
|
#define gstrcat strcat
|
|
#define gstrchr strchr
|
|
#define gstrcmp strcmp
|
|
#define gstrcpy strcpy
|
|
#define gstrcspn strcspn
|
|
#define gstricmp strcmpci
|
|
#define gstritoa stritoa
|
|
#define gstrlen strlen
|
|
#define gstrlower strlower
|
|
#define gstrncat strncat
|
|
#define gstrncmp strncmp
|
|
#define gstrncpy strncpy
|
|
#define gstrnlen strnlen
|
|
#define gstrnset strnset
|
|
#define gstrrchr strrchr
|
|
#define gstrspn strspn
|
|
#define gstrstr strstr
|
|
#define gstrtok strtok
|
|
#define gstrtol strtol
|
|
#define gstrupper strupper
|
|
#define gtempnam websTempFile
|
|
#define gtolower tolower
|
|
#define gtoupper toupper
|
|
#define gunlink unlink
|
|
#define gvsprintf vsprintf
|
|
#define gwrite write
|
|
#define hAlloc wallocHandle
|
|
#define hAllocEntry wallocObject
|
|
#define hFree wfreeHandle
|
|
#define stritoa gstritoa
|
|
#define strlower gstrlower
|
|
#define strupper gstrupper
|
|
#define websAspDefine websDefineJst
|
|
#define websAspOpen websJstOpen
|
|
#define websAspRequest websJstRequest
|
|
#define websFormDefine websDefineAction
|
|
#define websGetDefaultDir websGetDocuments
|
|
#define websGetDefaultPage websGetIndex
|
|
|
|
#define websGetRequestDir(wp) wp->dir
|
|
#define websGetRequestIpAddr(wp) wp->ipaddr
|
|
#define websGetRequestFilename(wp) wp->filename
|
|
#define websGetRequestFlags(wp) wp->flags
|
|
#define websGetRequestLpath(wp) wp->filename
|
|
#define websGetRequestPath(wp) wp->path
|
|
#define websGetRequestPassword(wp) wp->password
|
|
#define websGetRequestUserName(wp) wp->username
|
|
#define websGetRequestWritten(wp) wp->written
|
|
|
|
#define websSetDefaultDir websSetDocuments
|
|
#define websSetDefaultPage websSetIndex
|
|
#define websSetRequestLpath websSetRequestFilename
|
|
#define websSetRequestWritten(wp, nbytes) if (1) { wp->written = nbytes; } else {}
|
|
#define websTimeoutCancel websCancelTimeout
|
|
#define websWriteDataNonBlock websWriteRaw
|
|
|
|
#define ringqOpen bufCreate
|
|
#define ringqClose bufFree
|
|
#define ringqLen bufLen
|
|
#define ringqPutc bufPutc
|
|
#define ringqInsertc bufInsertc
|
|
#define ringqPutStr bufPutStr
|
|
#define ringqGetc bufGetc
|
|
#define ringqGrow bufGrow
|
|
#define ringqPutBlk bufPutBlk
|
|
#define ringqPutBlkMax bufRoom
|
|
#define ringqPutBlkAdj bufAdjustEnd
|
|
#define ringqGetBlk bufGetBlk
|
|
#define ringqGetBlkMax bufGetBlkMax
|
|
#define ringqGetBlkAdj bufAdjustSTart
|
|
#define ringqFlush bufFlush
|
|
#define ringqCompact bufCompact
|
|
#define ringqReset bufReset
|
|
#define ringqAddNull bufAddNull
|
|
|
|
#define symCreate hashCreate
|
|
#define symClose hashFree
|
|
#define symLookup hashLookup
|
|
#define symEnter hashEnter
|
|
#define symDelete hashDelete
|
|
#define symWalk hashWalk
|
|
#define symFirst hashFirst
|
|
#define symNext hashNext
|
|
|
|
typedef Webs *webs_t;
|
|
typedef Webs WebsRec;
|
|
typedef Webs websType;
|
|
typedef WebsBuf ringq_t;
|
|
typedef WebsError websErrorType;
|
|
typedef WebsProc WebsFormProc;
|
|
typedef int (*WebsLegacyHandlerProc)(Webs *wp, char *prefix, char *dir, int flags);
|
|
typedef SocketHandler socketHandler_t;
|
|
typedef SocketAccept socketAccept_t;
|
|
typedef WebsType vtype_t;
|
|
|
|
typedef WebsHash sym_fd_t;
|
|
typedef WebsKey sym_t;
|
|
typedef WebsMime websMimeType;
|
|
typedef WebsSocket socket_t;
|
|
typedef WebsStat gstat_t;
|
|
typedef WebsValue value_t;
|
|
|
|
PUBLIC int fmtValloc(char **s, int n, cchar *fmt, va_list arg);
|
|
PUBLIC int fmtAlloc(char **s, int n, cchar *fmt, ...);
|
|
PUBLIC void websFooter(Webs *wp);
|
|
PUBLIC void websHeader(Webs *wp);
|
|
PUBLIC int websPublish(cchar *prefix, cchar *path);
|
|
PUBLIC void websSetRequestFilename(Webs *wp, cchar *filename);
|
|
PUBLIC int websUrlHandlerDefine(cchar *prefix, cchar *dir, int arg, WebsLegacyHandlerProc handler, int flags);
|
|
|
|
#if ME_ROM
|
|
typedef WebsRomIndex websRomIndexType;
|
|
#endif
|
|
#endif
|
|
|
|
#if ME_CUSTOMIZE
|
|
#include "customize.h"
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
#endif /* _h_GOAHEAD */
|
|
|
|
/*
|
|
Copyright (c) Embedthis Software. All Rights Reserved.
|
|
This software is distributed under commercial and open source licenses.
|
|
You may use the Embedthis GoAhead open source license or you may acquire
|
|
a commercial license from Embedthis Software. You agree to be fully bound
|
|
by the terms of either license. Consult the LICENSE.md distributed with
|
|
this software for full details and other copyrights.
|
|
*/
|