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.
intmaSetHttpGroup(MaHttp *http, cchar *group)
 Set the Http Group.
intmaSetHttpUser(MaHttp *http, cchar *user)
 Set the Http User.
intmaStartHttp(MaHttp *http)
 Start Http services.
intmaStopHttp(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.
intmaGetPacketLength(MaPacket *packet)
 Get the length of the packet data contents.
intmaJoinPacket(MaPacket *packet, MaPacket *other)
 Join tow packets.
MaPacket*maSplitPacket(struct MaConn *conn, MaPacket *packet, int offset)
 Split a data packet.
voidmaDisableQueue(MaQueue *q)
 Disable a queue.
voidmaDiscardData(MaQueue *q, bool removePackets)
 Discard all data from the queue.
voidmaEnableQueue(MaQueue *q)
 Enable a queue.
MaPacket*maGet(MaQueue *q)
 Get the next packet from a queue.
intmaGetQueueRoom(MaQueue *q)
 Get the room in the queue.
boolmaIsQueueEmpty(MaQueue *q)
 Determine if the queue is empty.
voidmaJoinForService(MaQueue *q, MaPacket *packet, bool serviceQ)
 Join a packet onto the service queue.
boolmaPacketTooBig(MaQueue *q, MaPacket *packet)
 Test if a packet is too big.
voidmaPut(MaQueue *q, MaPacket *packet)
 Put a packet onto a queue.
voidmaPutBack(MaQueue *q, MaPacket *packet)
 Put a packet back onto a queue.
voidmaPutForService(MaQueue *q, MaPacket *packet, bool serviceQ)
 Put a packet onto the service queue.
voidmaPutNext(MaQueue *q, MaPacket *packet)
 Put a packet onto the next queue.
voidmaRemoveQueue(MaQueue *q)
 Remove a queue.
intmaResizePacket(MaQueue *q, MaPacket *packet, int size)
 Resize a packet.
voidmaScheduleQueue(MaQueue *q)
 Schedule a queue.
voidmaSendEndPacket(MaQueue *q)
 Send an end packet.
voidmaSendPackets(MaQueue *q)
 Send all queued packets.
voidmaServiceQueue(MaQueue *q)
 Service a queue.
boolmaWillNextQueueAccept(MaQueue *q, MaPacket *packet)
 Determine if the downstream queue will accept this packet.
intmaWrite(MaQueue *q, cchar *fmt, ...)
 Write a formatted string.
intmaWriteBlock(MaQueue *q, cchar *buf, int size, bool block)
 Write a block of data to the queue.
intmaWriteString(MaQueue *q, cchar *s)
 Write a string of data to the queue.
voidmaAddFormVars(MaConn *conn, cchar *buf, int len)
 Add form variables.
intmaCompareFormVar(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.
intmaGetIntFormVar(MaConn *conn, cchar *var, int defaultValue)
 Get a form variable as an integer.
cchar*maGetQueryString(MaConn *conn)
 Get the request query string.
voidmaSetFormVar(MaConn *conn, cchar *var, cchar *value)
 Set a form variable value.
voidmaSetIntFormVar(MaConn *conn, cchar *var, int value)
 Set a form variable value.
intmaTestFormVar(MaConn *conn, cchar *var)
 Test if a form variable is defined.
voidmaDontCacheResponse(MaConn *conn)
 Dont cache the response.
voidmaFailRequest(MaConn *conn, int code, cchar *fmt, ...)
 Fail a request.
voidmaFillHeaders(MaConn *conn, MaPacket *packet)
 Create the response headers.
intmaFormatBody(MaConn *conn, cchar *title, cchar *fmt, ...)
 Format an alternate response body.
voidmaRedirect(MaConn *conn, int code, cchar *uri)
 Redirect the client.
voidmaSetCookie(MaConn *conn, cchar *name, cchar *value, cchar *path, cchar *domain, int lifetime, bool secure)
 Set a response cookie.
voidmaSetHeader(MaConn *conn, bool allowMultiple, cchar *key, cchar *fmt, ...)
 Set a response header.
voidmaSetResponseCode(MaConn *conn, int code)
 Set a Http response code.
voidmaSetResponseMimeType(MaConn *conn, cchar *mimeType)
 Set the response mime type.
intmaConfigureServer(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.
voidmaLoadStaticModules(MaHttp *http)
 Load static modules.
intmaRunSimpleWebServer(cchar *ipAddress, int port, cchar *docRoot)
 Create and run a simple web server listening on a single IP address.
intmaRunWebServer(cchar *configFile)
 Create and run a web server based on a configuration file.
intmaServiceWebServer(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.
voidmaDefaultOutgoingServiceStage(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.
#defineMA_BUFSIZE   (4 * 1024)
 Default I/O buffer size.
#defineMA_CGI_PERIOD   20
 CGI poll period (only for windows).
#defineMA_CGI_TIMEOUT   4000
 Time to wait to reap exit status.
#defineMA_CONN_CASE_INSENSITIVE   0x2
 System case-insensitive for file matches.
#defineMA_CONN_CLEAN_MASK   0x1
 Mask to clear flags after a request completes.
#defineMA_CONN_CLOSE   0x1
 Connection needs to be closed.
#defineMA_DEFAULT_MAX_THREADS   10
 Default number of threads.
#defineMA_KEEP_TIMEOUT   60000
 Keep connection alive timeout.
#defineMA_LOC_APP   0x2
 Location defines an application.
#defineMA_LOC_APP_DIR   0x4
 Location defines a directory of applications.
#defineMA_LOC_AUTO_SESSION   0x8
 Auto create sessions in this location.
#defineMA_LOC_BROWSER   0x10
 Send errors back to the browser for this location.
#defineMA_MAX_ACCESS_LOG   (20971520)
 Access file size (20 MB).
#defineMA_MAX_IOVEC   16
 Number of fragments in a single socket write.
#defineMA_MAX_KEEP_ALIVE   100
 Default requests per TCP conn.
#defineMA_MAX_PASS   64
 Size of password.
#defineMA_MAX_QUEUE   2
 Number of queue types.
#defineMA_MAX_SECRET   32
 Number of random bytes to use.
#defineMA_MAX_URL   512
 Max URL size.
#defineMA_PACKET_DATA   0x4
 Packet contains actual content data.
#defineMA_PACKET_END   0x8
 End of stream packet.
#defineMA_PACKET_HEADER   0x1
 Packet contains HTTP headers.
#defineMA_PACKET_RANGE   0x2
 Packet is a range boundary packet.
#defineMA_QUEUE_ALL   0x8
 Queue has all the data there is and will be.
#defineMA_QUEUE_DISABLED   0x2
 Queue's service routine is disabled.
#defineMA_QUEUE_EOF   0x20
 Queue at end of data.
#defineMA_QUEUE_FULL   0x4
 Queue is full.
#defineMA_QUEUE_OPEN   0x1
 Queue's open routine has been called.
#defineMA_QUEUE_RECEIVE   1
 Receive (read from client) queue.
#defineMA_QUEUE_SEND   0
 Send (transmit to client) queue.
#defineMA_QUEUE_SERVICED   0x10
 Queue has been serviced at least once.
#defineMA_REQ_CHUNKED   0x4
 Content is chunk encoded.
#defineMA_REQ_CREATE_ENV   0x1
 Must create env for this request.
#defineMA_REQ_DELETE   0x1
 DELETE method.
#defineMA_REQ_GET   0x2
 GET method.
#defineMA_REQ_HEAD   0x4
 HEAD method.
#defineMA_REQ_IF_MODIFIED   0x2
 If-[un]modified-since supplied.
#defineMA_REQ_MASK   0x7F
 Method mask.
#defineMA_REQ_MEM   ((1 * 1024 * 1024) - HEAP_OVERHEAD)
 Default per-request memory arena size.
#defineMA_REQ_OPTIONS   0x8
 OPTIONS method.
#defineMA_REQ_POST   0x10
 Post method.
#defineMA_REQ_PUT   0x20
 PUT method.
#defineMA_REQ_TRACE   0x40
 TRACE method.
#defineMA_RESP_DONT_CACHE   0x1
 Add no-cache to the response.
#defineMA_RESP_DONT_FINISH   0x2
 Don't auto finish the request.
#defineMA_RESP_HEADERS_CREATED   0x8
 Response headers have been created.
#defineMA_RESP_NO_BODY   0x4
 No respose body, only return headers to client.
#defineMA_STAGE_ALL   MA_REQ_MASK
 Mask for all methods.
#defineMA_STAGE_AUTO_DIR   0x100000
 Want auto directory redirection.
#defineMA_STAGE_CONNECTOR   0x1000
 Stage is a connector.
#defineMA_STAGE_DELETE   MA_REQ_DELETE
 Support DELETE requests.
#defineMA_STAGE_ENV_VARS   0x20000
 Create CGI style environment variables table.
#defineMA_STAGE_FILTER   0x4000
 Stage is a filter.
#defineMA_STAGE_FORM_VARS   0x10000
 Create query and form variables table.
#defineMA_STAGE_GET   MA_REQ_GET
 Support GET requests.
#defineMA_STAGE_HANDLER   0x2000
 Stage is a handler.
#defineMA_STAGE_HEAD   MA_REQ_HEAD
 Support HEAD requests.
#defineMA_STAGE_MODULE   0x8000
 Stage is a filter.
#defineMA_STAGE_OPTIONS   MA_REQ_OPTIONS
 Support OPTIONS requests.
#defineMA_STAGE_PATH_INFO   0x80000
 Always do path info processing.
#defineMA_STAGE_POST   MA_REQ_POST
 Support POST requests.
#defineMA_STAGE_PUT   MA_REQ_PUT
 Support PUT requests.
#defineMA_STAGE_TRACE   MA_REQ_TRACE
 Support TRACE requests.
#defineMA_STAGE_VIRTUAL   0x40000
 Handler serves virtual resources not the physical file system.
#defineMA_TIMER_PERIOD   1000
 Timer checks ever 1 second.

MaAlias

MaAlias

Aliases.

API Stability:
Evolving.
See Also:
Fields:
char *filename Alias to a physical path name.
char *prefix Original URI prefix.
intprefixLen Prefix length.
char *uri Redirect to a uri.

MaAuth

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

MaConfigState

Current config parse state.

API Stability:
Evolving.
See Also:
Fields:
MaAuth *auth Current auth object.
MaDir *dir Current directory block.
intenabled True if the current block is enabled.
MprFile *file Config file handle.
MaHost *host Current host.
intlineNumber Config file name. Current line number.
MaLocation *location Current location.
MaServer *server Current server.

MaConn

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:
intabandonConnection Abandon all processing on the current connection. Emit no data.
MaHostAddress *address Host address structure for this connection.
MprHeap *arena Connection memory arena.
intcanProceed State machine should continue to process the request.
MprTimeexpire When the connection should expire.
intflags Connection flags.
MaHost *host Owning host for this request.
MaHttp *http Http handle.
MaPacket *input Header packet.
intkeepAliveCount Count of remaining keep alive requests for this connection.
MaHost *originalHost Owning host for this connection. May be changed by Host header.
intprotocol HTTP protocol version 0 == HTTP/1.0, 1 == HTTP/1.1.
char *remoteIpAddr Remote client IP address (REMOTE_ADDR).
intremotePort Remote client IP port number.
struct MaRequest *request Request object.
intrequestFailed Request failed. Abbreviate request processing.
struct MaResponse *response Response object.
struct MaQueueserviceq List of queues that require service for request pipeline.
MprSocket *sock Underlying socket handle.
intsocketEventMask Mask of events to receive.
MprTimestarted When the connection started.
intstate Connection state.
MprTimetime Cached current time.
inttimeout Timeout period in msec.

MaDir

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.
intpathLen Length of the directory path.

MaFilter

MaFilter

Filter Stages.

API Stability:
Evolving.
See Also:
Fields:

MaHost

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.
inthttpVersion HTTP/1.X.
char *ipAddrPort IP:PORT address (with wildcards).
intkeepAlive Keep alive supported - TODO should be in flags.
intkeepAliveTimeout 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.
intmaxKeepAlive 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.
boolsecure Host is a secure (SSL) host.
MaServer *server Server owning this host.
inttimeout Max time a request can take.
MprEvent *timer Admin service timer.
MprTimewhenCurrentDate When was the current date last computed.

MaHostAddress

MaHostAddress

Host Address Mapping.

API Stability:
Evolving.
See Also:
Fields:
intflags Mapping flags.
char *ipAddr IP Address for this endpoint.
intport Port for this endpoint.
MprList *vhosts Vhosts using this address.

MaHttp

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.
intgid Group Id.
char *groupname Http server group name.
MaLimitslimits 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.
intuid User Id.
char *username Http server user name.
MaHttp * maCreateHttp (MprCtx ctx)

Create the MaHttp object.

Description:
The Appweb library uses a singleton MaHttp object to manage multiple embedded web servers.
Parameters:
ctxAny memory context object returned by mprAlloc.
Returns:
A MaHttp object. Use mprFree to close and release.
See Also:
MaHttp, maStartHttp, maStopHttp
int maSetHttpGroup (MaHttp *http, cchar *group)

Set the Http Group.

Description:
Define the group name under which to run the Appweb service.
Parameters:
httpMaHttp object created via maCreateHttp.
groupGroup 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
int maSetHttpUser (MaHttp *http, cchar *user)

Set the Http User.

Description:
Define the user name under which to run the Appweb service.
Parameters:
httpMaHttp object created via maCreateHttp.
userUser 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
int maStartHttp (MaHttp *http)

Start Http services.

Description:
This starts listening for requests on all configured servers.
Parameters:
httpMaHttp 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
int maStopHttp (MaHttp *http)

Stop Http services.

Description:
This stops listening for requests on all configured servers. Shutdown is somewhat graceful.
Parameters:
httpMaHttp 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

MaLimits

Server limits.

API Stability:
Evolving.
See Also:
Fields:
intmaxBody Max size of an incoming request.
intmaxChunkSize Max chunk size for transfer encoding.
intmaxHeader Max size of the total header.
intmaxNumHeaders Max number of lines of header.
intmaxResponseBody Max size of generated response content.
intmaxStageBuffer Max buffering by any pipeline stage.
intmaxThreads Max number of pool threads.
intmaxUploadSize Max size of an uploaded file.
intmaxUrl Max size of a URL.
intminThreads Min number of pool threads.
intthreadStackSize Stack size for each pool thread.

MaListen

MaListen

Listen endpoint.

API Stability:
Evolving.
See Also:
Fields:
intflags Listen flags.
char *ipAddr IP address on which to listen.
intport Port number to listen on.
struct MaServer *server Server owning this listening endpoint.
MprSocket *sock Underlying socket.
struct MprSsl *ssl SSL configuration.

MaLocation

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.
intflags 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.
intprefixLen Length of the prefix name.
intsessionTimeout Session timeout for this location.
struct MprSsl *ssl SSL configuration.

MaMimeType

MaMimeType

Mime Type hash table entry (the URL extension is the key).

API Stability:
Evolving.
See Also:
Fields:

MaPacket

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.
intcount Count of bytes in packet.
intflags 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.
MaPacket * maCreateDataPacket (struct MaConn *conn, int size)

Create a data packet.

Description:
Create a packet and set the MA_PACKET_DATA flag Data packets convey data through the response pipeline.
Parameters:
connMaConn connection object.
sizeSize of the package data storage.
Returns:
MaPacket object.
See Also:
MaPacket, MaQueue, maCreateEndPacket, maCreateHeaderPacket, maCreatePacket, maGetPacketLength, maJoinPacket, maSplitPacket
MaPacket * maCreateEndPacket (struct MaConn *conn)

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:
connMaConn connection object.
Returns:
MaPacket object.
See Also:
MaPacket, MaQueue, maCreateHeaderPacket, maCreatePacket, maGetPacketLength, maJoinPacket, maSplitPacket
MaPacket * maCreateHeaderPacket (struct MaConn *conn)

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:
connMaConn connection object.
Returns:
MaPacket object.
See Also:
MaPacket, MaQueue, maCreateEndPacket, maCreatePacket, maGetPacketLength, maJoinPacket, maSplitPacket
MaPacket * maCreatePacket (struct MaConn *conn, int size)

Create a data packet.

Description:
Create a packet of the required size.
Parameters:
connMaConn connection object.
sizeSize of the package data storage.
Returns:
MaPacket object.
See Also:
MaPacket, MaQueue, maCreateEndPacket, maCreateHeaderPacket, maGetPacketLength, maJoinPacket, maSplitPacket
int maGetPacketLength (MaPacket *packet)

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:
packetPacket to examine.
Returns:
Count of bytes contained by the packet.
See Also:
MaPacket, MaQueue, maCreateEndPacket, maCreateHeaderPacket, maCreatePacket, maJoinPacket, maSplitPacket
int maJoinPacket (MaPacket *packet, MaPacket *other)

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:
packetDestination packet.
otherOther packet to copy data from.
Returns:
Zero if successful, otherwise a negative Mpr error code.
See Also:
MaPacket, MaQueue, maCreateEndPacket, maCreateHeaderPacket, maCreatePacket, maGetPacketLength, maSplitPacket
MaPacket * maSplitPacket (struct MaConn *conn, MaPacket *packet, int offset)

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:
connMaConn connection object.
packetPacket to split.
offsetLocation 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.
See Also:
MaPacket, MaQueue, maCreateEndPacket, maCreateHeaderPacket, maCreatePacket, maGetPacketLength, maJoinPacket

MaQueue

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:
MaQueueCloseclose Close the queue.
struct MaConn *conn Connection ownning this queue.
intcount Bytes in queue.
intdirection Flow direction.
MaPacket *first First packet in queue (singly linked).
intflags Queue flags.
intioCount Count of bytes in iovec.
intioFileEntry Has file entry in iovec.
intioFileOffset The next file position to use.
intioIndex Next index into iovec.
MaPacket *last Last packet in queue (tail pointer).
intlow Low water mark for flow control.
intmax Maxiumum queue size.
struct MaQueue *nextQ Downstream queue for next stage.
MaQueueOpenopen Open the queue.
cchar *owner Name of owning stage.
intpacketSize 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.
MaQueueDataput 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.
MaQueueServiceservice Service the queue.
struct MaStage *stage Stage owning this queue.
void maDisableQueue (MaQueue *q)

Disable a queue.

Description:
Mark a queue as disabled so that it will not be scheduled for service.
Parameters:
qQueue 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
void maDiscardData (MaQueue *q, bool removePackets)

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:
qQueue reference.
removePacketsIf 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
void maEnableQueue (MaQueue *q)

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:
qQueue 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
MaPacket * maGet (MaQueue *q)

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:
qQueue 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
int maGetQueueRoom (MaQueue *q)

Get the room in the queue.

Description:
Get the amount of data the queue can accept before being full.
Parameters:
qQueue 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
bool maIsQueueEmpty (MaQueue *q)

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:
qQueue 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
void maJoinForService (MaQueue *q, MaPacket *packet, bool serviceQ)

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:
qQueue reference.
packetPacket to join to the queue.
serviceQIf 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
bool maPacketTooBig (MaQueue *q, MaPacket *packet)

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:
qQueue reference.
packetPacket 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
void maPut (MaQueue *q, MaPacket *packet)

Put a packet onto a queue.

Description:
Put the packet onto the end of queue by calling the queue's put() method.
Parameters:
qQueue reference.
packetPacket 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
void maPutBack (MaQueue *q, MaPacket *packet)

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:
qQueue reference.
packetPacket 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
void maPutForService (MaQueue *q, MaPacket *packet, bool serviceQ)

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:
qQueue reference.
packetPacket to join to the queue.
serviceQIf true, schedule the queue for service.
Description:
Put the packet onto the service queue and optionally schedule the queue for service.
Parameters:
qQueue reference.
packetPacket 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
void maPutNext (MaQueue *q, MaPacket *packet)

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:
qQueue reference. The packet will not be queued on this queue, but rather on the queue downstream.
packetPacket 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
void maRemoveQueue (MaQueue *q)

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:
qQueue 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
int maResizePacket (MaQueue *q, MaPacket *packet, int size)

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:
qQueue reference.
packetPacket to put.
sizeIf 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
void maScheduleQueue (MaQueue *q)

Schedule a queue.

Description:
Schedule a queue by adding it to the schedule queue. Queues are serviced FIFO.
Parameters:
qQueue 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
void maSendEndPacket (MaQueue *q)

Send an end packet.

Description:
Create and send an end-of-stream packet downstream.
Parameters:
qQueue 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
void maSendPackets (MaQueue *q)

Send all queued packets.

Description:
Send all queued packets downstream.
Parameters:
qQueue 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
void maServiceQueue (MaQueue *q)

Service a queue.

Description:
Service a queue by invoking its service() routine.
Parameters:
qQueue 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
bool maWillNextQueueAccept (MaQueue *q, MaPacket *packet)

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:
qQueue reference.
packetPacket 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
int maWrite (MaQueue *q, cchar *fmt, ...)

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:
qQueue reference.
fmtPrintf 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
int maWriteBlock (MaQueue *q, cchar *buf, int size, bool block)

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:
qQueue reference.
bufBuffer containing the write data.
sizeof the data in buf.
blockSet 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
int maWriteString (MaQueue *q, cchar *s)

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:
qQueue reference.
sString 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

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:
intend End byte of range + 1.
intlen Redundant range length.
struct MaRange *next Next range.
intstart Start of range.

MaRequest

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.
intflags 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.
boolifMatch If-Match processing requested.
boolifModified If-Modified processing requested.
MprList *inputPipeline Input processing.
MaRange *inputRange Specified range for input (post) data.
intlength Declared content length (ENV: CONTENT_LENGTH).
MaLocation *location Location block.
intmethod 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.
intreceivedContent Length of content actually received.
char *referer Refering URL.
intremainingChunk Remaining chunk data to read.
intremainingContent Remaining content data to read.
MprTimesince 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.
void maAddFormVars (MaConn *conn, cchar *buf, int len)

Add form variables.

Description:
Add new form variables encoded in the supplied buffer.
Parameters:
connMaConn connection object.
bufBuffer containing www-urlencoded data.
lenLength of buf.
See Also:
MaConn, MaRequest, MaResponse, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar
int maCompareFormVar (MaConn *conn, cchar *var, cchar *value)

Compare a form variable.

Description:
Compare a form variable and return true if it exists and its value matches.
Parameters:
connMaConn connection object.
varName of the form variable.
valueValue to compare.
Returns:
True if the value matches.
See Also:
MaConn, MaRequest, MaResponse, maAddFormVars, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar
cchar * maGetCookies (MaConn *conn)

Get the cookies.

Description:
Get the cookies defined in the current requeset.
Parameters:
connMaConn connection object.
Returns:
Return a string containing the cookies sent in the Http header of the last request.
See Also:
MaConn, MaRequest, MaResponse, maAddFormVars, maCompareFormVar, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar
cchar * maGetFormVar (MaConn *conn, cchar *var, cchar *defaultValue)

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:
connMaConn connection object.
varName of the form variable to retrieve.
defaultValueDefault value to return if the variable is not defined. Can be null.
Returns:
String containing the form variable's value. Caller should not free.
See Also:
MaConn, MaRequest, MaResponse, maAddFormVars, maCompareFormVar, maGetCookies, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar
int maGetIntFormVar (MaConn *conn, cchar *var, int defaultValue)

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:
connMaConn connection object.
varName of the form variable to retrieve.
defaultValueDefault value to return if the variable is not defined. Can be null.
Returns:
Integer containing the form variable's value.
See Also:
MaConn, MaRequest, MaResponse, maAddFormVars, maCompareFormVar, maGetCookies, maGetFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar
cchar * maGetQueryString (MaConn *conn)

Get the request query string.

Description:
Get query string sent with the current request.
Parameters:
connMaConn connection object.
Returns:
String containing the request query string. Caller should not free.
See Also:
MaConn, MaRequest, MaResponse, maAddFormVars, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maSetFormVar, maSetIntFormVar, maTestFormVar
void maSetFormVar (MaConn *conn, cchar *var, cchar *value)

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:
connMaConn connection object.
varName of the form variable to retrieve.
valueDefault value to return if the variable is not defined. Can be null.
See Also:
MaConn, MaRequest, MaResponse, maAddFormVars, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetIntFormVar, maTestFormVar
void maSetIntFormVar (MaConn *conn, cchar *var, int value)

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:
connMaConn connection object.
varName of the form variable to retrieve.
valueDefault value to return if the variable is not defined. Can be null.
See Also:
MaConn, MaRequest, MaResponse, maAddFormVars, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maTestFormVar
int maTestFormVar (MaConn *conn, cchar *var)

Test if a form variable is defined.

Parameters:
connMaConn connection object.
varName of the form variable to retrieve.
Returns:
True if the form variable is defined.
See Also:
MaConn, MaRequest, MaResponse, maAddFormVars, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar

MaResponse

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.
intbytesWritten Bytes written including headers.
intchunkSize Chunk size to use when using transfer encoding.
intcode HTTP response code.
struct MaConn *conn Current connection object.
MaStage *connector Response connector.
MaRange *currentRange Current range being fullfilled.
intentityLength Original content length before range subsetting.
char *etag Unique identifier tag.
cchar *extension Filename extension.
MprFile *file File to be served.
MprPathfileInfo File information if there is a real file to serve.
char *filename Name of a real file being served.
intflags 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.
intheaderSize Size of the header written.
intlength Response content length.
cchar *mimeType Mime type of the response document.
MprList *outputPipeline Output processing.
intpos Current I/O position.
MaQueuequeue[2] Dummy head for the response queues.
char *rangeBoundary Inter-range boundary.
void maDontCacheResponse (MaConn *conn)

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:
connMaConn connection object.
See Also:
MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
void maFailRequest (MaConn *conn, int code, cchar *fmt, ...)

Fail a request.

Description:
Fail a request with the specified http status code. The formatted message is logged to the appweb error log.
Parameters:
connMaConn connection object.
codeHttp status code.
fmtPrintf style formatted string.
...Arguments for fmt.
See Also:
MaConn, MaRequest, MaResponse, maFormatBody, maSetCookie
void maFillHeaders (MaConn *conn, MaPacket *packet)

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:
connMaConn connection object.
packetPacket into which to place the headers.
See Also:
MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
int maFormatBody (MaConn *conn, cchar *title, cchar *fmt, ...)

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:
connMaConn connection object.
titleTitle string to format into the HTML response body.
fmtPrintf 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
void maRedirect (MaConn *conn, int code, cchar *uri)

Redirect the client.

Description:
Redirect the client to a new uri.
Parameters:
connMaConn connection object.
codeHttp status code to send with the response.
uriNew uri for the client.
See Also:
MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
void maSetCookie (MaConn *conn, cchar *name, cchar *value, cchar *path, cchar *domain, int lifetime, bool secure)

Set a response cookie.

Description:
Define a cookie to send in the response Http header.
Parameters:
connMaConn connection object.
nameCookie name.
valueCookie value.
pathURI path to which the cookie applies.
domainDomain in which the cookie applies. Must have 2-3 dots.
lifetimeDuration for the cookie to persist in seconds.
secureSet to true if the cookie only applies for SSL based connections.
See Also:
MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody
void maSetHeader (MaConn *conn, bool allowMultiple, cchar *key, cchar *fmt, ...)

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:
connMaConn connection object.
allowMultipleIf true, allow duplicate keys of the same value.
keyHttp response header key.
fmtPrintf style formatted string to use as the header key value.
...Arguments for fmt.
See Also:
MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
void maSetResponseCode (MaConn *conn, int code)

Set a Http response code.

Description:
Set the Http response code for the request. This defaults to 200 (OK).
Parameters:
connMaConn connection object.
codeHttp status code.
See Also:
MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie
void maSetResponseMimeType (MaConn *conn, cchar *mimeType)

Set the response mime type.

Description:
Set the response mime type Http header.
Parameters:
connMaConn connection object.
mimeTypeMime type string.
See Also:
MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie

MaServer

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:
boolalreadyLogging 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.
intmaxConcurrentRequests Maximum number of clients.
char *name Unique name for this server.
char *serverRoot Server root.
int maConfigureServer (MprCtx ctx, MaHttp *http, MaServer *server, cchar *configFile, cchar *ipAddr, int port, cchar *documentRoot)

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:
ctxAny memory context object returned by mprAlloc.
httpMaHttp object created via maCreateHttp.
serverMaServer object created via maCreateServer.
configFileFile name of the Appweb configuration file (appweb.conf) that defines the web server configuration.
ipAddrIf using a config file, set to null. Otherwise, set to a host name or IP address.
portIf using a config file, set to -1. Otherwise, set to the port number to listen on.
documentRootIf 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.
See Also:
MaServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer, maServiceWebServer
MaServer * maCreateServer (MaHttp *http, cchar *name, cchar *root, cchar *ipAddr, int port)

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:
httpHttp object returned from maCreateHttp.
nameName of the web server. This name is used as the initial server name.
rootServer root directory.
ipAddrIf 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.
portPort 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.
See Also:
MaServer, maConfigureServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer, maServiceWebServer
MaHttp * maCreateWebServer (cchar *configFile)

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:
configFileFile name of the Appweb configuration file (appweb.conf) that defines the web server configuration.
Returns:
MaHttp object.
See Also:
MaServer, maConfigureServer, maCreateServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer, maServiceWebServer
void maLoadStaticModules (MaHttp *http)

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:
httpMaHttp object created via maCreateHttp.
See Also:
MaServer, maConfigureServer, maCreateServer, maCreateWebServer, maRunSimpleWebServer, maRunWebServer, maServiceWebServer
int maRunSimpleWebServer (cchar *ipAddress, int port, cchar *docRoot)

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:
ipAddressIP address on which to listen. Set to "0.0.0.0" to listen on all interfaces.
portPort number to listen to.
docRootDirectory containing the documents to serve.
Returns:
Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
See Also:
MaServer, maConfigureServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunWebServer, maServiceWebServer
int maRunWebServer (cchar *configFile)

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:
configFileFile 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.
See Also:
MaServer, maConfigureServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maServiceWebServer
int maServiceWebServer (MaHttp *http)

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:
httpHttp object created via maCreateWebServer or maCreateHttp.
Returns:
Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
See Also:
MaServer, maConfigureServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer

MaStage

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 qQueue instance object .
intflags Stage flags.
void(*incomingData)(MaQueue *q, MaPacket *packet) Process incoming data. Description:Accept an incoming packet of data qQueue instance object packetPacket of data .
void(*incomingService)(MaQueue *q) Service the incoming data queue. qQueue 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. connMaConn connection object stageStage object uriCurrent 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. qQueue instance object .
void(*outgoingData)(MaQueue *q, MaPacket *packet) Process outgoing data. Description:Accept a packet as outgoing data qQueue instance object packetPacket of data .
void(*outgoingService)(MaQueue *q) Service the outgoing data queue. qQueue instance object .
int(*parse)(MaHttp *http, cchar *key, char *value, MaConfigState *state) Parse configuration data. Description:This is invoked when parsing appweb configuration files httpMaHttp object keyConfiguration directive name valueConfiguration directive value stateCurrent 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. qQueue instance object .
void *stageData Per-stage data.
MaStage * maCreateConnector (MaHttp *http, cchar *name, int flags)

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:
httpMaHttp object returned from maCreateHttp.
nameName of connector stage.
flagsStage 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.
See Also:
MaConn, MaQueue, MaStage, maCreateFilter, maCreateHandler, maDefaultOutgoingServiceStage, maLookupStageData
MaStage * maCreateFilter (MaHttp *http, cchar *name, int flags)

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:
httpMaHttp object returned from maCreateHttp.
nameName of connector stage.
flagsStage 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.
See Also:
MaConn, MaQueue, MaStage, maCreateConnector, maCreateHandler, maDefaultOutgoingServiceStage, maLookupStageData
MaStage * maCreateHandler (MaHttp *http, cchar *name, int flags)

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:
httpMaHttp object returned from maCreateHttp.
nameName of connector stage.
flagsStage 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.
See Also:
MaConn, MaQueue, MaStage, maCreateConnector, maCreateFilter, maDefaultOutgoingServiceStage, maLookupStageData
void maDefaultOutgoingServiceStage (MaQueue *q)

Default outgoing data handling.

Description:
This routine provides default handling of outgoing data for stages. It simply sends all packets downstream.
Parameters:
qQueue object.
See Also:
MaConn, MaQueue, MaStage, maCreateConnector, maCreateFilter, maCreateHandler, maLookupStageData
void * maLookupStageData (MaHttp *http, cchar *name)

Lookup stage data.

Description:
This looks up the stage by name and returns the private stage data.
Parameters:
httpMaHttp object returned from maCreateHttp.
nameName of the stage concerned.
Returns:
Reference to the stage data block.
See Also:
MaConn, MaQueue, MaStage, maCreateConnector, maCreateFilter, maCreateHandler, maDefaultOutgoingServiceStage

MaUploadFile

MaUploadFile

Upload File.

API Stability:
Evolving.
See Also:
Fields:

Functions

Typedefs