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. |
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). |
MaPacket | Data packet. |
MaQueue | Queue Head. |
MaRange | Content range structure. |
MaRequest | Http Requests. |
MaResponse | Http Response. |
MaServer | Http Server Control An application may have any number of HTTP servers, each managed by an instance of the Server class. |
MaStage | Pipeline Stages. |
MaUploadFile | Upload File. |
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. | |
MaPacket* | maCreateDataPacket(struct MaConn *conn, int size) |
Create a data packet. | |
MaPacket* | maCreateEndPacket(struct MaConn *conn) |
Create an end packet. | |
MaPacket* | maCreateHeaderPacket(struct MaConn *conn) |
Create a response header packet. | |
MaPacket* | maCreatePacket(struct MaConn *conn, int size) |
Create a data packet. | |
int | maGetPacketLength(MaPacket *packet) |
Get the length of the packet data contents. | |
int | maJoinPacket(MaPacket *packet, MaPacket *other) |
Join tow packets. | |
MaPacket* | maSplitPacket(struct MaConn *conn, MaPacket *packet, int offset) |
Split a data packet. | |
void | maDisableQueue(MaQueue *q) |
Disable a queue. | |
void | maDiscardData(MaQueue *q, bool removePackets) |
Discard all data from the queue. | |
void | maEnableQueue(MaQueue *q) |
Enable a queue. | |
MaPacket* | maGet(MaQueue *q) |
Get the next packet from a queue. | |
int | maGetQueueRoom(MaQueue *q) |
Get the room in the queue. | |
bool | maIsQueueEmpty(MaQueue *q) |
Determine if the queue is empty. | |
void | maJoinForService(MaQueue *q, MaPacket *packet, bool serviceQ) |
Join a packet onto the service queue. | |
bool | maPacketTooBig(MaQueue *q, MaPacket *packet) |
Test if a packet is too big. | |
void | maPut(MaQueue *q, MaPacket *packet) |
Put a packet onto a queue. | |
void | maPutBack(MaQueue *q, MaPacket *packet) |
Put a packet back onto a queue. | |
void | maPutForService(MaQueue *q, MaPacket *packet, bool serviceQ) |
Put a packet onto the service queue. | |
void | maPutNext(MaQueue *q, MaPacket *packet) |
Put a packet onto the next queue. | |
void | maRemoveQueue(MaQueue *q) |
Remove a queue. | |
int | maResizePacket(MaQueue *q, MaPacket *packet, int size) |
Resize a packet. | |
void | maScheduleQueue(MaQueue *q) |
Schedule a queue. | |
void | maSendEndPacket(MaQueue *q) |
Send an end packet. | |
void | maSendPackets(MaQueue *q) |
Send all queued packets. | |
void | maServiceQueue(MaQueue *q) |
Service a queue. | |
bool | maWillNextQueueAccept(MaQueue *q, MaPacket *packet) |
Determine if the downstream queue will accept this packet. | |
int | maWrite(MaQueue *q, cchar *fmt, ...) |
Write a formatted string. | |
int | maWriteBlock(MaQueue *q, cchar *buf, int size, bool block) |
Write a block of data to the queue. | |
int | maWriteString(MaQueue *q, cchar *s) |
Write a string of data to the queue. | |
void | maAddFormVars(MaConn *conn, cchar *buf, int len) |
Add 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. | |
void | maDontCacheResponse(MaConn *conn) |
Dont cache the response. | |
void | maFailRequest(MaConn *conn, int code, cchar *fmt, ...) |
Fail a request. | |
void | maFillHeaders(MaConn *conn, MaPacket *packet) |
Create the response headers. | |
int | maFormatBody(MaConn *conn, cchar *title, cchar *fmt, ...) |
Format an alternate response body. | |
void | maRedirect(MaConn *conn, int code, cchar *uri) |
Redirect the client. | |
void | maSetCookie(MaConn *conn, cchar *name, cchar *value, cchar *path, cchar *domain, int lifetime, bool secure) |
Set a response cookie. | |
void | maSetHeader(MaConn *conn, bool allowMultiple, cchar *key, cchar *fmt, ...) |
Set a response header. | |
void | maSetResponseCode(MaConn *conn, int code) |
Set a Http response code. | |
void | maSetResponseMimeType(MaConn *conn, cchar *mimeType) |
Set the response mime type. | |
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. | |
MaStage* | maCreateConnector(MaHttp *http, cchar *name, int flags) |
Create a connector stage. | |
MaStage* | maCreateFilter(MaHttp *http, cchar *name, int flags) |
Create a filter stage. | |
MaStage* | maCreateHandler(MaHttp *http, cchar *name, int flags) |
Create a request handler stage. | |
void | maDefaultOutgoingServiceStage(MaQueue *q) |
Default outgoing data handling. | |
void* | maLookupStageData(MaHttp *http, cchar *name) |
Lookup stage data. |
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_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_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_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_URL 512 |
Max URL 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 0x20 |
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_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) - HEAP_OVERHEAD) |
Default per-request 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_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_FORM_VARS 0x10000 |
Create query and form variables table. | |
#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_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_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:
- Fields:
-
MaAuth * auth Current auth object. MaDir * dir Current directory block. int enabled True if the current block is enabled. MprFile * file Config file handle. MaHost * host Current host. int lineNumber Config file name. Current line number. MaLocation * location Current location. MaServer * server Current server.
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:
-
int abandonConnection Abandon all processing on the current connection. Emit no data. MaHostAddress * address Host address structure for this connection. MprHeap * arena Connection memory arena. int canProceed State machine should continue to process the request. 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. 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. struct MaQueue serviceq List of queues that require service for request pipeline. MprSocket * sock Underlying socket handle. int socketEventMask Mask of events to receive. MprTime started When the connection started. int state Connection state. MprTime time Cached current time. int timeout Timeout period in msec.
MaDir
Directory Control.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MaAuth * auth Authorization control. struct MaHost * host Host owning this directory. char * indexName Default index document name. char * path Directory filename. int pathLen Length of the directory path.
MaFilter
Filter Stages.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MaHost
Host Object A Host object represents a single listening HTTP connection endpoint.
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MprFile * accessLog File object for access logging. MprList * aliases List of Alias definitions. MprList * connections Currently open connection requests. char * currentDate Date string for HTTP response headers. MprList * dirs List of Directory definitions. int httpVersion HTTP/1.X. char * ipAddrPort IP:PORT address (with wildcards). int keepAlive Keep alive supported - TODO should be in flags. int keepAliveTimeout Timeout for keep-alive. MaLimits * limits Pointer to http->limits. MaLocation * location Default location. MprList * locations List of Location defintions. struct MaHost * logHost If set, use this hosts logs. int maxKeepAlive Max keep-alive requests. char * mimeFile Name of the mime types file. MprHashTable * mimeTypes Hash table of mime types (key is extension). char * moduleDirs Directories for modules. char * name ServerName directive. struct MaHost * parent Parent host for virtual hosts. char * secret Random bytes for authentication. bool secure Host is a secure (SSL) host. MaServer * server Server owning this host. int timeout Max time a request can take. MprEvent * timer Admin service timer. MprTime whenCurrentDate When was the current date last computed.
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 * 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. MprMutex * mutex Multi-thread sync. struct MaStage * netConnector Network connector. struct MaStage * passHandler Pass through 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:
- Fields:
-
int maxBody Max size of an incoming request. int maxChunkSize Max chunk size for transfer encoding. int maxHeader Max size of the total header. int maxNumHeaders Max number of lines of header. int maxResponseBody Max size of generated response content. int maxStageBuffer Max buffering by any pipeline stage. int maxThreads Max number of pool threads. int maxUploadSize Max size of an uploaded file. int maxUrl Max size of a URL. int minThreads Min number of pool threads. int threadStackSize Stack size for each pool thread.
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. struct MaStage * connector Network connector. 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.
MaMimeType
Mime Type hash table entry (the URL extension is the key).
- API Stability:
- Evolving.
- See Also:
- Fields:
-
MaPacket
Data packet.
- Description:
- The request/response pipeline sends data and control information in MaPacket objects. The output stream typically consists of a HEADER packet followed by zero or more data packets and terminated by an END packet. If the request has input data, the input stream is consists of one or more data packets followed by an END packet.
Packets contain data and optional prefix or suffix headers. Packets can be split, joined, filled or emptied. The pipeline stages will fill or transform packet data as required.
- API Stability:
- Evolving.
- See Also:
- MaQueue, maCreateEndPacket, maCreateHeaderPacket, maCreatePacket, maGetPacketLength, maJoinPacket, maSplitPacket
- Fields:
-
struct MaConn * conn Owning connection. MprBuf * content Chunk content. int count Count of bytes in packet. int flags Packet flags. struct MaPacket * next Next packet in chain. MprBuf * prefix Prefix message to be emitted before the content. MprBuf * suffix Prefix message to be emitted after the content.
Create a data packet.
- Description:
- Create a packet and set the MA_PACKET_DATA flag Data packets convey data through the response pipeline.
- Parameters:
-
conn MaConn connection object. size Size of the package data storage.
- Returns:
- MaPacket object.
Create an end packet.
- Description:
- Create an end-of-stream packet and set the MA_PACKET_END flag. The end pack signifies the end of data. It is used on both incoming and outgoing streams through the request/response pipeline.
- Parameters:
-
conn MaConn connection object.
- Returns:
- MaPacket object.
Create a response header packet.
- Description:
- Create a response header packet and set the MA_PACKET_HEADER flag. A header packet is used by the pipeline to hold the response headers.
- Parameters:
-
conn MaConn connection object.
- Returns:
- MaPacket object.
- See Also:
- MaPacket, MaQueue, maCreateEndPacket, maCreatePacket, maGetPacketLength, maJoinPacket, maSplitPacket
Create a data packet.
- Description:
- Create a packet of the required size.
- Parameters:
-
conn MaConn connection object. size Size of the package data storage.
- Returns:
- MaPacket object.
Get the length of the packet data contents.
- Description:
- Get the content length of a packet. This does not include the prefix or suffix data length -- just the pure data contents.
- Parameters:
-
packet Packet to examine.
- Returns:
- Count of bytes contained by the packet.
Join tow packets.
- Description:
- Join the contents of one packet to another by copying the data from the other packet into the first packet.
- Parameters:
-
packet Destination packet. other Other packet to copy data from.
- Returns:
- Zero if successful, otherwise a negative Mpr error code.
Split a data packet.
- Description:
- Split a data packet at the specified offset. Packets may need to be split so that downstream stages can digest their contents. If a packet is too large for the queue maximum size, it should be split. When the packet is split, a new packet is created containing the data after the offset. Any suffix headers are moved to the new packet.
- Parameters:
-
conn MaConn connection object. packet Packet to split. offset Location in the original packet at which to split.
- Returns:
- New MaPacket object containing the data after the offset. No need to free, unless you have a very long running request. Otherwise the packet memory will be released automatically when the request completes.
MaQueue
Queue Head.
- Description:
- The request pipeline consists of a full-duplex pipeline of stages. Each stage has two queues, one for outgoing data and one for incoming. A MaQueue object manages the data flow for a request stage and has the ability to queue and process data, manage flow control and schedule packets for service.
Queue's provide open, close, put and service methods. These methods manage and respond to incoming packets. A queue can respond immediately to an incoming packet by processing or dispatching a packet in its put() method. Alternatively, the queue can defer processing by queueing the packet on it's service queue and then waiting for it's service() method to be invoked.
If a queue does not define a put() method, the default put method will be used which queues data onto the service queue. The default incoming put() method joins incoming packets into a single packet on the service queue.
- API Stability:
- Evolving.
- See Also:
- MaConn, MaPacket, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
- Fields:
-
MaQueueClose close Close the queue. struct MaConn * conn Connection ownning this queue. int count Bytes in queue. int direction Flow direction. MaPacket * first First packet in queue (singly linked). int flags Queue flags. int ioCount Count of bytes in iovec. int ioFileEntry Has file entry in iovec. int ioFileOffset The next file position to use. int ioIndex Next index into iovec. MaPacket * last Last packet in queue (tail pointer). int low Low water mark for flow control. int max Maxiumum queue size. struct MaQueue * nextQ Downstream queue for next stage. MaQueueOpen open Open the queue. cchar * owner Name of owning stage. int packetSize Maximum acceptable packet size. struct MaQueue * pair Queue for the same stage in the opposite direction. MaPacket * pending Packets pending more dynamic data output. struct MaQueue * prevQ Upstream queue for prior stage. MaQueueData put Put a message on the queue. void * queueData Stage instance data. struct MaQueue * scheduleNext Next linkage when queue is on the service queue. struct MaQueue * schedulePrev Previous linkage when queue is on the service queue. MaQueueService service Service the queue. struct MaStage * stage Stage owning this queue.
Disable a queue.
- Description:
- Mark a queue as disabled so that it will not be scheduled for service.
- Parameters:
-
q Queue reference.
- See Also:
- MaConn, MaPacket, MaQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Discard all data from the queue.
- Description:
- Discard data from the queue. If removePackets (not yet implemented) is true, then remove the packets otherwise, just discard the data and preserve the packets.
- Parameters:
-
q Queue reference. removePackets If true, the data packets will be removed from the queue.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Enable a queue.
- Description:
- Enable a queue for service and schedule it to run. This will cause the service routine to run as soon as possible.
- Parameters:
-
q Queue reference.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Get the next packet from a queue.
- Description:
- Get the next packet. This will remove the packet from the queue and adjust the queue counts accordingly. If the queue was full and upstream queues were blocked, they will be enabled.
- Parameters:
-
q Queue reference.
- Returns:
- The packet removed from the queue.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Get the room in the queue.
- Description:
- Get the amount of data the queue can accept before being full.
- Parameters:
-
q Queue reference.
- Returns:
- A count of bytes that can be written to the queue.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Determine if the queue is empty.
- Description:
- Determine if the queue has no packets queued. This does not test if the queue has no data content.
- Parameters:
-
q Queue reference.
- Returns:
- True if there are no packets queued.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Join a packet onto the service queue.
- Description:
- Add a packet to the service queue. If the queue already has data, then this packet will be joined (aggregated) into the existing packet. If serviceQ is true, the queue will be scheduled for service.
- Parameters:
-
q Queue reference. packet Packet to join to the queue. serviceQ If true, schedule the queue for service.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Test if a packet is too big.
- Description:
- Test if a packet is too big to fit downstream. If the packet content exceeds the downstream queue's maximum or exceeds the downstream queue's requested packet size -- then this routine will return true.
- Parameters:
-
q Queue reference. packet Packet to test.
- Returns:
- True if the packet is too big for the downstream queue.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Put a packet onto a queue.
- Description:
- Put the packet onto the end of queue by calling the queue's put() method.
- Parameters:
-
q Queue reference. packet Packet to put.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Put a packet back onto a queue.
- Description:
- Put the packet back onto the front of the queue. The queue's put() method is not called. This is typically used by the queue's service routine when a packet cannot complete processing.
- Parameters:
-
q Queue reference. packet Packet to put back.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Put a packet onto the service queue.
Put a packet onto a service queue- Description:
- Add a packet to the service queue. If serviceQ is true, the queue will be scheduled for service.
- Parameters:
-
q Queue reference. packet Packet to join to the queue. serviceQ If true, schedule the queue for service.
- Description:
- Put the packet onto the service queue and optionally schedule the queue for service.
- Parameters:
-
q Queue reference. packet Packet to put.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Put a packet onto the next queue.
- Description:
- Put a packet onto the next downstream queue by calling the downstreams queue's put() method.
- Parameters:
-
q Queue reference. The packet will not be queued on this queue, but rather on the queue downstream. packet Packet to put.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Remove a queue.
- Description:
- Remove a queue from the request/response pipeline. This will remove a queue so that it does not participate in the pipeline, effectively removing the processing stage from the pipeline. This is useful to remove unwanted filters and to speed up pipeline processing.
- Parameters:
-
q Queue reference.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Resize a packet.
- Description:
- Resize a packet if required so that it fits in the downstream queue. This may split the packet if it is too big to fit in the downstream queue. If it is split, the tail portion is put back on the queue.
- Parameters:
-
q Queue reference. packet Packet to put. size If size is > 0, then also ensure the packet is not larger than this size.
- Returns:
- Zero if successful, otherwise a negative Mpr error code.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Schedule a queue.
- Description:
- Schedule a queue by adding it to the schedule queue. Queues are serviced FIFO.
- Parameters:
-
q Queue reference.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Send an end packet.
- Description:
- Create and send an end-of-stream packet downstream.
- Parameters:
-
q Queue reference.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Send all queued packets.
- Description:
- Send all queued packets downstream.
- Parameters:
-
q Queue reference.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Service a queue.
- Description:
- Service a queue by invoking its service() routine.
- Parameters:
-
q Queue reference.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maWillNextQueueAccept, maWrite, maWriteBlock, maWriteString
Determine if the downstream queue will accept this packet.
- Description:
- Test if the downstream queue will accept a packet. The packet will be resized if required in an attempt to get the downstream queue to accept it. If the downstream queue is full, disable this queue and mark the downstream queue as full and service it immediately to try to relieve the congestion.
- Parameters:
-
q Queue reference. packet Packet to put.
- Returns:
- True if the downstream queue will accept the packet. Use maPutNext to send the packet downstream.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWrite, maWriteBlock, maWriteString
Write a formatted string.
- Description:
- Write a formatted string of data into packets onto the end of the queue. Data packets will be created as required to store the write data. This call may block waiting for the downstream queue to drain if it is or becomes full.
- Parameters:
-
q Queue reference. fmt Printf style formatted string. ... Arguments for fmt.
- Returns:
- A count of the bytes actually written.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWriteBlock, maWriteString
Write a block of data to the queue.
- Description:
- Write a block of data into packets onto the end of the queue. Data packets will be created as required to store the write data.
- Parameters:
-
q Queue reference. buf Buffer containing the write data. size of the data in buf. block Set to true to block and wait for data to drain if the downstream queue is full. If false, the call may return not having written all the data. The return value indicates how many bytes were actually written.
- Returns:
- A count of the bytes actually written.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteString
Write a string of data to the queue.
- Description:
- Write a string of data into packets onto the end of the queue. Data packets will be created as required to store the write data. This call may block waiting for the downstream queue to drain if it is or becomes full.
- Parameters:
-
q Queue reference. s String containing the data to write.
- Returns:
- A count of the bytes actually written.
- See Also:
- MaConn, MaPacket, MaQueue, maDisableQueue, maDiscardData, maEnableQueue, maGet, maGetQueueRoom, maIsQueueEmpty, maJoinForService, maPacketTooBig, maPut, maPutBack, maPutForService, maPutForService, maPutNext, maRemoveQueue, maResizePacket, maScheduleQueue, maSendEndPacket, maSendPackets, maServiceQueue, maWillNextQueueAccept, maWrite, maWriteBlock
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:
- Fields:
-
int end End byte of range + 1. int len Redundant range length. struct MaRange * next Next range. int start Start of range.
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, maAddFormVars, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar
- Fields:
-
char * accept Accept header. char * acceptCharset Accept-Charset header. char * acceptEncoding Accept-Encoding header. MaAlias * alias Matching alias. MprHeap * arena Request memory arena. MaAuth * auth Set to either dir or location auth information. char * authType Authorization type (basic|digest) (ENV: AUTH_TYPE). struct MaConn * conn Connection object. char * connection Connection header. char * contentLengthStr Content length string value. char * cookie Request cookie header. MaDir * dir Best matching dir (PTR only). MprList * etags Document etag to uniquely identify the document version. int flags Request modifiers. MprHashTable * formVars Query and post data variables. char * forwarded Forwarded header. char * group Supplied via basic / digest auth. MaPacket * headerpacket Packet containing all headers ( == conn->input). MaPacket * headerPacket HTTP headers. MprHashTable * headers Header variables. MaHost * host Owning host for this request. char * hostName Client supplied host name. char * httpProtocol HTTP/1.0 or HTTP/1.1. bool ifMatch If-Match processing requested. bool ifModified If-Modified processing requested. MprList * inputPipeline Input processing. MaRange * inputRange Specified range for input (post) data. int length Declared content length (ENV: CONTENT_LENGTH). MaLocation * location Location block. int method Request method. char * methodName Protocol method GET|PUT. (ENV: REQUEST_METHOD). char * mimeType Mime type of the request payload (ENV: CONTENT_TYPE). MaPacket * packet Current input packet. MprUri * parsedUri Parsed query string. parsedUri->query is the query string. char * pathInfo Extra path information (ENV: PATH_INFO). char * pathTranslated Mapped extraPath to storage (ENV: PATH_TRANSLATED). char * pragma Pragma header. MaRange * ranges Requested ranges for response data. int receivedContent Length of content actually received. char * referer Refering URL. int remainingChunk Remaining chunk data to read. int remainingContent Remaining content data to read. MprTime since If-Modified date. char * url Decoded URL. Doesn't include scheme, host, extra path, query or fragments. char * user Remote user (ENV: REMOTE_USER). char * userAgent User-Agent header.
Add form variables.
- Description:
- Add new form variables encoded in the supplied buffer.
- Parameters:
-
conn MaConn connection object. 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.
MaResponse
Http Response.
- Description:
- Most of the APIs in the Response 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, MaRequest, maFailRequest, maFormatBody, maSetCookie
- Fields:
-
char * altBody Alternate response for errors. int bytesWritten Bytes written including headers. int chunkSize Chunk size to use when using transfer encoding. int code HTTP response code. struct MaConn * conn Current connection object. MaStage * connector Response connector. MaRange * currentRange Current range being fullfilled. int entityLength Original content length before range subsetting. char * etag Unique identifier tag. cchar * extension Filename extension. MprFile * file File to be served. MprPath fileInfo File information if there is a real file to serve. char * filename Name of a real file being served. int flags Response flags. MaPacket * freePackets List of free packets. MaStage * handler Response handler. void * handlerData Data reserved for the handler. char * header HTTP response header. MprHashTable * headers Custom response headers. int headerSize Size of the header written. int length Response content length. cchar * mimeType Mime type of the response document. MprList * outputPipeline Output processing. int pos Current I/O position. MaQueue queue[2] Dummy head for the response queues. char * rangeBoundary Inter-range boundary.
Dont cache the response.
- Description:
- Instruct the client not to cache the response body. This is done by setting the Cache-control Http header.
- Parameters:
-
conn MaConn connection object.
- See Also:
- MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
Fail a request.
- Description:
- Fail a request with the specified http status code. The formatted message is logged to the appweb error log.
- Parameters:
-
conn MaConn connection object. code Http status code. fmt Printf style formatted string. ... Arguments for fmt.
- See Also:
- MaConn, MaRequest, MaResponse, maFormatBody, maSetCookie
Create the response headers.
- Description:
- Fill the given empty packet with the Http response headers. This should only be called by connectors just prior to sending output to the client. It should be delayed as long as possible if the content length is not yet known to give the pipeline a chance to determine the response length. This way, a non-chunked response can be sent with a content-length header. This is the fastest HTTP response.
- Parameters:
-
conn MaConn connection object. packet Packet into which to place the headers.
- See Also:
- MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
Format an alternate response body.
- Description:
- Format a response body to use instead of data generated by the request processing pipeline. This is typically used to send error responses and redirections.
- Parameters:
-
conn MaConn connection object. title Title string to format into the HTML response body. fmt Printf style formatted string. This string may contain HTML tags and is not HTML encoded before sending to the user. NOTE: Do not send user input back to the client using this method. Otherwise you open large security holes. ... Arguments for fmt.
- Returns:
- A count of the number of bytes in the response body.
- See Also:
- MaConn, MaRequest, MaResponse, maFailRequest, maSetCookie
Redirect the client.
- Description:
- Redirect the client to a new uri.
- Parameters:
-
conn MaConn connection object. code Http status code to send with the response. uri New uri for the client.
- See Also:
- MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
Set a response cookie.
- Description:
- Define a cookie to send in the response Http header.
- Parameters:
-
conn MaConn connection object. name Cookie name. value Cookie value. path URI path to which the cookie applies. domain Domain in which the cookie applies. Must have 2-3 dots. lifetime Duration for the cookie to persist in seconds. secure Set to true if the cookie only applies for SSL based connections.
- See Also:
- MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody
Set a response header.
- Description:
- Set the response header. If allowMultiple is true, then duplicate keys can be defined. Otherwise, prior key headers are overwritten.
- Parameters:
-
conn MaConn connection object. allowMultiple If true, allow duplicate keys of the same value. key Http response header key. fmt Printf style formatted string to use as the header key value. ... Arguments for fmt.
- See Also:
- MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
Set a Http response code.
- Description:
- Set the Http response code for the request. This defaults to 200 (OK).
- Parameters:
-
conn MaConn connection object. code Http status code.
- See Also:
- MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
Set the response mime type.
- Description:
- Set the response mime type Http header.
- Parameters:
-
conn MaConn connection object. mimeType Mime type string.
- See Also:
- MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
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:
-
bool alreadyLogging Already logging. struct MaHost * defaultHost Primary host. MprList * hostAddresses List of HostAddress objects. MprList * hosts List of host objects. MprList * listens List of listening sockets. int maxConcurrentRequests Maximum number of clients. char * name Unique name for this server. char * serverRoot Server root.
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.
MaStage
Pipeline Stages.
- Description:
- The request pipeline consists of a full-duplex pipeline of stages. Stages are used to process client HTTP requests in a modular fashion. Each stage either creates, filters or consumes data packets. The MaStage structure describes the stage capabilities and callbacks. Each stage has two queues, one for outgoing data and one for incoming data.
Stages provide callback methods for parsing configuration, matching requests, open/close, run and the acceptance and service of incoming and outgoing data.
- API Stability:
- Evolving.
- See Also:
- MaConn, MaQueue, maCreateConnector, maCreateFilter, maCreateHandler, maDefaultOutgoingServiceStage, maLookupStageData
- Fields:
-
void(* close)(MaQueue *q) Close the queue. Description:Close the queue instance .q Queue instance object int flags Stage flags. void(* incomingData)(MaQueue *q, MaPacket *packet) Process incoming data. Description:Accept an incoming packet of data .q Queue instance object packet Packet of data void(* incomingService)(MaQueue *q) Service the incoming data queue. .q Queue instance object bool(* match)(struct MaConn *conn, struct MaStage *stage, cchar *uri) Match a request. Description:This method is invoked to see if the stage wishes to handle the request. If a stage denies to handle a request, it will be removed from the pipeline. conn MaConn connection object stage Stage object uri Current request URI True if the stage wishes to process this request. .char * name Stage name. void(* open)(MaQueue *q) Open the queue. Description:Open the queue instance and initialize for this request. .q Queue instance object void(* outgoingData)(MaQueue *q, MaPacket *packet) Process outgoing data. Description:Accept a packet as outgoing data .q Queue instance object packet Packet of data void(* outgoingService)(MaQueue *q) Service the outgoing data queue. .q Queue instance object int(* parse)(MaHttp *http, cchar *key, char *value, MaConfigState *state) Parse configuration data. Description:This is invoked when parsing appweb configuration files http MaHttp object key Configuration directive name value Configuration directive value state Current configuration parsing state Zero if the key was not relevant to this stage. Return 1 if the directive applies to this stage and was accepted. .void(* run)(MaQueue *q) Run the queue. Description:The queue is run after all incoming data has been received. .q Queue instance object void * stageData Per-stage data.
Create a connector stage.
- Description:
- Create a new connector. Connectors are the final stage for outgoing data. Their job is to transmit outgoing data to the client.
- Parameters:
-
http MaHttp object returned from maCreateHttp. name Name of connector stage. flags Stage flags mask. These specify what Http request methods will be supported by this stage. Or together any of the following flags: - MA_STAGE_DELETE - Support DELETE requests
- MA_STAGE_GET - Support GET requests
- MA_STAGE_HEAD - Support HEAD requests
- MA_STAGE_OPTIONS - Support OPTIONS requests
- MA_STAGE_POST - Support POST requests
- MA_STAGE_PUT - Support PUT requests
- MA_STAGE_TRACE - Support TRACE requests
- MA_STAGE_ALL - Mask to support all methods
- Returns:
- A new stage object.
Create a filter stage.
- Description:
- Create a new filter. Filters transform data generated by handlers and before connectors transmit to the client. Filters can apply transformations to incoming, outgoing or bi-directional data.
- Parameters:
-
http MaHttp object returned from maCreateHttp. name Name of connector stage. flags Stage flags mask. These specify what Http request methods will be supported by this stage. Or together any of the following flags: - MA_STAGE_DELETE - Support DELETE requests
- MA_STAGE_GET - Support GET requests
- MA_STAGE_HEAD - Support HEAD requests
- MA_STAGE_OPTIONS - Support OPTIONS requests
- MA_STAGE_POST - Support POST requests
- MA_STAGE_PUT - Support PUT requests
- MA_STAGE_TRACE - Support TRACE requests
- MA_STAGE_ALL - Mask to support all methods
- Returns:
- A new stage object.
Create a request handler stage.
- Description:
- Create a new handler. Handlers generate outgoing data and are the final stage for incoming data. Their job is to process requests and send outgoing data downstream toward the client consumer. There is ever only one handler for a request.
- Parameters:
-
http MaHttp object returned from maCreateHttp. name Name of connector stage. flags Stage flags mask. These specify what Http request methods will be supported by this stage. Or together any of the following flags: - MA_STAGE_DELETE - Support DELETE requests
- MA_STAGE_GET - Support GET requests
- MA_STAGE_HEAD - Support HEAD requests
- MA_STAGE_OPTIONS - Support OPTIONS requests
- MA_STAGE_POST - Support POST requests
- MA_STAGE_PUT - Support PUT requests
- MA_STAGE_TRACE - Support TRACE requests
- MA_STAGE_ALL - Mask to support all methods
- Returns:
- A new stage object.
Default outgoing data handling.
- Description:
- This routine provides default handling of outgoing data for stages. It simply sends all packets downstream.
- Parameters:
-
q Queue object.
- See Also:
- MaConn, MaQueue, MaStage, maCreateConnector, maCreateFilter, maCreateHandler, maLookupStageData
Lookup stage data.
- Description:
- This looks up the stage by name and returns the private stage data.
- Parameters:
-
http MaHttp object returned from maCreateHttp. name Name of the stage concerned.
- Returns:
- Reference to the stage data block.
MaUploadFile
Upload File.
- API Stability:
- Evolving.
- See Also:
- Fields:
-