See Also
Quick Nav
Appweb Native API
Components
MaAlias | Aliases. |
MaAuth | Authorization The MaAuth struct is the foundation authorization object and is used as base class by MaDirectory and MaLocation. |
MaConfigState | Current config parse state. |
MaConn | Http Connections. |
MaDir | Directory Control. |
MaFilter | Filter Stages. |
MaGroup | Group Authorization. |
MaHost | Host Object A Host object represents a single listening HTTP connection endpoint. |
MaHostAddress | Host Address Mapping. |
MaHttp | Http Service. |
MaLimits | Server limits. |
MaListen | Listen endpoint. |
MaLocation | Location Control. |
MaMimeType | Mime Type hash table entry (the URL extension is the key). |
MaRange | Content range structure. |
MaRequest | Http Requests. |
MaServer | Http Server Control An application may have any number of HTTP servers, each managed by an instance of the Server class. |
MaUploadFile | Upload File Each uploaded file has an MaUploadedFile entry. |
MaUser | User Authorization File based authorization backend. |
Functions
MaHttp* | maCreateHttp(MprCtx ctx) |
Create the MaHttp object. | |
int | maSetHttpGroup(MaHttp *http, cchar *group) |
Set the Http Group. | |
int | maSetHttpUser(MaHttp *http, cchar *user) |
Set the Http User. | |
int | maStartHttp(MaHttp *http) |
Start Http services. | |
int | maStopHttp(MaHttp *http) |
Stop Http services. | |
void | maAddVars(MprHashTable *table, cchar *buf, int len) |
Add query and post form variables. | |
int | maCompareFormVar(MaConn *conn, cchar *var, cchar *value) |
Compare a form variable. | |
cchar* | maGetCookies(MaConn *conn) |
Get the cookies. | |
cchar* | maGetFormVar(MaConn *conn, cchar *var, cchar *defaultValue) |
Get a form variable. | |
int | maGetIntFormVar(MaConn *conn, cchar *var, int defaultValue) |
Get a form variable as an integer. | |
cchar* | maGetQueryString(MaConn *conn) |
Get the request query string. | |
void | maSetFormVar(MaConn *conn, cchar *var, cchar *value) |
Set a form variable value. | |
void | maSetIntFormVar(MaConn *conn, cchar *var, int value) |
Set a form variable value. | |
int | maTestFormVar(MaConn *conn, cchar *var) |
Test if a form variable is defined. | |
int | maConfigureServer(MprCtx ctx, MaHttp *http, MaServer *server, cchar *configFile, cchar *ipAddr, int port, cchar *documentRoot) |
Configure a web server. | |
MaServer* | maCreateServer(MaHttp *http, cchar *name, cchar *root, cchar *ipAddr, int port) |
Create a MaServer object. | |
MaHttp* | maCreateWebServer(cchar *configFile) |
Create a web server. | |
void | maLoadStaticModules(MaHttp *http) |
Load static modules. | |
int | maRunSimpleWebServer(cchar *ipAddress, int port, cchar *docRoot) |
Create and run a simple web server listening on a single IP address. | |
int | maRunWebServer(cchar *configFile) |
Create and run a web server based on a configuration file. | |
int | maServiceWebServer(MaHttp *http) |
Service a web server. |
Typedefs
Defines
#define | _h_APPWEB_MONITOR 1 |
appwebMonitor.h - Monitor Header. | |
#define | _h_HTTP_TUNE 1 |
httpTune.h - Tunable parameters for the Embedthis Http Web Server. | |
#define | MA_BUFSIZE (4 * 1024) |
Default I/O buffer size. | |
#define | MA_CGI_PERIOD 20 |
CGI poll period (only for windows). | |
#define | MA_CGI_TIMEOUT 4000 |
Time to wait to reap exit status. | |
#define | MA_CHUNK_DATA 2 |
Start of chunk data. | |
#define | MA_CHUNK_EOF 3 |
End of last chunk. | |
#define | MA_CHUNK_START 1 |
Start of a new chunk. | |
#define | MA_CONN_CASE_INSENSITIVE 0x2 |
System case-insensitive for file matches. | |
#define | MA_CONN_CLEAN_MASK 0x1 |
Mask to clear flags after a request completes. | |
#define | MA_CONN_CLOSE 0x1 |
Connection needs to be closed. | |
#define | MA_CONN_PIPE_CREATED 0x4 |
Request pipeline created. | |
#define | MA_DEFAULT_MAX_THREADS 10 |
Default number of threads. | |
#define | MA_KEEP_TIMEOUT 60000 |
Keep connection alive timeout. | |
#define | MA_LOC_APP 0x2 |
Location defines an application. | |
#define | MA_LOC_APP_DIR 0x4 |
Location defines a directory of applications. | |
#define | MA_LOC_AUTO_SESSION 0x8 |
Auto create sessions in this location. | |
#define | MA_LOC_BROWSER 0x10 |
Send errors back to the browser for this location. | |
#define | MA_LOC_PUT_DELETE 0x20 |
Support PUT|DELETE. | |
#define | MA_MAX_ACCESS_LOG (20971520) |
Access file size (20 MB). | |
#define | MA_MAX_IOVEC 16 |
Number of fragments in a single socket write. | |
#define | MA_MAX_KEEP_ALIVE 100 |
Default requests per TCP conn. | |
#define | MA_MAX_PASS 64 |
Size of password. | |
#define | MA_MAX_QUEUE 2 |
Number of queue types. | |
#define | MA_MAX_SECRET 32 |
Number of random bytes to use. | |
#define | MA_MAX_STAGE_BUFFER (4 * 1024) |
Max buffer for any stage. | |
#define | MA_MIN_PACKET 512 |
Minimum packet size. | |
#define | MA_PACKET_DATA 0x4 |
Packet contains actual content data. | |
#define | MA_PACKET_END 0x8 |
End of stream packet. | |
#define | MA_PACKET_HEADER 0x1 |
Packet contains HTTP headers. | |
#define | MA_PACKET_RANGE 0x2 |
Packet is a range boundary packet. | |
#define | MA_QUEUE_ALL 0x8 |
Queue has all the data there is and will be. | |
#define | MA_QUEUE_DISABLED 0x2 |
Queue's service routine is disabled. | |
#define | MA_QUEUE_EOF 0x40 |
Queue at end of data. | |
#define | MA_QUEUE_FULL 0x4 |
Queue is full. | |
#define | MA_QUEUE_OPEN 0x1 |
Queue's open routine has been called. | |
#define | MA_QUEUE_RECEIVE 1 |
Receive (read from client) queue. | |
#define | MA_QUEUE_SEND 0 |
Send (transmit to client) queue. | |
#define | MA_QUEUE_SERVICED 0x10 |
Queue has been serviced at least once. | |
#define | MA_QUEUE_STARTED 0x20 |
Queue's start routine has been called. | |
#define | MA_REQ_CHUNKED 0x4 |
Content is chunk encoded. | |
#define | MA_REQ_CREATE_ENV 0x1 |
Must create env for this request. | |
#define | MA_REQ_DELETE 0x1 |
DELETE method. | |
#define | MA_REQ_GET 0x2 |
GET method. | |
#define | MA_REQ_HEAD 0x4 |
HEAD method. | |
#define | MA_REQ_IF_MODIFIED 0x2 |
If-[un]modified-since supplied. | |
#define | MA_REQ_MASK 0x7F |
Method mask. | |
#define | MA_REQ_MEM ((1 * 1024 * 1024) - MPR_HEAP_OVERHEAD) |
Initial virt memory arena size. | |
#define | MA_REQ_MEM 1 |
Initial virt memory arena size. | |
#define | MA_REQ_OPTIONS 0x8 |
OPTIONS method. | |
#define | MA_REQ_POST 0x10 |
Post method. | |
#define | MA_REQ_PUT 0x20 |
PUT method. | |
#define | MA_REQ_TRACE 0x40 |
TRACE method. | |
#define | MA_REQ_UPLOADING 0x8 |
Content contains upload files. | |
#define | MA_RESP_DONT_CACHE 0x1 |
Add no-cache to the response. | |
#define | MA_RESP_DONT_FINISH 0x2 |
Don't auto finish the request. | |
#define | MA_RESP_HEADERS_CREATED 0x8 |
Response headers have been created. | |
#define | MA_RESP_NO_BODY 0x4 |
No respose body, only return headers to client. | |
#define | MA_STAGE_ALL MA_REQ_MASK |
Mask for all methods. | |
#define | MA_STAGE_AUTO_DIR 0x100000 |
Want auto directory redirection. | |
#define | MA_STAGE_CONNECTOR 0x1000 |
Stage is a connector. | |
#define | MA_STAGE_DELETE MA_REQ_DELETE |
Support DELETE requests. | |
#define | MA_STAGE_ENV_VARS 0x20000 |
Create CGI style environment variables table. | |
#define | MA_STAGE_FILTER 0x4000 |
Stage is a filter. | |
#define | MA_STAGE_GET MA_REQ_GET |
Support GET requests. | |
#define | MA_STAGE_HANDLER 0x2000 |
Stage is a handler. | |
#define | MA_STAGE_HEAD MA_REQ_HEAD |
Support HEAD requests. | |
#define | MA_STAGE_MISSING_EXT 0x400000 |
Handle URIs with missing extensions. | |
#define | MA_STAGE_MODULE 0x8000 |
Stage is a filter. | |
#define | MA_STAGE_OPTIONS MA_REQ_OPTIONS |
Support OPTIONS requests. | |
#define | MA_STAGE_PATH_INFO 0x80000 |
Always do path info processing. | |
#define | MA_STAGE_POST MA_REQ_POST |
Support POST requests. | |
#define | MA_STAGE_PUT MA_REQ_PUT |
Support PUT requests. | |
#define | MA_STAGE_TRACE MA_REQ_TRACE |
Support TRACE requests. | |
#define | MA_STAGE_UNLOADED 0x800000 |
Stage library has been unloaded. | |
#define | MA_STAGE_VARS 0x10000 |
Create query and form variables table. | |
#define | MA_STAGE_VERIFY_ENTITY 0x200000 |
Verify the request entity exists. | |
#define | MA_STAGE_VIRTUAL 0x40000 |
Handler serves virtual resources not the physical file system. | |
#define | MA_TIMER_PERIOD 1000 |
Timer checks ever 1 second. |
MaAlias
Aliases.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
char * filename Alias to a physical path name. char * prefix Original URI prefix. int prefixLen Prefix length. char * uri Redirect to a uri.
MaAuth
Authorization The MaAuth struct is the foundation authorization object and is used as base class by MaDirectory and MaLocation.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MaConfigState
Current config parse state.
- API Stability:
- Evolving.
- See Also:
MaConn
Http Connections.
- Description:
- The MaConn object represents a TCP/IP connection to the client. A connection object is created for each socket connection initiated by the client. One MaConn object may service many Http requests due to HTTP/1.1 keep-alive.
- API Stability:
- Evolving.
- See Also:
- MaQueue, MaRequest, MaResponse, MaStage
- Fields:
-
MaHostAddress * address Host address structure for this connection. MprHeap * arena Connection memory arena. int canProceed State machine should continue to process the request. int connectionFailed Request failed and connection protocol is compromised. void * data Connection data for stages. int dedicated Dedicate the current thread to the request. int disconnected Connection is disconnected. Abandon current request. int eventMask Desired events anded with this mask. MprTime expire When the connection should expire. int flags Connection flags. MaHost * host Owning host for this request. MaHttp * http Http handle. MaPacket * input Header packet. int keepAliveCount Count of remaining keep alive requests for this connection. MprMutex * mutex Optional multi-thread sync. MaHost * originalHost Owning host for this connection. May be changed by Host header. int protocol HTTP protocol version 0 == HTTP/1.0, 1 == HTTP/1.1. char * remoteIpAddr Remote client IP address (REMOTE_ADDR). int remotePort Remote client IP port number. struct MaRequest * request Request object. int requestFailed Request failed. Abbreviate request processing. struct MaResponse * response Response object. int seqno Unique connection sequence number. struct MaQueue serviceq List of queues that require service for request pipeline. MprSocket * sock Underlying socket handle. MprTime started When the connection started. int state Connection state. MprTime time Cached current time. int timeout Timeout period in msec. int trace Current request should be traced.
MaDir
Directory Control.
- API Stability:
- Evolving.
- See Also:
MaFilter
Filter Stages.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MaGroup
Group Authorization.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MaHost
Host Object A Host object represents a single listening HTTP connection endpoint.
- API Stability:
- Evolving.
- See Also:
MaHostAddress
Host Address Mapping.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
int flags Mapping flags. char * ipAddr IP Address for this endpoint. int port Port for this endpoint. MprList * vhosts Vhosts using this address.
MaHttp
Http Service.
- Description:
- There is one instance of MaHttp per application. It manages a list of HTTP servers running in the application.
- API Stability:
- Evolving.
- See Also:
- maCreateHttp, maStartHttp, maStopHttp
- Fields:
-
struct MaStage * authFilter Authorization filter (digest and basic). struct MaStage * cgiHandler CGI handler. struct MaStage * chunkFilter Chunked transfer encoding filter. struct MaServer * defaultServer Default web server object. struct MaStage * dirHandler Directory listing handler. struct MaStage * egiHandler Embedded Gateway Interface (EGI) handler. struct MaStage * ejsHandler Ejscript Web Framework handler. struct MaStage * fileHandler Static file handler. int gid Group Id. char * groupname Http server group name. MaLimits limits Security and resource limits. MaListenCallback listenCallback Invoked when creating listeners. MprMutex * mutex Multi-thread sync. struct MaStage * netConnector Network connector. struct MaStage * passHandler Pass through handler. struct MaStage * phpHandler PHP handler. struct MaStage * rangeFilter Ranged requests filter. struct MaStage * sendConnector Send file connector. MprList * servers List of web servers objects. MprHashTable * stages Hash table of stages. int uid User Id. char * username Http server user name.
Create the MaHttp object.
- Description:
- The Appweb library uses a singleton MaHttp object to manage multiple embedded web servers.
- Parameters:
-
ctx Any memory context object returned by mprAlloc.
- Returns:
- A MaHttp object. Use mprFree to close and release.
- See Also:
- MaHttp, maStartHttp, maStopHttp
Set the Http Group.
- Description:
- Define the group name under which to run the Appweb service.
- Parameters:
-
http MaHttp object created via maCreateHttp. group Group name. Must be defined in the system group file.
- Returns:
- Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
- See Also:
- MaHttp, maCreateHttp, maStartHttp, maStopHttp
Set the Http User.
- Description:
- Define the user name under which to run the Appweb service.
- Parameters:
-
http MaHttp object created via maCreateHttp. user User name. Must be defined in the system password file.
- Returns:
- Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
- See Also:
- MaHttp, maCreateHttp, maStartHttp, maStopHttp
Start Http services.
- Description:
- This starts listening for requests on all configured servers.
- Parameters:
-
http MaHttp object created via maCreateHttp.
- Returns:
- Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
- See Also:
- MaHttp, maCreateHttp, maStopHttp
Stop Http services.
- Description:
- This stops listening for requests on all configured servers. Shutdown is somewhat graceful.
- Parameters:
-
http MaHttp object created via maCreateHttp.
- Returns:
- Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
- See Also:
- MaHttp, maCreateHttp, maStartHttp
MaLimits
Server limits.
- API Stability:
- Evolving.
- See Also:
MaListen
Listen endpoint.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
int flags Listen flags. char * ipAddr IP address on which to listen. int port Port number to listen on. struct MaServer * server Server owning this listening endpoint. MprSocket * sock Underlying socket. struct MprSsl * ssl SSL configuration.
MaLocation
Location Control.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MaAuth * auth Per location block authentication. int autoDelete Auto delete uploaded files. struct MaStage * connector Network connector. char * ejsPath EjsPath search path. MprHashTable * expires Expiry of content by mime type. MprHashTable * extensions Hash of handlers by extensions. int flags Location flags. struct MaStage * handler Set handler. void * handlerData Data reserved for the handler. MprList * handlers List of handlers for this location. MprList * inputStages Input stages. MprList * outputStages Output stages. struct MaLocation * parent Parent location. char * prefix Location prefix name. int prefixLen Length of the prefix name. int sessionTimeout Session timeout for this location. struct MprSsl * ssl SSL configuration. char * uploadDir Upload directory.
MaMimeType
Mime Type hash table entry (the URL extension is the key).
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MaRange
Content range structure.
- Range: 0, 49 First 50 bytes Range: -1, -50 Last 50 bytes Range: 1, -1 Skip first byte then select content to the end.
- API Stability:
- Evolving.
- See Also:
MaRequest
Http Requests.
- Description:
- Most of the APIs in the Request group still take a MaConn object as their first parameter. This is to make the API easier to remember - APIs take a connection object rather than a request or response object.
- API Stability:
- Evolving.
- See Also:
- MaConn, MaResponse, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar
- Fields:
-
Add query and post form variables.
- Description:
- Add new variables encoded in the supplied buffer.
- Parameters:
-
table MprHashTable Hash table to modify. buf Buffer containing www-urlencoded data. len Length of buf.
Compare a form variable.
- Description:
- Compare a form variable and return true if it exists and its value matches.
- Parameters:
-
conn MaConn connection object. var Name of the form variable. value Value to compare.
- Returns:
- True if the value matches.
Get the cookies.
- Description:
- Get the cookies defined in the current requeset.
- Parameters:
-
conn MaConn connection object.
- Returns:
- Return a string containing the cookies sent in the Http header of the last request.
Get a form variable.
- Description:
- Get the value of a named form variable. Form variables are define via www-urlencoded query or post data contained in the request.
- Parameters:
-
conn MaConn connection object. var Name of the form variable to retrieve. defaultValue Default value to return if the variable is not defined. Can be null.
- Returns:
- String containing the form variable's value. Caller should not free.
Get a form variable as an integer.
- Description:
- Get the value of a named form variable as an integer. Form variables are define via www-urlencoded query or post data contained in the request.
- Parameters:
-
conn MaConn connection object. var Name of the form variable to retrieve. defaultValue Default value to return if the variable is not defined. Can be null.
- Returns:
- Integer containing the form variable's value.
Get the request query string.
- Description:
- Get query string sent with the current request.
- Parameters:
-
conn MaConn connection object.
- Returns:
- String containing the request query string. Caller should not free.
Set a form variable value.
- Description:
- Set the value of a named form variable to a string value. Form variables are define via www-urlencoded query or post data contained in the request.
- Parameters:
-
conn MaConn connection object. var Name of the form variable to retrieve. value Default value to return if the variable is not defined. Can be null.
Set a form variable value.
- Description:
- Set the value of a named form variable to an integer value. Form variables are define via www-urlencoded query or post data contained in the request.
- Parameters:
-
conn MaConn connection object. var Name of the form variable to retrieve. value Default value to return if the variable is not defined. Can be null.
Test if a form variable is defined.
- Parameters:
-
conn MaConn connection object. var Name of the form variable to retrieve.
- Returns:
- True if the form variable is defined.
MaServer
Http Server Control An application may have any number of HTTP servers, each managed by an instance of the Server class.
- API Stability:
- Evolving.
- See Also:
- maConfigureServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer, maServiceWebServer
- Fields:
-
Configure a web server.
- Description:
- This will configure a web server based on either a configuration file or using the supplied IP address and port.
- Parameters:
-
ctx Any memory context object returned by mprAlloc. http MaHttp object created via maCreateHttp. server MaServer object created via maCreateServer. configFile File name of the Appweb configuration file (appweb.conf) that defines the web server configuration. ipAddr If using a config file, set to null. Otherwise, set to a host name or IP address. port If using a config file, set to -1. Otherwise, set to the port number to listen on. documentRoot If not using a config file, set this to the directory containing the web documents to serve.
- Returns:
- Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
Create a MaServer object.
- Description:
- Create new MaServer object. This routine creates a bare MaServer object, loads any required static modules and performs minimal configuration. To use the server object created, more configuration will be required before starting Http services. If you want a one-line embedding of Appweb, use maRunWebServer or maRunSimpleWebServer.
- Parameters:
-
http Http object returned from maCreateHttp. name Name of the web server. This name is used as the initial server name. root Server root directory. ipAddr If not-null, create and open a listening endpoint on this IP address. If you are configuring via a config file, use maConfigureServer and set ipAddr to null. port Port number to listen on. Set to -1 if you do not want to open a listening endpoint on ipAddr:port.
- Returns:
- MaServer A newly created MaServer object. Use mprFree to free and release.
Create a web server.
- Description:
- Create a web server configuration based on the supplied config file. Once created, the web server should be run by calling maServiceWebServer. Use this routine when you need access to the MaHttp object. If you want a one-line embedding of Appweb, use maRunWebServer or maRunSimpleWebServer.
- Parameters:
-
configFile File name of the Appweb configuration file (appweb.conf) that defines the web server configuration.
- Returns:
- MaHttp object.
Load static modules.
- Description:
- Load the statically configured modules, handlers, filters and connectors. The configure program can specify a static or shared build of Appweb. The maCreateServer routine will call maLoadStaticModules automatically. It should not be called by in user programs.
- Parameters:
-
http MaHttp object created via maCreateHttp.
Create and run a simple web server listening on a single IP address.
- Description:
- Create a simple web server without using a configuration file. The server is created to listen on the specified IP addresss and port. This routine provides is a one-line embedding of Appweb. If you want to use a config file, try the maRunWebServer instead. If you need more control, try maCreateWebServer which exposes the MaHttp object.
- Parameters:
-
ipAddress IP address on which to listen. Set to "0.0.0.0" to listen on all interfaces. port Port number to listen to. docRoot Directory containing the documents to serve.
- Returns:
- Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
Create and run a web server based on a configuration file.
- Description:
- Create a web server configuration based on the supplied config file. This routine provides is a one-line embedding of Appweb. If you don't want to use a config file, try the maRunSimpleWebServer instead. If you need more control, try maCreateWebServer which exposes the MaHttp object.
- Parameters:
-
configFile File name of the Appweb configuration file (appweb.conf) that defines the web server configuration.
- Returns:
- Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
Service a web server.
- Description:
- Run a web server configuration. This is will start http services via maStartHttp and will service incoming Http requests until instructed to exit. This is often used in conjunction with maCreateWebServer.
- Parameters:
-
http Http object created via maCreateWebServer or maCreateHttp.
- Returns:
- Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
MaUploadFile
Upload File Each uploaded file has an MaUploadedFile entry.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MaUser
User Authorization File based authorization backend.
- API Stability:
- Evolving.
- See Also: