Http API API

Extensions

Http Http service object.
HttpAuth Authorization.
HttpCache Cache Control.
HttpDir Directory object for the DirHandler.
HttpEndpoint Listening endpoints.
HttpHost Host Object.
HttpLimits Http limits.
HttpMonitor Monitor control structure.
HttpNet Control object for the network connection.
HttpPacket Packet object.
HttpQueue Queue object.
HttpRange Content range structure.
HttpRoute Route Control.
HttpRx Http Rx.
HttpSession Session state object.
HttpStage Pipeline Stages.
HttpStats HttpStats.
HttpStream Http request stream.
HttpTrace Trace management structure.
HttpTx Http Tx.
HttpUploadFile Upload File.
HttpUri URI management.
HttpWebSocket WebSocket Service to implement the WebSockets RFC 6455 specification for client and server communications.

Functions

HttpNet *httpAccept(HttpEndpoint *endpoint, MprEvent *event)
 Accept a new connection.
inthttpAddBodyParams(HttpStream *stream)
 Add parameters from the request body content.
voidhttpAddCache(struct HttpRoute *route, cchar *methods, cchar *uris, cchar *extensions, cchar *types, MprTicks clientLifespan, MprTicks serverLifespan, int flags)
 Add caching for response content.
HttpParseCallbackhttpAddConfig(cchar *key, HttpParseCallback callback)
 Add a configuration file callback for a property key.
inthttpAddCounter(cchar *name)
 Add a counter to be monitored.
inthttpAddDefense(cchar *name, cchar *remedy, cchar *args)
 Add a defense.
inthttpAddDefenseFromJson(cchar *name, cchar *remedy, MprJson *jargs)
 Add a defense using JSON arguments.
voidhttpAddHeader(HttpStream *stream, cchar *key, cchar *fmt, ...) PRINTF_ATTRIBUTE(3
 Add a header to the transmission using a format string.
void voidhttpAddHeaderString(HttpStream *stream, cchar *key, cchar *value)
 Add a header to the transmission.
voidhttpAddHostToEndpoint(HttpEndpoint *endpoint, struct HttpHost *host)
 Add a host to an endpoint.
voidhttpAddInputEndPacket(HttpStream *stream, HttpQueue *q)
 Add an END packet to the input queue.
voidhttpAddJsonParams(HttpStream *stream)
 Add parameters from a JSON body.
inthttpAddMonitor(cchar *counter, cchar *expr, uint64 limit, MprTicks period, cchar *defenses)
 Add a monitor.
voidhttpAddOption(MprHash *options, cchar *field, cchar *value)
 Add an option to the options table.
voidhttpAddPermResource(HttpRoute *parent, cchar *resource)
 Add routes for a permanent resource.
voidhttpAddPostGroup(HttpRoute *parent, cchar *resource)
 Add routes that use POST methods to enable extra parameters to be included in the body.
voidhttpAddQueryParams(HttpStream *stream)
 Add parameters from the request query string.
inthttpAddRemedy(cchar *name, HttpRemedyProc remedy)
 Add a remedy.
voidhttpAddResource(HttpRoute *parent, cchar *resource)
 Add routes for a resource.
voidhttpAddResourceGroup(HttpRoute *parent, cchar *resource)
 Add routes for a group of resources.
HttpRoute *httpAddRestfulRoute(HttpRoute *parent, cchar *methods, cchar *pattern, cchar *target, cchar *resource)
 Define a RESTful route.
HttpRole *httpAddRole(HttpAuth *auth, cchar *role, cchar *abilities)
 Add a role.
inthttpAddRoute(HttpHost *host, HttpRoute *route)
 Add a route to a host.
inthttpAddRouteCondition(HttpRoute *route, cchar *name, cchar *details, int flags)
 Add a route condition.
voidhttpAddRouteErrorDocument(HttpRoute *route, int status, cchar *uri)
 Add an error document.
inthttpAddRouteFilter(HttpRoute *route, cchar *name, cchar *extensions, int direction)
 Add a route filter.
inthttpAddRouteHandler(HttpRoute *route, cchar *name, cchar *extensions)
 Add a route handler.
voidhttpAddRouteIndex(HttpRoute *route, cchar *path)
 Set the route index document.
inthttpAddRouteLanguageDir(HttpRoute *route, cchar *language, cchar *path)
 Add a route language directory.
inthttpAddRouteLanguageSuffix(HttpRoute *route, cchar *language, cchar *suffix, int flags)
 Add a route language suffix.
voidhttpAddRouteMapping(HttpRoute *route, cchar *extensions, cchar *mappings)
 Add a route mapping.
voidhttpAddRouteMethods(HttpRoute *route, cchar *methods)
 Add HTTP methods for the route.
voidhttpAddRouteParam(HttpRoute *route, cchar *field, cchar *value, int flags)
 Add a route param check.
voidhttpAddRouteRequestHeaderCheck(HttpRoute *route, cchar *header, cchar *value, int flags)
 Add a request header check.
voidhttpAddRouteResponseHeader(HttpRoute *route, int cmd, cchar *header, cchar *value)
 Add a response header.
voidhttpAddRouteSet(HttpRoute *route, cchar *set)
 Add a route set.
inthttpAddRouteUpdate(HttpRoute *route, cchar *name, cchar *details, int flags)
 Add a route update rule.
inthttpAddSecurityToken(HttpStream *stream, bool recreate)
 Add the security token to the response.
voidhttpAddSpaGroup(HttpRoute *parent, cchar *resource)
 Add routes for a group of resources for use by a single page application.
HttpUser *httpAddUser(HttpAuth *auth, cchar *user, cchar *password, cchar *abilities)
 Add a user.
HttpRoute *httpAddWebSocketsRoute(HttpRoute *route, cchar *action)
 Add a route using the WebSockets filter.
voidhttpAdjustPacketEnd(HttpPacket *packet, MprOff size)
 Adjust the packet end position.
voidhttpAdjustPacketStart(HttpPacket *packet, MprOff size)
 Adjust the packet starting position.
HttpSession *httpAllocSession(HttpStream *stream, cchar *id, MprTicks lifespan)
 Allocate a new session state object.
voidhttpAppendHeader(HttpStream *stream, cchar *key, cchar *fmt, ...) PRINTF_ATTRIBUTE(3
 Append a transmission header.
void voidhttpAppendHeaderString(HttpStream *stream, cchar *key, cchar *value)
 Append a transmission header string.
inthttpApplyChangedGroup(void)
 Apply the changed group ID.
inthttpApplyChangedUser(void)
 Apply the changed user ID.
inthttpApplyUserGroup(void)
 Apply the changed user and group ID.
boolhttpAuthenticate(HttpStream *stream)
 Authenticate a user based on session data.
voidhttpBadRequestError(HttpStream *stream, int status, cchar *fmt, ...) PRINTF_ATTRIBUTE(3
 Emit an error message for a badly formatted request.
inthttpBanClient(cchar *ip, MprTicks period, int status, cchar *msg)
 Ban a client IP from service.
boolhttpCanUser(HttpStream *stream, cchar *abilities)
 Test if a user has the required abilities.
boolhttpCheckSecurityToken(HttpStream *stream)
 Check a security token.
voidhttpClearRouteStages(HttpRoute *route, int direction)
 Clear the pipeline stages for the route.
boolhttpClientStream(HttpStream *stream)
 Test if the connection is a client-side connection.
HttpHost *httpCloneHost(HttpHost *parent)
 Clone a host.
HttpLimits *httpCloneLimits(HttpLimits *base)
 Clone a limits object.
HttpPacket *httpClonePacket(HttpPacket *orig)
 Clone a packet.
HttpStage *httpCloneStage(HttpStage *stage)
 Create a clone of an existing state.
HttpUri *httpCloneUri(HttpUri *base, int flags)
 Clone a URI.
void voidhttpClosePipeline(HttpStream *stream)
 Destroy the request pipeline.
voidhttpCommonFormatter(HttpTrace *trace, cchar *event, cchar *type, int flags, cchar *buf, ssize len, cchar *fmt, va_list args)
 Common Log trace formatter.
HttpUri *httpCompleteUri(HttpUri *uri, HttpUri *other)
 Complete the given URI.
voidhttpComputeAllUserAbilities(HttpAuth *auth)
 Compute all the user abilities for a route using the given auth.
voidhttpComputeUserAbilities(HttpAuth *auth, HttpUser *user)
 Compute the user abilities for a given user in a route using the given auth.
boolhttpConfigure(HttpConfigureProc proc, void *arg, MprTicks timeout)
 Alter the configuration by first quiescing all Http activity.
inthttpConnect(HttpStream *stream, cchar *method, cchar *uri, struct MprSsl *ssl)
 Connect to a server and issue Http client request.
inthttpConnectNet(HttpNet *net, cchar *ip, int port, MprSsl *ssl)
 Connect the network to a remote peer.
boolhttpContentNotModified(HttpStream *stream)
 Test if the content has not been modified.
Http *httpCreate(int flags)
 Create a Http service object.
HttpRoute *httpCreateActionRoute(HttpRoute *parent, cchar *pattern, HttpAction action)
 Create a route for use with the Action Handler.
HttpRoute *httpCreateAliasRoute(HttpRoute *parent, cchar *pattern, cchar *path, int status)
 Create a route suitable for use as an alias.
HttpAuth *httpCreateAuth(void)
 Create an authentication object.
HttpAuthStore *httpCreateAuthStore(cchar *name, HttpVerifyUser verifyUser)
 Add an authorization store for password validation.
inthttpCreateAuthType(cchar *name, HttpAskLogin askLogin, HttpParseAuth parse, HttpSetAuth setAuth)
 Create an authorization protocol type.
voidhttpCreateCGIParams(HttpStream *stream)
 Create CGI parameters.
HttpEndpoint *httpCreateConfiguredEndpoint(struct HttpHost *host, cchar *home, cchar *documents, cchar *ip, int port)
 Create and configure a new endpoint.
HttpRoute *httpCreateConfiguredRoute(struct HttpHost *host, int serverSide)
 Create a configured route.
HttpStage *httpCreateConnector(cchar *name, MprModule *module)
 Create a connector stage.
HttpPacket *httpCreateDataPacket(ssize size)
 Create a data packet.
HttpHost *httpCreateDefaultHost(void)
 Create the default host.
HttpRoute *httpCreateDefaultRoute(struct HttpHost *host)
 Create a default route for a host.
HttpPacket *httpCreateEndPacket(void)
 Create an end-of-stream packet.
HttpEndpoint *httpCreateEndpoint(cchar *ip, int port, MprDispatcher *dispatcher)
 Create an endpoint object.
HttpPacket *httpCreateEntityPacket(MprOff pos, MprOff size, HttpFillProc fill)
 Create an entity data packet.
inthttpCreateEvent(uint64 streamSeqno, HttpEventProc callback, void *data)
 Invoke a callback on a stream using a stream sequence number.
HttpStage *httpCreateFilter(cchar *name, MprModule *module)
 Create a filter stage.
HttpStage *httpCreateHandler(cchar *name, MprModule *module)
 Create a request handler stage.
HttpPacket *httpCreateHeaderPacket(void)
 Create a response header packet.
HttpPacket *httpCreateHeaders(HttpQueue *q, HttpPacket *packet)
 Create a HTTP header packet.
HttpHost *httpCreateHost(void)
 Create a host.
HttpRoute *httpCreateInheritedRoute(HttpRoute *route)
 Create a route inherited from a parent route.
HttpLimits *httpCreateLimits(int serverSide)
 Create a new limits object.
HttpNet *httpCreateNet(MprDispatcher *dispatcher, struct HttpEndpoint *endpoint, int protocol, int flags)
 Create a network object.
HttpPacket *httpCreatePacket(ssize size)
 Create a data packet.
voidhttpCreatePipeline(HttpStream *stream)
 Create the pipeline.
HttpRoute *httpCreateRoute(struct HttpHost *host)
 Create a route for a host.
voidhttpCreateRxPipeline(HttpStream *stream, struct HttpRoute *route)
 Create the receive request pipeline.
HttpSession *httpCreateSession(HttpStream *stream)
 Create a session object.
HttpStage *httpCreateStage(cchar *name, int flags, MprModule *module)
 Create a connector stage.
HttpStream *httpCreateStream(HttpNet *net, bool peerCreated)
 Create a stream object.
HttpTrace *httpCreateTrace(HttpTrace *parent)
 Create a trace object.
HttpTx *httpCreateTx(HttpStream *stream, MprHash *headers)
 Create the tx object.
voidhttpCreateTxPipeline(HttpStream *stream, struct HttpRoute *route)
 Create the transmit request pipeline.
HttpUri *httpCreateUri(cchar *uri, int flags)
 Create and initialize a URI.
HttpUri *httpCreateUriFromParts(cchar *scheme, cchar *host, int port, cchar *path, cchar *reference, cchar *query, int flags)
 Create a URI from parts.
voidhttpDefaultIncoming(HttpQueue *q, HttpPacket *packet)
 Default stage incoming handling.
voidhttpDefaultOutgoing(HttpQueue *q, HttpPacket *packet)
 Default stage outgoing handling.
voidhttpDefaultService(HttpQueue *q)
 Default stage service routine handling.
voidhttpDefineAction(cchar *uri, HttpAction fun)
 Define a function procedure to invoke when the specified URI is requested.
HttpRoute *httpDefineRoute(HttpRoute *parent, cchar *methods, cchar *pattern, cchar *target, cchar *source)
 Define a route.
voidhttpDefineRouteCondition(cchar *name, HttpRouteProc *proc)
 Define a route condition rule.
HttpRouteSetProchttpDefineRouteSet(cchar *name, HttpRouteSetProc fn)
 Define a route set callback.
voidhttpDefineRouteTarget(cchar *name, HttpRouteProc *proc)
 Define a route target rule.
voidhttpDefineRouteUpdate(cchar *name, HttpRouteProc *proc)
 Define a route update rule.
voidhttpDestroy(void)
 Destroy the Http service.
voidhttpDestroyEndpoint(HttpEndpoint *endpoint)
 Destroy the endpoint.
voidhttpDestroyNet(HttpNet *net)
 Destroy the network object.
voidhttpDestroySession(HttpStream *stream)
 Destroy a session state object.
voidhttpDestroyStream(HttpStream *stream)
 Destroy the stream object.
voidhttpDestroyTx(HttpTx *tx)
 Destroy the tx object.
voidhttpDetailFormatter(HttpTrace *trace, cchar *event, cchar *type, int flags, cchar *buf, ssize len, cchar *fmt, va_list args)
 Detailed log trace formatter.
voidhttpDiscardData(HttpStream *stream, int dir)
 Discard buffered transmit pipeline data.
voidhttpDiscardQueueData(HttpQueue *q, bool removePackets)
 Discard all data from the queue.
voidhttpDiscardService(HttpQueue *q)
 Stage service routine that discards packets.
voidhttpDisconnectStream(HttpStream *stream)
 Disconnect the connection's socket.
voidhttpDumpCounters(void)
 Print the monitor counters to the error log.
voidhttpEaseLimits(HttpLimits *limits)
 Ease the limits.
voidhttpEnableNetEvents(HttpNet *net)
 Enable network events.
voidhttpEnableUpload(HttpStream *stream)
 Enable Multipart-Mime File Upload for this request.
voidhttpError(HttpStream *stream, int status, cchar *fmt, ...) PRINTF_ATTRIBUTE(3
 Error handling for the connection.
cchar *httpExpandRouteVars(HttpRoute *route, cchar *str)
 Expand route variables in a string.
voidhttpFinalize(HttpStream *stream)
 Indicate the request is finalized.
voidhttpFinalizeConnector(HttpStream *stream)
 Finalize connector output sending the response.
voidhttpFinalizeHttp2Stream(HttpStream *stream)
 Finalize a HTTP/2 stream when the connector output has sent the response.
voidhttpFinalizeInput(HttpStream *stream)
 Finalize receiption of the http content.
voidhttpFinalizeOutput(HttpStream *stream)
 Finalize transmission of the http response.
voidhttpFinalizeRoute(HttpRoute *route)
 Finalize a route.
void HttpStream *httpFindStream(uint64 seqno, HttpEventProc proc, void *data)
 Find a stream given a stream sequence number.
voidhttpFlush(HttpStream *stream)
 Flush transmit data.
voidhttpFlushAll(HttpStream *stream)
 Flush transmit data and wait for all the data to be written to the socket.
boolhttpFlushQueue(HttpQueue *q, int flags)
 Flush queue data.
voidhttpFollowRedirects(HttpStream *stream, bool follow)
 Follow redirctions.
voidhttpFormatError(HttpStream *stream, int status, cchar *fmt, ...) PRINTF_ATTRIBUTE(3
 Format an error transmission.
void ssizehttpFormatResponse(HttpStream *stream, cchar *fmt, ...) PRINTF_ATTRIBUTE(2
 Format an alternate response.
ssizehttpFormatResponseBody(HttpStream *stream, cchar *title, cchar *fmt, ...) PRINTF_ATTRIBUTE(3
 Format a response body.
void ssize ssizehttpFormatResponsev(HttpStream *stream, cchar *fmt, va_list args)
 Format an alternate response.
voidhttpFormatTrace(HttpTrace *trace, cchar *event, cchar *type, int flags, cchar *buf, ssize len, cchar *fmt, va_list args)
 Convenience routine to format trace via the configured formatter.
char *httpFormatUri(cchar *scheme, cchar *host, int port, cchar *path, cchar *ref, cchar *query, int flags)
 Format a URI.
boolhttpGetAsync(HttpNet *net)
 Get the async mode value for the network.
HttpAuthStore *httpGetAuthStore(cchar *name)
 Lookup an authentication store.
cchar *httpGetBodyInput(HttpStream *stream)
 Get the receive body input.
boolhttpGetBoolToken(cchar *tok)
 Parse a boolean token.
void ssizehttpGetChunkSize(HttpStream *stream)
 Get the preferred chunked size for transfer chunk encoding.
MprOffhttpGetContentLength(HttpStream *stream)
 Get the receive body content length.
void *httpGetContext(void)
 Get the http context object.
cchar *httpGetCookie(HttpStream *stream, cchar *name)
 Get a request cookie.
cchar *httpGetCookies(HttpStream *stream)
 Get the request cookies.
char *httpGetDateString(MprPath *sbuf)
 Get the time as an ISO date string.
HttpHost *httpGetDefaultHost(void)
 Get the default host defined via httpSetDefaultHost.
HttpRoute *httpGetDefaultRoute(HttpHost *host)
 Get the default route for a host.
cchar *httpGetDir(HttpRoute *route, cchar *name)
 Get a route directory variable.
HttpDir *httpGetDirObj(HttpRoute *route)
 Get the HttpDir object for a route.
void *httpGetEndpointContext(HttpEndpoint *endpoint)
 Get the endpoint context object.
cchar *httpGetError(HttpStream *stream)
 Get the error message associated with the last request.
char *httpGetExt(HttpStream *stream)
 Get a URI extension.
cchar *httpGetHeader(HttpStream *stream, cchar *key)
 Get an rx http header.
MprHash *httpGetHeaderHash(HttpStream *stream)
 Get the hash table of rx Http headers.
char *httpGetHeaders(HttpStream *stream)
 Get all the request http headers.
char *httpGetHeadersFromHash(MprHash *hash)
 Get a header string from the given hash.
HttpRoute *httpGetHostDefaultRoute(HttpHost *host)
 Return the default route for a host.
inthttpGetIntParam(HttpStream *stream, cchar *var, int defaultValue)
 Get a request parm as an integer.
inthttpGetKeepAliveCount(HttpStream *stream)
 Get the count of Keep-Alive requests that will be used for this stream object.
HttpLang *httpGetLanguage(HttpStream *stream, MprHash *spoken, cchar *defaultLang)
 Get the language to use for the request.
void *httpGetOption(MprHash *options, cchar *field, cchar *defaultValue)
 Extract a field value from an option string.
MprHash *httpGetOptionHash(MprHash *options, cchar *field)
 Get an option value that is itself an object (hash).
MprHash *httpGetOptions(cchar *options)
 Convert an options string into an options table.
HttpPacket *httpGetPacket(struct HttpQueue *q)
 Get the next packet from a queue.
ssizehttpGetPacketContents(HttpPacket *packet)
 Get the packet data contents.
ssizehttpGetPacketLength(HttpPacket *packet)
 Get the length of the packet data contents.
char *httpGetPacketStart(HttpPacket *packet)
 Get the start of the packet data contents.
char *httpGetPacketString(HttpPacket *packet)
 Get the packet data contents as a string.
cchar *httpGetParam(HttpStream *stream, cchar *var, cchar *defaultValue)
 Get a request param.
MprJson *httpGetParamObj(HttpStream *stream, cchar *var)
 Get a parameter as a JSON object.
MprJson *httpGetParams(HttpStream *stream)
 Get the request params table.
cchar *httpGetParamsString(HttpStream *stream)
 Get the request params table as a string.
char *httpGetPathExt(cchar *path)
 Get a path extension.
cchar *httpGetProtocol(HttpNet *net)
 Get the Http protocol variant for this network connection.
cchar *httpGetQueryString(HttpStream *stream)
 Get the request query string.
void *httpGetQueueData(HttpStream *stream)
 Get the queue data for the connection.
ssizehttpGetQueueRoom(HttpQueue *q)
 Get the room in the queue.
ssizehttpGetReadCount(HttpStream *stream)
 Get the number of bytes that can be read from the read queue.
HttpUri *httpGetRelativeUri(HttpUri *base, HttpUri *target, int clone)
 Get a relative URI from the base to the target.
void *httpGetRouteData(HttpRoute *route, cchar *key)
 Get extra route data.
cchar *httpGetRouteDocuments(HttpRoute *route)
 Get the route documents directory.
cchar *httpGetRouteHome(HttpRoute *route)
 Get the route home directory.
cchar *httpGetRouteMethods(HttpRoute *route)
 Get the route method list.
cchar *httpGetRouteTop(HttpStream *stream)
 Get a URL path to the top of the route from the current request (rx->pathInfo).
cchar *httpGetRouteVar(HttpRoute *route, cchar *key)
 Get a path token variable.
cchar *httpGetSecurityToken(HttpStream *stream, bool recreate)
 Get a unique security token.
HttpSession *httpGetSession(HttpStream *stream, int create)
 Get a session state object.
cchar *httpGetSessionID(HttpStream *stream)
 Get the session ID.
MprHash *httpGetSessionObj(HttpStream *stream, cchar *key)
 Get an object from the session state store.
cchar *httpGetSessionVar(HttpStream *stream, cchar *name, cchar *defaultValue)
 Get a session state variable.
cvoid *httpGetStageData(struct HttpStream *stream, cchar *key)
 Get stage data.
voidhttpGetStats(HttpStats *sp)
 Get the Http performance statistics.
inthttpGetStatus(HttpStream *stream)
 Get the response status.
cchar *httpGetStatusMessage(HttpStream *stream)
 Get the Http response status message.
void *httpGetStreamContext(HttpStream *stream)
 Get the connection context object.
inthttpGetStreamEventMask(HttpStream *stream)
 Get an IO event mask for events of interest to the connection.
void *httpGetStreamHost(HttpStream *stream)
 Get the connection host object.
boolhttpGetStreaming(struct HttpStream *stream)
 Determine if input body content should be streamed or buffered for requests with content of a given mime type.
inthttpGetTraceLevel(HttpTrace *trace)
 Get the current tracing level.
ssize cchar,*httpGetTxHeader(HttpStream *stream, cchar *key)
 Get a tx http header.
voidhttpGetUserGroup(void)
 Get the user group.
cchar *httpGetWebSocketCloseReason(HttpStream *stream)
 Get the close reason supplied by the peer.
void *httpGetWebSocketData(HttpStream *stream)
 Get the WebSocket private data.
ssizehttpGetWebSocketMessageLength(HttpStream *stream)
 Get the message length for the current message.
char *httpGetWebSocketProtocol(HttpStream *stream)
 Get the selected WebSocket protocol selected by the server.
ssizehttpGetWebSocketState(HttpStream *stream)
 Get the WebSocket state.
ssizehttpGetWriteQueueCount(HttpStream *stream)
 Get the count of bytes buffered on the write queue.
HttpLimits *httpGraduateLimits(HttpRoute *route, HttpLimits *limits)
 Graduate the limits from the parent route.
voidhttpHandleOptions(struct HttpStream *stream)
 Handle a Http Options method request.
voidhttpHideRoute(HttpRoute *route, bool on)
 Hide the route from route tables.
voidhttpIOEvent(struct HttpNet *net, MprEvent *event)
 Respond to a HTTP I/O event.
voidhttpInitConfig(HttpRoute *route)
 Initialize and prepare to load configuration files.
voidhttpInitLimits(HttpLimits *limits, bool serverSide)
 Initialize a limits object with default values.
inthttpInitParser(void)
 Initialize the Http configuration parser.
voidhttpInsertOption(MprHash *options, cchar *field, cchar *value)
 Add an option to the options table.
boolhttpIsAuthenticated(HttpStream *stream)
 Test if the user is authenticated.
inthttpIsChunked(HttpStream *stream)
 Return whether transfer chunked encoding will be used on this request.
inthttpIsEndpointAsync(HttpEndpoint *endpoint)
 Get if the endpoint is running in asynchronous mode.
boolhttpIsEof(struct HttpStream *stream)
 Test if the connection has received all incoming content.
inthttpIsFinalized(HttpStream *stream)
 Test if request has been finalized.
boolhttpIsLastPacket(HttpPacket *packet)
 Test if the packet is the last in a logical message.
inthttpIsOutputFinalized(HttpStream *stream)
 Test if request response has been fully generated.
boolhttpIsPacketTooBig(struct HttpQueue *q, HttpPacket *packet)
 Test if a packet is too big.
boolhttpIsQueueEmpty(HttpQueue *q)
 Determine if the queue is empty.
boolhttpIsQueueSuspended(HttpQueue *q)
 Test if a queue is suspended.
inthttpJoinPacket(HttpPacket *packet, HttpPacket *other)
 Join two packets.
voidhttpJoinPacketForService(struct HttpQueue *q, HttpPacket *packet, bool serviceQ)
 Join a packet onto the service queue.
voidhttpJoinPackets(HttpQueue *q, ssize size)
 Join packets together.
HttpUri *httpJoinUri(HttpUri *base, int argc, HttpUri **others)
 Join URIs.
HttpUri *httpJoinUriPath(HttpUri *result, HttpUri *base, HttpUri *other)
 Join a URI path.
voidhttpLimitError(HttpStream *stream, int status, cchar *fmt, ...) PRINTF_ATTRIBUTE(3
 Emit an error message for limit violations.
char *httpLink(struct HttpStream *stream, cchar *target)
 Create a URI link.
char *httpLinkAbs(struct HttpStream *stream, cchar *target)
 Create an absolute link that includes scheme and host.
char *httpLinkEx(struct HttpStream *stream, cchar *target, MprHash *options)
 Extended URI link creation.
inthttpLoadConfig(HttpRoute *route, cchar *path)
 Load a JSON configuration file.
boolhttpLog(HttpTrace *trace, cchar *event, cchar *type, cchar *fmt, ...)
 Log (trace) an event of interest.
voidhttpLogCompleteRequest(struct HttpStream *stream)
 Trace the completion of a request.
voidhttpLogRoutes(HttpHost *host, bool full)
 Show the current route table to the error log.
void voidhttpLogRxPacket(struct HttpNet *net, cchar *buf, ssize len)
 Trace a packet received from the network.
voidhttpLogTxPacket(struct HttpNet *net, ssize len)
 Trace packets sent to the network.
boolhttpLogin(HttpStream *stream, cchar *username, cchar *password)
 Log the user in.
voidhttpLogout(HttpStream *stream)
 Logout the user.
struct HttpEndpoint *httpLookupEndpoint(cchar *ip, int port)
 Lookup a listening endpoint.
struct HttpHost *httpLookupHost(cchar *name)
 Lookup a host by name.
struct HttpHost *httpLookupHostOnEndpoint(HttpEndpoint *endpoint, cchar *name)
 Lookup a host name.
cchar *httpLookupMimeType(cchar *ext)
 Get the mime type for an extension.
HttpRole *httpLookupRole(HttpAuth *auth, cchar *name)
 Lookup a role by name.
HttpRoute *httpLookupRoute(HttpHost *host, cchar *pattern)
 Lookup a route by pattern.
cchar *httpLookupRouteErrorDocument(HttpRoute *route, int status)
 Lookup an error document by HTTP status code.
boolhttpLookupSessionID(cchar *id)
 Lookup a session ID.
struct HttpStage *httpLookupStage(cchar *name)
 Lookup a stage by name.
void *httpLookupStageData(cchar *name)
 Lookup stage data.
cchar *httpLookupStatus(int status)
 Lookup a Http status code.
HttpUser *httpLookupUser(HttpAuth *auth, cchar *name)
 Lookup a user by username.
char *httpMakePath(HttpRoute *route, cchar *dir, cchar *path)
 Make a filename path.
HttpUri *httpMakeUriLocal(HttpUri *uri)
 Make a URI local.
cchar *httpMapContent(HttpStream *stream, cchar *filename)
 Map a content filename.
voidhttpMapFile(HttpStream *stream)
 Map the request URI to a filename in physical storage for a handler.
struct HttpHost *httpMatchHost(HttpNet *net, cchar *hostname)
 Match the HttpHost object that should serve this request.
boolhttpMatchParam(HttpStream *stream, cchar *var, cchar *expected)
 Match a form variable with an expected value.
MprSsl *httpMatchSsl(MprSocket *sp, cchar *hostname)
 Match the HttpHost object that should serve this request.
voidhttpMemoryError(HttpStream *stream)
 Signal a memory allocation error in a response to the peer.
int64httpMonitorEvent(struct HttpStream *stream, int counter, int64 adj)
 Monitor an event and validate against defined limits and monitored resources.
int64httpMonitorNetEvent(struct HttpNet *net, int counter, int64 adj)
 Monitor a network event and validate against defined limits and monitored resources.
boolhttpNeedRetry(HttpStream *stream, cchar **url)
 Determine if the transmission needs a transparent retry to implement authentication or redirection.
voidhttpNetError(HttpNet *net, cchar *fmt, ...)
 Error handling for the network.
voidhttpNetTimeout(HttpNet *net)
 Schedule a network connection timeout event on a network.
boolhttpNextQueueFull(HttpQueue *q)
 Test if the next queue is full.
HttpUri *httpNormalizeUri(HttpUri *uri)
 Normalize a URI.
char *httpNormalizeUriPath(cchar *uri)
 Normalize a URI.
voidhttpNotify(HttpStream *stream, int event, int arg)
 Inform notifiers of a connection event or state change.
voidhttpOmitBody(HttpStream *stream)
 Tell the tx to omit sending any body.
boolhttpOption(MprHash *options, cchar *field, cchar *value, int useDefault)
 Test a field value from an option string.
voidhttpParseAll(HttpRoute *route, cchar *key, MprJson *prop)
 Parse all the properties under the given key.
inthttpParsePlatform(cchar *platform, cchar **os, cchar **arch, cchar **profile)
 Parse a platform string.
voidhttpPrettyFormatter(HttpTrace *trace, cchar *event, cchar *type, int flags, cchar *buf, ssize len, cchar *fmt, va_list args)
 Pretty log trace formatter for debugging.
boolhttpPumpOutput(HttpQueue *q)
 Get more output by invoking the handler's writable callback.
voidhttpPutBackPacket(struct HttpQueue *q, HttpPacket *packet)
 Put a packet back onto a queue.
voidhttpPutForService(struct HttpQueue *q, HttpPacket *packet, bool serviceQ)
 Put a packet into the service queue for deferred processing.
voidhttpPutPacket(struct HttpQueue *q, HttpPacket *packet)
 Put a packet to the queue.
voidhttpPutPacketToNext(struct HttpQueue *qp, HttpPacket *packet)
 Put a packet to the next queue downstream.
boolhttpQueuesNeedService(HttpNet *net)
 Test if the network queues need service.
ssizehttpRead(HttpStream *stream, char *buffer, ssize size)
 Read rx body data.
ssizehttpReadBlock(HttpStream *stream, char *buffer, ssize size, MprTicks timeout, int flags)
 Read a block of rx body data.
boolhttpReadIO(HttpNet *net)
 Read input from a HTTP connected socket.
char *httpReadString(HttpStream *stream)
 Read response data as a string.
voidhttpReadyHandler(HttpStream *stream)
 Run the handler ready callback.
voidhttpRedirect(HttpStream *stream, int status, cchar *uri)
 Redirect the client.
voidhttpRemoveCookie(HttpStream *stream, cchar *name)
 Remove a cookie from the client (browser) This will emit a Set-Cookie response header with the value set to "" and a one second lifespan.
inthttpRemoveHeader(HttpStream *stream, cchar *key)
 Remove a header from the transmission.
voidhttpRemoveOption(MprHash *options, cchar *field)
 Remove an option.
voidhttpRemoveParam(HttpStream *stream, cchar *var)
 Remove a request param.
voidhttpRemoveQueue(HttpQueue *q)
 Remove a queue.
inthttpRemoveRole(HttpAuth *auth, cchar *role)
 Remove a role.
voidhttpRemoveRouteMethods(HttpRoute *route, cchar *methods)
 Remove HTTP methods for the route.
inthttpRemoveSessionVar(HttpStream *stream, cchar *name)
 Remove a session state variable.
inthttpRemoveUser(HttpAuth *auth, cchar *user)
 Remove a user.
voidhttpReplayPackets(HttpQueue *inq, HttpQueue *outq)
 Replay incoming packets through the pipeline.
HttpStream *httpRequest(cchar *method, cchar *uri, cchar *data, int protocol, char **err)
 Issue a http request.
boolhttpRequestExpired(HttpStream *stream, MprTicks timeout)
 Test if a request has exceeded its timeout limits.
voidhttpResetClientStream(HttpStream *stream, bool keepHeaders)
 Prepare a client connection for a new request.
voidhttpResetCredentials(HttpStream *stream)
 Reset the current security credentials.
voidhttpResetRouteIndexes(HttpRoute *route)
 Reset all defined indexes.
voidhttpResetRoutePipeline(HttpRoute *route)
 Reset the route pipeline.
voidhttpResetRoutes(HttpHost *host)
 Reset the list of routes for the host.
HttpPacket *httpResizePacket(struct HttpQueue *q, HttpPacket *packet, ssize size)
 Resize a packet.
HttpUri *httpResolveUri(struct HttpStream *stream, HttpUri *base, HttpUri *target)
 Resolve URIs relative to a base.
boolhttpResumeQueue(HttpQueue *q, bool force)
 Resume a queue.
voidhttpRouteRequest(HttpStream *stream)
 Route the request and select that matching route and handle to process the request.
voidhttpScheduleQueue(HttpQueue *q)
 Schedule a queue.
inthttpSecureEndpoint(HttpEndpoint *endpoint, struct MprSsl *ssl)
 Secure an endpoint.
inthttpSecureEndpointByName(cchar *name, struct MprSsl *ssl)
 Secure an endpoint by name.
ssizehttpSend(HttpStream *stream, cchar *fmt, ...) PRINTF_ATTRIBUTE(2
 Send a UTF-8 text message to the WebSocket peer.
ssizehttpSendBlock(HttpStream *stream, int type, cchar *msg, ssize len, int flags)
 Send a message of a given type to the WebSocket peer.
ssizehttpSendClose(HttpStream *stream, int status, cchar *reason)
 Send a close message to the WebSocket peer.
boolhttpServerStream(HttpStream *stream)
 Test if the connection is a server-side connection.
voidhttpServiceNetQueues(HttpNet *net, int flags)
 Service pipeline queues to flow data.
voidhttpSetAsync(HttpNet *net, bool async)
 Set the async mode value for the network.
voidhttpSetAuthAllow(HttpAuth *auth, cchar *ip)
 Allow access by a client IP IP address.
voidhttpSetAuthAnyValidUser(HttpAuth *auth)
 Allow access by any valid user.
voidhttpSetAuthDeny(HttpAuth *auth, cchar *ip)
 Deny access by a client IP address.
voidhttpSetAuthFormDetails(struct HttpRoute *route, cchar *loginPage, cchar *loginService, cchar *logoutService, cchar *loggedInPage, cchar *loggedOutPage)
 Define login service URLs for use with "form" authentication.
voidhttpSetAuthLogin(HttpAuth *auth, cchar *uri)
 Define the login page for use with authentication.
voidhttpSetAuthOrder(HttpAuth *auth, int order)
 Set the auth allow/deny order.
voidhttpSetAuthPermittedUsers(HttpAuth *auth, cchar *users)
 Define the set of permitted users.
voidhttpSetAuthQop(HttpAuth *auth, cchar *qop)
 Set the required quality of service for digest authentication.
voidhttpSetAuthRealm(HttpAuth *auth, cchar *realm)
 Set the required realm for basic or digest authentication.
voidhttpSetAuthRequiredAbilities(HttpAuth *auth, cchar *abilities)
 Set the required abilities for access.
voidhttpSetAuthSession(HttpAuth *auth, bool noSession)
 Control whether a session and session cookie will be created for user logins for this authentication route.
inthttpSetAuthStore(HttpAuth *auth, cchar *store)
 Set the authentication password store to use.
voidhttpSetAuthStoreSessions(HttpAuthStore *store, bool noSession)
 Control whether sessions and session cookies are created for user logins.
voidhttpSetAuthStoreVerify(HttpAuthStore *store, HttpVerifyUser verifyUser)
 Set the global verify callback for an authentication store.
voidhttpSetAuthStoreVerifyByName(cchar *storeName, HttpVerifyUser verifyUser)
 Set the global verify callback for an authentication store.
inthttpSetAuthType(HttpAuth *auth, cchar *proto, cchar *details)
 Set the authentication protocol type to use.
voidhttpSetAuthUsername(HttpAuth *auth, cchar *username)
 Set an automatic login username.
voidhttpSetAuthVerify(HttpAuth *auth, HttpVerifyUser verifyUser)
 Set the verify callback for an authentication object that is part of a route.
voidhttpSetCharSet(HttpStream *stream, cchar *charSet)
 Set the transmission (response) character set.
voidhttpSetChunkSize(HttpStream *stream, ssize size)
 Set the chunk size for transfer chunked encoding.
voidhttpSetContentLength(HttpStream *stream, MprOff length)
 Define a content length header in the transmission.
voidhttpSetContentType(HttpStream *stream, cchar *mimeType)
 Set the transmission (response) content mime type.
voidhttpSetContext(void *context)
 Set the http context object.
voidhttpSetCookie(HttpStream *stream, cchar *name, cchar *value, cchar *path, cchar *domain, MprTicks lifespan, int flags)
 Set a transmission cookie.
voidhttpSetCredentials(HttpStream *stream, cchar *user, cchar *password, cchar *authType)
 Set the Http credentials.
voidhttpSetDefaultClientHost(cchar *host)
 Define a default client host.
voidhttpSetDefaultClientPort(int port)
 Define a default client port.
voidhttpSetDefaultHost(HttpHost *host)
 Set the default host for all servers.
voidhttpSetDir(HttpRoute *route, cchar *name, cchar *value)
 Define a route directory path variable.
inthttpSetEndpointAddress(HttpEndpoint *endpoint, cchar *ip, int port)
 Set the endpoint IP address.
voidhttpSetEndpointAsync(HttpEndpoint *endpoint, int enable)
 Control if the endpoint is running in asynchronous mode.
voidhttpSetEndpointContext(HttpEndpoint *endpoint, void *context)
 Set the endpoint context object.
voidhttpSetEndpointNotifier(HttpEndpoint *endpoint, HttpNotifier fn)
 Define a notifier callback for this endpoint.
voidhttpSetEnvCallback(HttpEnvCallback envCallback)
 Define a callback to invoke after env vars have been defined.
voidhttpSetEof(HttpStream *stream)
 Set the HttpRx eof condition.
voidhttpSetFileHandler(HttpStream *stream, cchar *path)
 Set the "fileHandler" to process the request.
boolhttpSetFilename(HttpStream *stream, cchar *filename, int flags)
 Set the filename to serve for a request.
voidhttpSetForkCallback(MprForkCallback proc, void *arg)
 Set the fork callback.
inthttpSetGroupAccount(cchar *group)
 Set the group account.
voidhttpSetHandler(HttpStream *stream, HttpStage *handler)
 Set the handler for this request Use this request from the Handler rewrite callback to change the selected handler to process a request.
voidhttpSetHeader(HttpStream *stream, cchar *key, cchar *fmt, ...) PRINTF_ATTRIBUTE(3
 Set a transmission header.
void voidhttpSetHeaderString(HttpStream *stream, cchar *key, cchar *value)
 Set a simple key/value transmission header.
voidhttpSetHeadersCallback(struct HttpStream *stream, HttpHeadersCallback fn, void *arg)
 Define a headers callback.
voidhttpSetHostDefaultEndpoint(HttpHost *host, HttpEndpoint *endpoint)
 Set the default endpoint for a host.
voidhttpSetHostDefaultRoute(HttpHost *host, HttpRoute *route)
 Set the default route for a host.
inthttpSetHostName(HttpHost *host, cchar *name)
 Set the host name.
voidhttpSetHostProtocol(HttpHost *host, cchar *protocol)
 Set the host HTTP protocol version.
voidhttpSetHostRoot(HttpHost *host, cchar *root)
 Set the server root for a host.
voidhttpSetHostSecureEndpoint(HttpHost *host, HttpEndpoint *endpoint)
 Set the default secure endpoint for a host.
voidhttpSetIOCallback(struct HttpNet *net, HttpIOCallback fn)
 Define an I/O callback for network connections.
voidhttpSetIntParam(HttpStream *stream, cchar *var, int value)
 Set an integer request param value.
voidhttpSetJail(cchar *path)
 Remember the Chroot jail path.
voidhttpSetKeepAliveCount(HttpStream *stream, int count)
 Control Http Keep-Alive for the connection.
voidhttpSetMethod(HttpStream *stream, cchar *method)
 Set a new HTTP method for processing.
voidhttpSetNetCallback(HttpNet *net, HttpNetCallback callback)
 Define a network event callback.
voidhttpSetNetContext(HttpNet *net, void *context)
 Set the network context object.
voidhttpSetNetEof(HttpNet *net)
 Set the EOF flag in the network to indicate a peer disconnect.
voidhttpSetNetError(HttpNet *net)
 Set the error flag in the network to indicate a peer disconnect.
voidhttpSetNetProtocol(HttpNet *net, int protocol)
 Set the Http protocol variant for this network connection.
voidhttpSetOption(MprHash *options, cchar *field, cchar *value)
 Set an option.
voidhttpSetParam(HttpStream *stream, cchar *var, cchar *value)
 Set a request param value.
inthttpSetPlatform(cchar *platform)
 Set platform description.
inthttpSetPlatformDir(cchar *platform)
 Set platform directory location.
voidhttpSetProxy(cchar *host, int port)
 Define a Http proxy host to use for all client connect requests.
voidhttpSetQueueLimits(HttpQueue *q, HttpLimits *limits, ssize packetSize, ssize low, ssize max, ssize window)
 Set a queue's max packetSize and flow control low, max and window thresholds.
voidhttpSetRedirectCallback(HttpRedirectCallback redirectCallback)
 Define a callback to invoke on redirect requests.
voidhttpSetRequestCallback(HttpRequestCallback callback)
 Define a request completion callback.
voidhttpSetResponded(HttpStream *stream)
 Set the responded flag for the request.
voidhttpSetRouteAuth(HttpRoute *route, HttpAuth *auth)
 Set the route authentication.
voidhttpSetRouteAutoDelete(HttpRoute *route, bool on)
 Control file upload auto delete.
voidhttpSetRouteAutoFinalize(HttpRoute *route, bool on)
 Control auto finalize for a route.
inthttpSetRouteCanonicalName(HttpRoute *route, cchar *name)
 Set the route canonical name.
voidhttpSetRouteCharSet(HttpRoute *route, cchar *charSet)
 Set the default route character set.
inthttpSetRouteConnector(HttpRoute *route, cchar *name)
 Set the connector to use for a route.
voidhttpSetRouteCookie(HttpRoute *route, cchar *cookie)
 Set the route session cookie.
voidhttpSetRouteCookiePersist(HttpRoute *route, int enable)
 Persist the cookie to disk.
voidhttpSetRouteCookieSame(HttpRoute *route, cchar *value)
 Set the session cookie SameSite property.
voidhttpSetRouteData(HttpRoute *route, cchar *key, void *data)
 Set route data.
voidhttpSetRouteDefaultLanguage(HttpRoute *route, cchar *language)
 Set the default language for the route.
voidhttpSetRouteDocuments(HttpRoute *route, cchar *path)
 Set the route directory.
voidhttpSetRouteEnvEscape(HttpRoute *route, bool on)
 Define whether shell special characters are escaped in environment variables.
voidhttpSetRouteEnvPrefix(HttpRoute *route, cchar *prefix)
 Define a prefix string for environment variables.
voidhttpSetRouteFlags(HttpRoute *route, int flags)
 Update the route flags.
inthttpSetRouteHandler(HttpRoute *route, cchar *name)
 Set the handler to use for a route.
voidhttpSetRouteHome(HttpRoute *route, cchar *home)
 Set the route directory for configuration files.
voidhttpSetRouteIgnoreEncodingErrors(HttpRoute *route, bool on)
 Set the route to ignore UTF encoding errors for WebSocket connections.
voidhttpSetRouteMethods(HttpRoute *route, cchar *methods)
 Define the methods for the route.
voidhttpSetRoutePattern(HttpRoute *route, cchar *pattern, int flags)
 Set the route pattern.
voidhttpSetRoutePrefix(HttpRoute *route, cchar *prefix)
 Set the route prefix.
voidhttpSetRoutePreserveFrames(HttpRoute *route, bool on)
 Set the route to preserve WebSocket frames boundaries.
voidhttpSetRouteRenameUploads(HttpRoute *route, bool enable)
 Control the renaming of uploaded filenames.
voidhttpSetRouteSessionVisibility(HttpRoute *route, bool visible)
 Make session cookies that are visible to javascript.
voidhttpSetRouteShowErrors(HttpRoute *route, bool on)
 Define whether to show errors to the client.
voidhttpSetRouteSource(HttpRoute *route, cchar *source)
 Set the source code module for the route.
voidhttpSetRouteStealth(HttpRoute *route, bool on)
 Set stealth mode for the route.
inthttpSetRouteTarget(HttpRoute *route, cchar *name, cchar *details)
 Set a route target.
voidhttpSetRouteTemplate(HttpRoute *route, cchar *tplate)
 Set the route template.
voidhttpSetRouteUploadDir(HttpRoute *route, cchar *dir)
 Set the default upload directory for file uploads.
voidhttpSetRouteVar(HttpRoute *route, cchar *token, cchar *value)
 Define a route variable.
voidhttpSetRouteXsrf(HttpRoute *route, bool enable)
 Control whether an XSRF token will be emitted during a user login sequence.
voidhttpSetSessionNotify(MprCacheProc notifyProc)
 Set a notification callback to be invoked for session notification events.
inthttpSetSessionObj(HttpStream *stream, cchar *key, MprHash *value)
 Set an object into the session state store.
inthttpSetSessionVar(HttpStream *stream, cchar *name, cchar *value)
 Set a session variable.
voidhttpSetSoftware(cchar *description)
 Set the software description.
voidhttpSetStageData(struct HttpStream *stream, cchar *key, cvoid *data)
 Set stage data.
voidhttpSetState(HttpStream *stream, int state)
 Set the connection state and invoke notifiers.
voidhttpSetStatus(HttpStream *stream, int status)
 Set a Http response status.
voidhttpSetStreamContext(HttpStream *stream, void *context)
 Set the connection context object.
voidhttpSetStreamData(HttpStream *stream, void *data)
 Set the connection data field.
voidhttpSetStreamHost(HttpStream *stream, void *host)
 Set the connection host object.
voidhttpSetStreamNotifier(HttpStream *stream, HttpNotifier notifier)
 Define a notifier callback for this connection.
voidhttpSetStreamUser(HttpStream *stream, struct HttpUser *user)
 Set the logged in user associated with the connection.
voidhttpSetStreaming(struct HttpHost *host, cchar *mime, cchar *uri, bool streaming)
 Control if input body content should be streamed or buffered for requests with content of a given mime type and a URI path that starts with the specified URI prefix.
voidhttpSetTimeout(HttpStream *stream, MprTicks requestTimeout, MprTicks inactivityTimeout)
 Set the Http inactivity timeout.
voidhttpSetTimestamp(MprTicks period)
 Define a timestamp in the MPR log file.
voidhttpSetTraceContentSize(HttpTrace *trace, ssize size)
 Set the maximum content size to trace.
voidhttpSetTraceEventLevel(HttpTrace *trace, cchar *type, int level)
 Configure the tracing level for an event type.
voidhttpSetTraceFormat(HttpTrace *trace, cchar *format)
 Set the logging format.
HttpTraceFormatterhttpSetTraceFormatter(HttpTrace *trace, HttpTraceFormatter callback)
 Set the formatter callback to use with a trace object.
voidhttpSetTraceFormatterName(HttpTrace *trace, cchar *name)
 Define the trace formatter by name.
voidhttpSetTraceLevel(HttpTrace *trace, int level)
 Set the current tracing verbosity level.
inthttpSetTraceLogFile(HttpTrace *trace, cchar *path, ssize size, int backup, cchar *format, int flags)
 Configure the request trace log.
voidhttpSetTraceLogger(HttpTrace *trace, HttpTraceLogger callback)
 Set the trace callback to use with a trace object.
inthttpSetUri(HttpStream *stream, cchar *uri)
 Set a new URI for processing.
inthttpSetUserAccount(cchar *user)
 Set the user account.
voidhttpSetWebSocketData(HttpStream *stream, void *data)
 Set the WebSocket private data.
voidhttpSetWebSocketPreserveFrames(HttpStream *stream, bool on)
 Preserve frames for incoming messages.
voidhttpSetWebSocketProtocols(HttpStream *stream, cchar *protocols)
 Set a list of application-level protocols supported by the client.
boolhttpShouldRenderDirListing(HttpStream *stream)
 Test if a directory listing should be rendered for the request.
boolhttpShouldTrace(HttpTrace *trace, cchar *type)
 Should trace be emitted.
HttpPacket *httpSplitPacket(HttpPacket *packet, ssize offset)
 Split a data packet.
inthttpStartEndpoint(HttpEndpoint *endpoint)
 Start listening for client connections on an endpoint.
inthttpStartEndpoints(void)
 Start listening for client connections on all endpoints.
voidhttpStartPipeline(HttpStream *stream)
 Start the pipeline.
inthttpStartTracing(cchar *traceSpec)
 Start tracing for the given trace log file when instructed via a command line switch.
char *httpStatsReport(int flags)
 Get an Http performance report.
SockethttpStealSocketHandle(HttpNet *net)
 Steal the O/S socket handle from the network socket object.
voidhttpStopEndpoint(HttpEndpoint *endpoint)
 Stop the server listening for client connections.
voidhttpStopEndpoints(void)
 Stop listening for client connections on all endpoints.
voidhttpStreamTimeout(HttpStream *stream)
 Schedule a connection timeout event on a connection.
voidhttpSuspendQueue(HttpQueue *q)
 Suspend a queue.
char *httpTemplate(HttpStream *stream, cchar *tplate, MprHash *options)
 Expand a template string using given options.
inthttpTestParam(HttpStream *stream, cchar *var)
 Test if a request param is defined.
boolhttpTokenize(HttpRoute *route, cchar *str, cchar *fmt, ...)
 Tokenize a string based on route data.
boolhttpTokenizev(HttpRoute *route, cchar *str, cchar *fmt, va_list args)
 Tokenize a string based on route data.
voidhttpTransferPackets(HttpQueue *inq, HttpQueue *outq)
 Transfer packets from one queue to another.
voidhttpTrimExtraPath(HttpStream *stream)
 Trim extra path from the URI.
ssizehttpUpdateCache(HttpStream *stream, cchar *uri, cchar *data, MprTicks lifespan)
 Update the cached content for a URI.
inthttpUpgradeWebSocket(HttpStream *stream)
 Upgrade a client HTTP connection connection to use WebSockets.
char *httpUriToString(HttpUri *uri, int flags)
 Convert a Uri to a string.
boolhttpValidUriChars(cchar *uri)
 Test if a URI is using only valid characters Note this does not test if the URI is fully legal.
char *httpValidateUriPath(cchar *uri)
 Validate a URI path as expected in a HTTP request line.
boolhttpVerifyWebSocketsHandshake(HttpStream *stream)
 Verify the server handshake.
inthttpWait(HttpStream *stream, int state, MprTicks timeout)
 Wait for the client connection to achieve the requested state.
boolhttpWebSocketOrderlyClosed(HttpStream *stream)
 Test if WebSocket connection was orderly closed by sending an acknowledged close message.
boolhttpWillNextQueueAcceptPacket(HttpQueue *q, HttpPacket *packet)
 Determine if the downstream queue will accept this packet.
boolhttpWillNextQueueAcceptSize(HttpQueue *q, ssize size)
 Determine if the downstream queue will accept a certain amount of data.
boolhttpWillQueueAcceptPacket(HttpQueue *q, HttpQueue *nextQ, HttpPacket *packet)
 Determine if the given queue will accept this packet.
ssizehttpWrite(HttpQueue *q, cchar *fmt, ...) PRINTF_ATTRIBUTE(2
 Write a formatted string.
ssizehttpWriteBlock(HttpQueue *q, cchar *buf, ssize size, int flags)
 Write a block of data to the queue.
ssizehttpWriteCached(HttpStream *stream)
 Write the cached content for a URI to the client.
inthttpWriteSession(HttpStream *stream)
 Write the session state to persistent data storage.
ssizehttpWriteString(HttpQueue *q, cchar *s)
 Write a string of data to the queue.
voidhttpWriteTrace(HttpTrace *trace, cchar *buf, ssize len)
 Convenience routine to write data to the trace logger.
voidhttpWriteTraceLogFile(HttpTrace *trace, cchar *buf, ssize len)
 Write a message to the trace file logger.
ssizehttpWriteUploadData(HttpStream *stream, MprList *formData, MprList *fileData)
 Write Http upload body data.

Typedefs

HttpAddressPer-IP address structure that holds the monitor counters.
HttpAskLoginAuthType callback to generate a response requesting the user login This should call httpError if such a response cannot be generated.
HttpAuthStorePassword backend store.
HttpAuthTypeAuthentication Protocol.
HttpConfigureProcCallback procedure for HttpConfigure.
HttpCounterMonitoring counter.
HttpDefenseMonitor defense configuration.
HttpEnvCallbackSet environment vars callback.
HttpEventProcEvent callback function for httpCreateEvent.
HttpFillProcCallback procedure to fill a packet with data.
HttpHeaderTableHTTP HPACK header table.
HttpHeadersCallbackCallback to fill headers.
HttpIOCallbackI/O callback for network connections.
HttpLangLanguage definition record for routes.
HttpListenCallbackListen callback.
HttpNetCallbackNetwork event callback.
HttpNotifierHttpStream state change notification callback.
HttpParseAuthAuthType callback to parse the HTTP 'Authorize' (client) and 'www-authenticate' (server) headers.
HttpParseCallbackHttp JSON configuration parse callback.
HttpRedirectCallbackRedirect callback.
HttpRemedyProcDefense remedy callback.
HttpRequestCallbackRequest completion callback.
HttpRoleAuthorization Roles.
HttpRouteOpRoute operation record.
HttpRouteProcGeneral route procedure.
HttpRouteSetProcRouteSet callback.
HttpSetAuthAuthType callback to set the necessary HTTP authorization headers for a client request.
HttpTimeoutCallbackTimeout callback.
HttpTraceFormatterTrace formatter callback.
HttpTraceLoggerTrace logger callback.
HttpUserUser Authorization.
HttpVerifyUserAuthStore callback Verify the user credentials.

Defines

#defineHTTP2_DEFAULT_WEIGHT   16
 Unused.
#defineHTTP2_FRAME_OVERHEAD   9
 Minimum HTTP/2 frame size.
#defineHTTP2_GOAWAY_SIZE   8
 Size of goaway frame data.
#defineHTTP2_HEADER_OVERHEAD   32
 HPACK table overhead by spec.
#defineHTTP2_MAX_FRAME_SIZE   ((1 << 24) - 1)
 Maximum frame size by spec.
#defineHTTP2_MAX_STREAM   ((1U << 31) - 1)
 Maximum stream number by spec.
#defineHTTP2_MAX_WINDOW   ((1U << 31) - 1)
 Maximum window size by spec.
#defineHTTP2_MIN_FRAME_SIZE   (16 * 1024)
 Default and minimum frame size - modified by config.
#defineHTTP2_MIN_WINDOW   65535
 Initial default window size by spec.
#defineHTTP2_PRIORITY_SIZE   5
 Size of priority frame data.
#defineHTTP2_RESET_SIZE   4
 Size of rest frame data.
#defineHTTP2_SETTINGS_SIZE   6
 Size of settings frame data.
#defineHTTP2_WINDOW_SIZE   4
 Size of windows frame data.
#defineHTTP_ADDED_BODY_PARAMS   0x800
 Body data added to params.
#defineHTTP_ADDED_QUERY_PARAMS   0x400
 Query added to params.
#defineHTTP_ALLOW_DENY   0x1
 Run allow checks before deny checks.
#defineHTTP_AUTH_NO_SESSION   0x4
 Do not create a session when authenticated.
#defineHTTP_AUTH_TYPE_CONDITION   0x1
 Use auth condition.
#defineHTTP_BLOCK   0x1
 Flag for httpSendBlock and httpWriteBlock to indicate blocking operation.
#defineHTTP_BUFFER   0x4
 Flag for httpSendBlock and httpWriteBlock to always absorb the data without blocking.
#defineHTTP_CACHE_CLIENT   0x1
 Cache on the client side.
#defineHTTP_CACHE_HAS_PARAMS   0x20
 Cache definition has params.
#defineHTTP_CACHE_MANUAL   0x4
 Cache manually.
#defineHTTP_CACHE_RESET   0x8
 Don't inherit cache config from outer routes.
#defineHTTP_CACHE_SERVER   0x2
 Cache on the server side.
#defineHTTP_CACHE_STATIC   0x40
 Cache extensions: css, gif, ico, jpg, js, html, pdf, ttf, txt, xml, woff.
#defineHTTP_CACHE_UNIQUE   0x10
 Uniquely cache request with different params.
#defineHTTP_CHUNK_DATA   2
 Start of chunk data.
#defineHTTP_CHUNK_EOF   3
 End of last chunk.
#defineHTTP_CHUNK_START   1
 Start of a new chunk.
#defineHTTP_CHUNK_UNCHUNKED   0
 Data is not transfer-chunk encoded.
#defineHTTP_CHUNKED   0x200
 Content is chunk encoded.
#defineHTTP_CLIENT_SIDE   0x1
 Initialize the client-side support.
#defineHTTP_CODE_ACCEPTED   202
 The request has been accepted and processing is continuing.
#defineHTTP_CODE_BAD_GATEWAY   502
 The server cannot act as a gateway for the given request.
#defineHTTP_CODE_BAD_HANDSHAKE   551
 The server handsake response is unacceptable.
#defineHTTP_CODE_BAD_METHOD   405
 The request HTTP method was not supported by the resource.
#defineHTTP_CODE_BAD_REQUEST   400
 The request is malformed.
#defineHTTP_CODE_BAD_VERSION   505
 The server does not support the HTTP protocol version.
#defineHTTP_CODE_CERT_ERROR   495
 The peer provided certificate is unacceptable.
#defineHTTP_CODE_CLIENT_ERROR   552
 The server responded, but the response is unacceptable to the client.
#defineHTTP_CODE_COMMS_ERROR   550
 The server had a communications error responding to the client.
#defineHTTP_CODE_CONFLICT   409
 The request had a conflict in the request headers and URI.
#defineHTTP_CODE_CONTINUE   100
 Continue with request, only partial content transmitted.
#defineHTTP_CODE_CREATED   201
 The request has completed and a new resource was created.
#defineHTTP_CODE_EXPECTATION_FAILED   417
 The server cannot satisfy the Expect header requirements.
#defineHTTP_CODE_FORBIDDEN   403
 The request was legal, but the server refuses to process.
#defineHTTP_CODE_GATEWAY_TIMEOUT   504
 The server gateway timed out waiting for the upstream server.
#defineHTTP_CODE_GONE   410
 The requested resource is no longer available.
#defineHTTP_CODE_IM_A_TEAPOT   418
 Short and stout error code (RFC 2324).
#defineHTTP_CODE_INSUFFICIENT_STORAGE   507
 The server has insufficient storage to complete the request.
#defineHTTP_CODE_INTERNAL_SERVER_ERROR   500
 Server processing or configuration error.
#defineHTTP_CODE_LENGTH_REQUIRED   411
 The request did not specify a required content length.
#defineHTTP_CODE_MOVED_PERMANENTLY   301
 The requested URI has moved permanently to a new location.
#defineHTTP_CODE_MOVED_TEMPORARILY   302
 The URI has moved temporarily to a new location.
#defineHTTP_CODE_NO_CONTENT   204
 The request has completed and there is no response to send.
#defineHTTP_CODE_NO_RESPONSE   444
 The connection was closed with no response to the client.
#defineHTTP_CODE_NOT_ACCEPTABLE   406
 The requested resource cannot generate the required content.
#defineHTTP_CODE_NOT_AUTHORITATIVE   203
 The request has completed but content may be from another source.
#defineHTTP_CODE_NOT_FOUND   404
 The requested resource was not found.
#defineHTTP_CODE_NOT_IMPLEMENTED   501
 The server does not recognize the request or method.
#defineHTTP_CODE_NOT_MODIFIED   304
 The requested resource has changed since the last request.
#defineHTTP_CODE_OK   200
 The request completed successfully.
#defineHTTP_CODE_PARTIAL   206
 The request has completed and is returning partial content.
#defineHTTP_CODE_PAYMENT_REQUIRED   402
 Reserved for future use.
#defineHTTP_CODE_PRECOND_FAILED   412
 The server cannot satisfy one of the request preconditions.
#defineHTTP_CODE_RANGE_NOT_SATISFIABLE   416
 The request content range does not exist for the resource.
#defineHTTP_CODE_REQUEST_TIMEOUT   408
 The server timed out waiting for the request to complete.
#defineHTTP_CODE_REQUEST_TOO_LARGE   413
 The request is too large for the server to process.
#defineHTTP_CODE_REQUEST_URL_TOO_LARGE   414
 The request URI is too long for the server to process.
#defineHTTP_CODE_RESET   205
 The request has completed with no content.
#defineHTTP_CODE_SEE_OTHER   303
 The requested URI can be found at another URI location.
#defineHTTP_CODE_SERVICE_UNAVAILABLE   503
 The server is currently unavailable or overloaded.
#defineHTTP_CODE_SWITCHING   101
 Switching protocols.
#defineHTTP_CODE_TEMPORARY_REDIRECT   307
 The request should be repeated at another URI location.
#defineHTTP_CODE_UNAUTHORIZED   401
 Authentication for the request has failed.
#defineHTTP_CODE_UNPROCESSABLE   422
 The request was well-formed but was unable process.
#defineHTTP_CODE_UNSUPPORTED_MEDIA_TYPE   415
 The request media type is not supported by the server or resource.
#defineHTTP_CODE_UPGRADE_REQUIRED   426
 The client should upgrade.
#defineHTTP_CODE_USE_PROXY   305
 The requested resource must be accessed via the location proxy.
#defineHTTP_COMPLETE_URI   0x1
 Complete all missing URI fields.
#defineHTTP_COMPLETE_URI_PATH   0x2
 Complete missing URI path.
#defineHTTP_COOKIE_HTTP   0x2
 Flag for Set-Cookie httponly.
#defineHTTP_COOKIE_SAME_LAX   0x4
 Flag for Set-Cookie SameSite=Lax.
#defineHTTP_COOKIE_SAME_NONE   0x10
 Flag for Set-Cookie SameSite=None.
#defineHTTP_COOKIE_SAME_STRICT   0x8
 Flag for Set-Cookie SameSite=Strict.
#defineHTTP_COOKIE_SECURE   0x1
 Flag for Set-Cookie for SSL only.
#defineHTTP_COUNTER_ACTIVE_CLIENTS   0
 Active unique client IP addresses (global).
#defineHTTP_COUNTER_ACTIVE_CONNECTIONS   1
 Active connections per client.
#defineHTTP_COUNTER_ACTIVE_PROCESSES   3
 Total processes for server (global).
#defineHTTP_COUNTER_ACTIVE_REQUESTS   2
 Active requests per client.
#defineHTTP_COUNTER_BAD_REQUEST_ERRORS   4
 Bad request format errors.
#defineHTTP_COUNTER_ERRORS   5
 All errors.
#defineHTTP_COUNTER_LIMIT_ERRORS   6
 Limit violation errors.
#defineHTTP_COUNTER_MAX   12
 Max standard counters.
#defineHTTP_COUNTER_MEMORY   7
 Total application memory for server (global).
#defineHTTP_COUNTER_NETWORK_IO   8
 Network I/O.
#defineHTTP_COUNTER_NOT_FOUND_ERRORS   9
 URI not found errors.
#defineHTTP_COUNTER_REQUESTS   10
 Request count.
#defineHTTP_COUNTER_SSL_ERRORS   11
 SSL upgrade errors.
#defineHTTP_CREATE_ENV   0x80
 Must create env for this request.
#defineHTTP_CURRENT   0x8
 Flag to service current queued events only.
#defineHTTP_DELAY_SERVICE   0
 Delay servicing the queue.
#defineHTTP_DELETE   0x1
 DELETE method
#defineHTTP_DENY_ALLOW   0x2
 Run deny checks before allow checks.
#defineHTTP_EVENT_APP_CLOSE   8
 The request is now closed.
#defineHTTP_EVENT_APP_OPEN   9
 The request is now open.
#defineHTTP_EVENT_DESTROY   7
 The HttpStream object is being closed and destroyed.
#defineHTTP_EVENT_DONE   5
 Request is done (all states complete).
#defineHTTP_EVENT_ERROR   4
 The request has an error.
#defineHTTP_EVENT_MAX   10
 Maximum event plus one.
#defineHTTP_EVENT_READABLE   2
 The request has data available for reading.
#defineHTTP_EVENT_STATE   1
 Notifier events.
#defineHTTP_EVENT_TIMEOUT   6
 Request has timed out.
#defineHTTP_EVENT_WRITABLE   3
 The request is now writable (post / put data).
#defineHTTP_EXPECT_CONTINUE   0x1000
 Client expects an HTTP 100 Continue response.
#defineHTTP_GET   0x2
 GET method
#defineHTTP_HEAD   0x4
 HEAD method
#defineHTTP_HOST_ATTACHED   0x100
 Host name attached to an endpoint.
#defineHTTP_HOST_NO_TRACE   0x10
 Host flag to disable the of TRACE HTTP method.
#defineHTTP_HOST_WILD_CONTAINS   0x40
 Host name contains the host name.
#defineHTTP_HOST_WILD_REGEXP   0x80
 Host name is a regular expression.
#defineHTTP_HOST_WILD_STARTS   0x20
 Host name starts with pattern.
#defineHTTP_IF_MODIFIED   0x100
 If-[un]modified-since supplied.
#defineHTTP_LANG_AFTER   0x2
 Insert suffix after extension.
#defineHTTP_LANG_BEFORE   0x1
 Insert suffix before extension.
#defineHTTP_MAX_QUEUE   2
 Number of queue types.
#defineHTTP_MAX_SECRET   16
 Size of secret data for auth.
#defineHTTP_MORE   0x1000
 Flag for httpSendBlock to indicate there are more frames for this message.
#defineHTTP_NET_ACCEPT   1
 A network connection has just been accepted.
#defineHTTP_NET_CONNECT   2
 The network has just connected to a peery (client side only).
#defineHTTP_NET_DESTROY   5
 The network is about to be destroyed.
#defineHTTP_NET_EOF   3
 The network peer has disconnected.
#defineHTTP_NET_ERROR   4
 The network has an unrecoverable error.
#defineHTTP_NET_IO   6
 The network has an IO event.
#defineHTTP_NEW_DISPATCHER   0x1
 New dispatcher for each connection.
#defineHTTP_NON_BLOCK   0x2
 Flag for httpSendBlock and httpWriteBlock to indicate non-blocking operation.
#defineHTTP_OPTIONS   0x8
 OPTIONS method
#defineHTTP_PACKET_DATA   0x4
 Packet contains actual content data.
#defineHTTP_PACKET_END   0x8
 End of stream packet.
#defineHTTP_PACKET_HEADER   0x1
 Packet contains HTTP headers.
#defineHTTP_PACKET_PROCESSED   0x20
 Packet data has already been processed.
#defineHTTP_PACKET_RANGE   0x2
 Packet is a range boundary packet.
#defineHTTP_PACKET_SOLO   0x10
 Don't join this packet.
#defineHTTP_POST   0x10
 Post method.
#defineHTTP_PUT   0x20
 PUT method
#defineHTTP_QUEUE_ALL   0x8
 Queue has all the data there is and will be.
#defineHTTP_QUEUE_ALLOW   32
 Let packets less than this size flow through.
#defineHTTP_QUEUE_DONT_SPLIT   32
 Don't split packets less than 32 bytes.
#defineHTTP_QUEUE_EOF   0x20
 Queue at end of data.
#defineHTTP_QUEUE_HEAD   0x800
 Queue header.
#defineHTTP_QUEUE_OPEN_TRIED   0x1
 Queue's open routine has been called.
#defineHTTP_QUEUE_OPENED   0x2
 Queue's open routine has been called.
#defineHTTP_QUEUE_OUTGOING   0x200
 Queue is for outgoing traffic.
#defineHTTP_QUEUE_READY   0x80
 Handler stage ready routine called.
#defineHTTP_QUEUE_REMOVED   0x1000
 Queue removed from pipeline.
#defineHTTP_QUEUE_REQUEST   0x400
 Queue is specific for this request.
#defineHTTP_QUEUE_RESERVICE   0x100
 Queue requires reservicing.
#defineHTTP_QUEUE_RX   1
 Receive (read from client) queue.
#defineHTTP_QUEUE_SERVICED   0x10
 Queue has been serviced at least once.
#defineHTTP_QUEUE_STARTED   0x40
 Handler stage start routine called.
#defineHTTP_QUEUE_SUSPENDED   0x4
 Queue's service routine is suspended due to flow control.
#defineHTTP_QUEUE_TX   0
 Send (transmit to client) queue.
#defineHTTP_ROUTE_CORS   0x40
 Cross-Origin resource sharing.
#defineHTTP_ROUTE_DOTNET_DIGEST_FIX   0x2000
 NET digest auth omits query in MD5.
#defineHTTP_ROUTE_ENV_ESCAPE   0x1000
 Escape env vars.
#defineHTTP_ROUTE_FREE   0x2
 Free Route.mdata back to malloc when route is freed.
#defineHTTP_ROUTE_FREE_PATTERN   0x4
 Free Route.patternCompiled back to malloc when route is freed.
#defineHTTP_ROUTE_HIDDEN   0x800
 Hide this route in route tables.
#defineHTTP_ROUTE_HOSTED   0x10000
 Route being hosted (appweb).
#defineHTTP_ROUTE_LAX_COOKIE   0x200000
 Session cookie is SameSite=lax.
#defineHTTP_ROUTE_NO_LISTEN   0x20000
 Not listening on endpoints.
#defineHTTP_ROUTE_NONE_COOKIE   0x800000
 Session cookie is SameSite=none.
#defineHTTP_ROUTE_NOT   0x1
 Negate the route pattern test result.
#defineHTTP_ROUTE_OK   0
 The route matches the request.
#defineHTTP_ROUTE_OMIT_FILTER   1
 Omit filter.
#defineHTTP_ROUTE_OWN_LISTEN   0x80000
 Override listening endpoints.
#defineHTTP_ROUTE_PERSIST_COOKIE   0x40000
 Persist session cookie to disk.
#defineHTTP_ROUTE_PRESERVE_FRAMES   0x400
 Preserve WebSocket frame boundaries.
#defineHTTP_ROUTE_RAW   0x8
 Don't html encode the write data.
#defineHTTP_ROUTE_REDIRECT   0x4000
 Redirect secureCondition.
#defineHTTP_ROUTE_REJECT   1
 The route does not match the request.
#defineHTTP_ROUTE_REROUTE   2
 Request has been modified and must be re-routed.
#defineHTTP_ROUTE_SHOW_ERRORS   0x100
 Show errors to the client.
#defineHTTP_ROUTE_STARTED   0x10
 Route initialized.
#defineHTTP_ROUTE_STEALTH   0x80
 Stealth mode.
#defineHTTP_ROUTE_STRICT_COOKIE   0x400000
 Session cookie is SameSite=strict.
#defineHTTP_ROUTE_STRICT_TLS   0x8000
 Emit Strict-Transport-Security header.
#defineHTTP_ROUTE_UTILITY   0x100000
 Route hosted by a utility.
#defineHTTP_ROUTE_VISIBLE_SESSION   0x200
 Create a session cookie visible to client Javascript.
#defineHTTP_ROUTE_XSRF   0x20
 Generate XSRF tokens.
#defineHTTP_SCHEDULE_QUEUE   1
 Schedule the queue for service.
#defineHTTP_SERVER_SIDE   0x2
 Initialize the server-side support.
#defineHTTP_SESSION_COOKIE   "-http-session-"
 Session cookie name.
#defineHTTP_SESSION_IP   "__IP__"
 Connection IP address - prevents session hijack.
#defineHTTP_SESSION_USERNAME   "__USERNAME__"
 Username variable.
#defineHTTP_STAGE_AUTO_DIR   0x10000
 Want auto directory redirection.
#defineHTTP_STAGE_CONNECTOR   0x1000
 Stage is a connector
#defineHTTP_STAGE_FILTER   0x4000
 Stage is a filter
#defineHTTP_STAGE_HANDLER   0x2000
 Stage is a handler
#defineHTTP_STAGE_INTERNAL   0x100000
 Internal stage - hidden.
#defineHTTP_STAGE_MODULE   0x8000
 Stage is a module
#defineHTTP_STAGE_QHEAD   0x200000
 Queue Head.
#defineHTTP_STAGE_RX   0x40000
 Stage to be used in the Rx direction.
#defineHTTP_STAGE_TX   0x80000
 Stage to be used in the Tx direction.
#defineHTTP_STAGE_UNLOADED   0x20000
 Stage module library has been unloaded.
#defineHTTP_STATE_BEGIN   1
 Ready for a new request.
#defineHTTP_STATE_COMPLETE   9
 Request complete.
#defineHTTP_STATE_CONNECTED   2
 Connection received or made.
#defineHTTP_STATE_CONTENT   5
 Reading posted content.
#defineHTTP_STATE_FINALIZED   8
 Input received, request processed and response transmitted.
#defineHTTP_STATE_FIRST   3
 First request line has been parsed.
#defineHTTP_STATE_PARSED   4
 Headers have been parsed, handler can start.
#defineHTTP_STATE_READY   6
 Handler ready - all body data received
#defineHTTP_STATE_RUNNING   7
 Handler running.
#defineHTTP_TIMER_PERIOD   1000
 HttpTimer checks ever 1 second.
#defineHTTP_TRACE   0x40
 TRACE method
#defineHTTP_TRACE_CONT   0x4
 Continuation trace.
#defineHTTP_TRACE_HEX   0x1
 Format content in hex with side ascii.
#defineHTTP_TRACE_MAX_SIZE   (10 * 1024)
 Default maximum body size to log.
#defineHTTP_TRACE_MIN_LOG_SIZE   (10 * 1024)
 Minimum log file size.
#defineHTTP_TRACE_RAW   0x2
 Emit raw trace - don't interpret key/value pairs.
#defineHTTP_TX_HAS_FILTERS   0x100
 Has output filters.
#defineHTTP_TX_HEADERS_CREATED   0x2
 Tx headers have been created.
#defineHTTP_TX_HEADERS_PREPARED   0x200
 Tx headers have been created.
#defineHTTP_TX_NO_BODY   0x1
 No transmission body, only send headers.
#defineHTTP_TX_NO_CHECK   0x10
 Do not check if the filename is inside the route documents directory.
#defineHTTP_TX_NO_LENGTH   0x20
 Do not emit a content length (used for TRACE).
#defineHTTP_TX_NO_MAP   0x40
 Do not map the filename to compressed or minified alternatives.
#defineHTTP_TX_PIPELINE   0x80
 Created Tx pipeline.
#defineHTTP_TX_USE_OWN_HEADERS   0x8
 Skip adding default headers.
#definehttpIsClient   (net && !net->endpoint)
 Test if the network is a client-side network.
#definehttpIsServer   (net && net->endpoint)
 Test if the network is a server-side network.
#defineME_DIGEST_NONCE_DURATION   60
 Lifespan for Digest auth request nonce.
#defineME_HTTP_BAN_PERIOD   (5 * 60 * 1000)
 Default ban IP period.
#defineME_HTTP_DEFAULT_METHODS   "GET,POST"
 Default methods for routes.
#defineME_HTTP_DELAY   (2000)
 2 second delay per request - while delay enforced.
#defineME_HTTP_DELAY_PERIOD   (5 * 60 * 1000)
 Default delay IP period.
#defineME_HTTP_MONITOR_PERIOD   (60 * 1000)
 Monitor prune period.
#defineME_HTTP_REMEDY_TIMEOUT   (60 * 1000)
 Default remedy command timeout.
#defineME_HTTP_SOFTWARE   "Embedthis-http"
 Default Http protocol name used in Http Server header.
#defineME_MAX_CACHE_DURATION   (86400 * 1000)
 Default cache lifespan to 1 day.
#defineME_MAX_CACHE_ITEM   (256 * 1024)
 Maximum cachable item size.
#defineME_MAX_CHUNK   (8 * 1024)
 Maximum chunk size for transfer chunk encoding.
#defineME_MAX_CLIENTS   32
 Maximum unique client IP addresses.
#defineME_MAX_CLIENTS_HASH   131
 Hash table for client IP addresses.
#defineME_MAX_CONNECTIONS   50
 Maximum concurrent connections (sockets) for whole server.
#defineME_MAX_CONNECTIONS_PER_CLIENT   20
 Maximum concurrent connections per client (ip address).
#defineME_MAX_HEADERS   (512 * 1024)
 Maximum size of the headers (Chrome HTTP/2 needs this).
#defineME_MAX_HPACK_SIZE   65536
 Maximum size of the hpack table.
#defineME_MAX_INACTIVITY_DURATION   (30 * 1000)
 Default keep alive between requests timeout (30 sec).
#defineME_MAX_IOVEC   16
 Number of fragments in a single socket write.
#defineME_MAX_KEEP_ALIVE   400
 Maximum requests per network.
#defineME_MAX_NUM_HEADERS   64
 Maximum number of header lines.
#defineME_MAX_PARSE_DURATION   (5 * 1000)
 Default request parse header timeout (5 sec).
#defineME_MAX_PING_DURATION   (30 * 1000)
 WSS ping defeat Keep-Alive timeouts (30 sec).
#defineME_MAX_PROCESSES   10
 Maximum concurrent processes.
#defineME_MAX_REQUEST_DURATION   (5 * 60 * 1000)
 Default request timeout (5 minutes).
#defineME_MAX_REQUESTS_PER_CLIENT   ME_MAX_STREAMS
 Maximum concurrent requests per client (ip address).
#defineME_MAX_REWRITE   20
 Maximum URI rewrites.
#defineME_MAX_ROUTE_MAP_HASH   17
 Size of the route mapping hash.
#defineME_MAX_ROUTE_MATCHES   32
 Maximum number of submatches in routes.
#defineME_MAX_RX_BODY   (512 * 1024)
 Maximum incoming body size (512K).
#defineME_MAX_RX_FORM   (512 * 1024)
 Maximum incoming form size (512K).
#defineME_MAX_RX_FORM_FIELD   HTTP_UNLIMITED
 Maximum form field size for copied to.
#defineME_MAX_SESSION_DURATION   (5 * 60 * 1000)
 Default session inactivity timeout (5 mins).
#defineME_MAX_SESSION_HASH   31
 Hash table for session data.
#defineME_MAX_SESSIONS   100
 Maximum concurrent sessions.
#defineME_MAX_STREAMS   200
 Default maximum concurrent streams per network.
#defineME_MAX_TX_BODY   HTTP_UNLIMITED
 Maximum buffer for response data.
#defineME_MAX_UPLOAD   HTTP_UNLIMITED
 Maximum file upload size.
#defineME_MAX_URI   512
 Reasonable URI size.
#defineME_MAX_WSS_FRAME   (4 * 1024)
 Default max WebSockets message frame size.
#defineME_MAX_WSS_MESSAGE   (2147483647)
 Default max WebSockets message size (2GB).
#defineME_MAX_WSS_PACKET   (8 * 1024)
 Default size to provide to application in one packet.
#defineME_MAX_WSS_SOCKETS   25
 Default max WebSockets.
#defineME_QUEUE_MAX_FACTOR   4
 Queue max set to packetSize * factor.
#defineME_XSRF_COOKIE   "XSRF-TOKEN"
 CSRF token cookie name.
#defineME_XSRF_HEADER   "X-XSRF-TOKEN"
 CSRF token name in Http headers.
#defineME_XSRF_PARAM   "-xsrf-"
 CSRF parameter in form fields.
#defineWS_MAX_CONTROL   125
 Maximum bytes in control message.
#defineWS_MSG_BINARY   0x2
 httpSendBlock type for binary messages.
#defineWS_MSG_CLOSE   0x8
 httpSendBlock type for close message.
#defineWS_MSG_CONT   0x0
 Continuation of WebSocket message.
#defineWS_MSG_CONTROL   0x8
 Start of control messages.
#defineWS_MSG_MAX   0xB
 Max message type for httpSendBlock.
#defineWS_MSG_PING   0x9
 httpSendBlock type for ping messages.
#defineWS_MSG_PONG   0xA
 httpSendBlock type for pong messages.
#defineWS_MSG_TEXT   0x1
 httpSendBlock type for text messages.
#defineWS_STATE_CLOSED   3
 WebSocket is closed.
#defineWS_STATE_CLOSING   2
 WebSocket is closing.
#defineWS_STATE_CONNECTING   0
 WebSocket connection is being established.
#defineWS_STATE_OPEN   1
 WebSocket handsake is complete and ready for communications.
#defineWS_STATUS_COMMS_ERROR   1006
 TCP/IP communications error
#defineWS_STATUS_FRAME_TOO_LARGE   1004
 Reserved.
#defineWS_STATUS_GOING_AWAY   1001
 Endpoint is going away.
#defineWS_STATUS_INTERNAL_ERROR   1011
 Server terminating due to an internal error.
#defineWS_STATUS_INVALID_UTF8   1007
 Text message has invalid UTF-8.
#defineWS_STATUS_MAX   5000
 Maximum error status (less one).
#defineWS_STATUS_MESSAGE_TOO_LARGE   1009
 Message is too large.
#defineWS_STATUS_MISSING_EXTENSION   1010
 Unsupported WebSockets extension.
#defineWS_STATUS_NO_STATUS   1005
 No status was received from the peer in closing.
#defineWS_STATUS_OK   1000
 Normal closure.
#defineWS_STATUS_POLICY_VIOLATION   1008
 Application level policy violation.
#defineWS_STATUS_PROTOCOL_ERROR   1002
 WebSockets protocol error.
#defineWS_STATUS_TLS_ERROR   1015
 TLS handshake error.
#defineWS_STATUS_UNSUPPORTED_TYPE   1003
 Unsupported message data type.
#defineWS_VERSION   13
 Current WebSocket specification version.
#definehttpIsClient   (net && !net->endpoint)
 Test if the network is a client-side network.
#definehttpIsServer   (net && net->endpoint)
 Test if the network is a server-side network.

Http

Http

Http service object.

Description:
Configuration is not thread safe and must occur at initialization time when the application is single threaded. If the configuration is modified when the application is multithreaded, all requests must be first be quiesced.
See Also:
HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
API Stability:
Internal.
Fields:
struct HttpStage *actionHandler Action handler.
intactiveProcesses Count of active external processes.
MprHash *addresses Monitored per-IP-address counters.
MprHash *authStores Available password stores.
MprHash *authTypes Available authentication protocol types.
MprTimebooted Time the server started.
struct HttpStage *cacheFilter Cache filter.
struct HttpStage *cacheHandler Cache filter.
struct HttpStage *cgiConnector CGI connector.
struct HttpStage *cgiHandler CGI handler.
struct HttpStage *chunkFilter Chunked transfer encoding filter.
struct HttpLimits *clientLimits Client resource limits.
struct HttpRoute *clientRoute Default route for clients.
void *context Embedding context.
MprList *counters List of counters.
char *currentDate Date string for HTTP response headers.
MprTickscurrentTime When currentDate was last calculated (ticks).
MprHash *dateCache Cache of date modified times.
char *defaultClientHost Default ip address.
intdefaultClientPort Default port.
MprHash *defenses List of Defenses.
struct HttpStage *dirHandler Directory listing handler.
struct HttpStage *egiHandler Embedded Gateway Interface (EGI) handler.
MprList *endpoints Currently configured listening endpoints.
HttpEnvCallbackenvCallback SetEnv callback.
struct HttpStage *espHandler ESP Web Framework handler.
struct HttpStage *fastConnector FastCGI connector.
struct HttpStage *fastHandler FastCGI handler.
struct HttpStage *fileHandler Static file handler.
intflags Open flags.
MprForkCallbackforkCallback Callback in child after fork().
intgid Group Id.
cchar *group O/S application group name.
intgroupChanged Group name changed.
MprList *hosts List of host objects.
struct HttpStage *http1Filter Http/1 filter.
inthttp2 Enable http 2.
struct HttpStage *httpFilter Http filter.
cchar *jail Chroot jail path.
HttpListenCallbacklistenCallback Invoked when creating listeners.
cchar *localPlatform Local (dev) platform os-arch-profile (lower case).
MprTicksmonitorPeriod Minimum monitor period.
MprList *monitors List of monitors.
intmonitorsStarted Monitors are running.
MprMutex *mutex Multithread sync.
HttpNetCallbacknetCallback Default network event callback.
struct HttpStage *netConnector Default network connector.
MprList *networks Currently open network connections.
intnextAuth Auth object version vector.
MprTicksnow Current time in ticks.
MprHash *parsers Table config parser callbacks.
struct HttpStage *passHandler Pass through handler.
struct HttpStage *phpHandler PHP through handler.
cchar *platform Target platform os-arch-profile (lower case).
cchar *platformDir Path to platform directory containing binaries.
struct HttpStage *proxyConnector Proxy connector.
struct HttpStage *proxyHandler Proxy handler.
char *proxyHost Proxy ip address.
intproxyPort Proxy port.
struct HttpStage *queueHead Queue head stage.
struct HttpStage *rangeFilter Ranged requests filter.
HttpRedirectCallbackredirectCallback Redirect callback.
MprHash *remedies List of Defense Remedies.
HttpRequestCallbackrequestCallback Request completion callback.
MprHash *routeConditions Http route condition functions.
MprHash *routeSets Http route sets functions.
MprHash *routeTargets Http route target functions.
MprHash *routeUpdates Http route update functions.
char *secret Random bytes for authentication.
struct HttpLimits *serverLimits Server resource limits.
MprCache *sessionCache Session state cache.
char *software Software name and version.
MprHash *stages Possible stages in connection pipelines.
intstartLevel Start endpoint trace level.
MprList *staticHeaders HTTP/2 static headers.
intstaticLink Target platform is using a static linking.
MprHash *statusCodes Http status codes.
struct HttpStage *tailFilter Tail filter.
MprEvent *timer Admin service timer.
MprEvent *timestamp Timestamp timer.
uint64totalConnections Total connections accepted.
uint64totalRequests Total requests served.
uint64totalStreams Total streams created.
HttpTrace *trace Default tracing configuration.
intuid User Id.
struct HttpStage *uploadFilter Upload filter.
cchar *user O/S application user name.
intuserChanged User name changed.
void httpAddOption (MprHash *options, cchar *field, cchar *value)

Add an option to the options table.

Parameters:
optionsOption table returned from httpGetOptions.
fieldField key name.
valueValue to use for the field.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
int httpApplyChangedGroup (void )

Apply the changed group ID.

Description:
Apply configuration changes and actually change the group id.
Returns:
Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
int httpApplyChangedUser (void )

Apply the changed user ID.

Description:
Apply configuration changes and actually change the user id.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
int httpApplyUserGroup (void )

Apply the changed user and group ID.

Description:
Apply configuration changes and actually change the user and group id.
Returns:
Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
bool httpConfigure (HttpConfigureProc proc, void *arg, MprTicks timeout)

Alter the configuration by first quiescing all Http activity.

This waits until there are no open connections and then invokes the configuration callback while blocking further connections. When the callback completes, connections are resumed with the new configuration. This callback is required because configuration of the Http engine must be done when single-threaded
Parameters:
procFunction of the type HttpConfigureProc.
argReference argument to pass to the callback proc. Can be a managed or an unmanaged reference.
timeoutTimeout in milliseconds to wait. Set to -1 to use the default server inactivity timeout. Set to zero to wait forever.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
Http * * httpCreate (int flags)

Create a Http service object.

Description:
Create a http service object. One http service object should be created per application.
Parameters:
flagsSet to zero to initialize bo Initialize the client-side support only.
Returns:
The http service object.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpDestroy (void )

Destroy the Http service.

Description:
This routine is invoked as the final stage in shutting down the http service. It stops the request timeout timer and releases all http memory.
API Stability:
Internal.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void * * httpGetContext (void )

Get the http context object.

Returns:
The http context object defined via httpSetContext.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
char * * httpGetDateString (MprPath *sbuf)

Get the time as an ISO date string.

Parameters:
sbufOptional path buffer. If supplied, the modified time of the path is used. If NULL, then the current time is used.
Returns:
RFC822 formatted date string.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void * * httpGetOption (MprHash *options, cchar *field, cchar *defaultValue)

Extract a field value from an option string.

Parameters:
optionsOption string of the form: "field='value' field='value'...".
fieldField key name.
defaultValueValue to use if "field" is not found in options.
Returns:
Option value.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
MprHash * * httpGetOptionHash (MprHash *options, cchar *field)

Get an option value that is itself an object (hash).

Description:
This returns an option value that is an instance of MprHash. When deserializing a JSON option string which contains multiple levels, this routine can be used to extract lower option container values.
Parameters:
optionsOptions object to examine.
fieldProperty to return.
Returns:
An MprHash instance for the given field. This will contain option sub-properties.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
MprHash * * httpGetOptions (cchar *options)

Convert an options string into an options table.

Parameters:
optionsOption string of the form: "{field:'value', field:'value'}" This is a sub-set of the JSON syntax. Arrays are not supported.
Returns:
Options table.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpGetUserGroup (void )
int httpInitParser (void )

Initialize the Http configuration parser.

Returns:
Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpInsertOption (MprHash *options, cchar *field, cchar *value)

Add an option to the options table.

Description:
If the field already exists, the added value is inserted prior to the existing value.
Parameters:
optionsOption table returned from httpGetOptions.
fieldField key name.
valueValue to use for the field.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
struct HttpEndpoint * HttpEndpoint * httpLookupEndpoint (cchar *ip, int port)

Lookup a listening endpoint.

Parameters:
ipListening IP address to look for.
portListening port number.
Returns:
HttpEndpoint object.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
struct HttpHost * HttpHost * httpLookupHost (cchar *name)

Lookup a host by name.

Parameters:
nameThe name of the host to find.
Returns:
The corresponding host object.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
cchar * * httpLookupStatus (int status)

Lookup a Http status code.

Description:
Lookup the code and return the corresponding text message briefly expaining the status.
Parameters:
statusHttp status code.
Returns:
Text message corresponding to the status code.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
bool httpOption (MprHash *options, cchar *field, cchar *value, int useDefault)

Test a field value from an option string.

Parameters:
optionsOption string of the form: "field='value' field='value'...".
fieldField key name.
valueTest if the field is set to this value.
useDefaultIf true and "field" is not found in options, return true.
Returns:
Allocated value string.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
int httpParsePlatform (cchar *platform, cchar **os, cchar **arch, cchar **profile)

Parse a platform string.

Parameters:
platformThe platform string. Must be of the form: os-arch-profile.
osParsed O/S portion.
archParsed architecture portion.
profileParsed profile portion.
Returns:
Zero if successful, otherwise a negative Mpr error code.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpRemoveOption (MprHash *options, cchar *field)

Remove an option.

Description:
Remove a property from an options hash.
Parameters:
optionsOptions table returned from httpGetOptions.
fieldProperty field to remove.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpSetContext (void *context)
void httpSetDefaultClientHost (cchar *host)

Define a default client host.

Description:
Define a default host to use for client connections if the URI does not specify a host.
Parameters:
hostHost or IP address.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpSetDefaultClientPort (int port)

Define a default client port.

Description:
Define a default port to use for client connections if the URI does not define a port.
Parameters:
portInteger port number.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpSetEnvCallback (HttpEnvCallback envCallback)

Define a callback to invoke after env vars have been defined.

Parameters:
envCallbackCallback to invoke.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
int httpSetGroupAccount (cchar *group)

Set the group account.

Description:
Define the group account name under which to run the process.
Parameters:
groupGroup name. Must be defined in the system group database.
Returns:
Zero if successful, otherwise a negative Mpr error code.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpSetJail (cchar *path)

Remember the Chroot jail path.

Description:
Store the jail path in HTTP->jail.
Parameters:
pathPathname to remember.
API Stability:
Internal.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpSetOption (MprHash *options, cchar *field, cchar *value)

Set an option.

Description:
Set a property in an options hash.
Parameters:
optionsOptions table returned from httpGetOptions.
fieldProperty field to set.
valueProperty value to use.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
int httpSetPlatform (cchar *platform)

Set platform description.

Description:
Some web frameworks need to recompile sources before serving requests (ESP). These need access to the http libraries to link with.
Parameters:
platformPlatform string of the form: OS-ARCH-PROFILE.
Returns:
Zero if the platform string parses, otherwise a negative Mpr error code.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
int httpSetPlatformDir (cchar *platform)

Set platform directory location.

Description:
Set the platform directory location which contains libraries and headers for the application.
Parameters:
platformPath to the platform directory.
Returns:
Zero if successful, otherwise a negative Mpr error code.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpSetProxy (cchar *host, int port)

Define a Http proxy host to use for all client connect requests.

Description:
Define a http proxy host to communicate via when accessing the net.
Parameters:
hostProxy host name or IP address.
portProxy host port number.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetSoftware
void httpSetRedirectCallback (HttpRedirectCallback redirectCallback)

Define a callback to invoke on redirect requests.

Parameters:
redirectCallbackCallback to invoke.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
void httpSetSoftware (cchar *description)

Set the software description.

Parameters:
descriptionString describing the Http software. By default, this is set to HTTP_NAME.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy
int httpSetUserAccount (cchar *user)

Set the user account.

Description:
Define the user account name under which to run the process.
Parameters:
userUser name. Must be defined in the system password database.
Returns:
Zero if successful, otherwise a negative Mpr error code.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

HttpAuth

HttpAuth

Authorization.

Description:
HttpAuth is the foundation authorization object and is used by HttpRoute. It stores the authorization configuration information required to determine if a client request should be permitted access to a given resource.
See Also:
HttpAskLogin, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
API Stability:
Internal.
Fields:
MprHash *abilities Set of required abilities (all are required).
MprHash *allow Clients to allow.
char *cipher Encryption cipher.
MprHash *deny Clients to deny.
intflags Authorization flags.
char *loggedInPage Target URI after logging in.
char *loggedOutPage Target URI after logging out.
char *loginPage Web page for user login for 'form' type.
struct HttpAuth *parent Parent auth.
MprHash *permittedUsers Set of valid users.
char *qop Quality of service.
char *realm Realm of access.
MprHash *roles Hash of roles.
HttpAuthStore *store Authorization password backend (system|file|custom).
HttpAuthType *type Authorization protocol type (basic|digest|form|custom).
MprHash *userCache Cache of authenticated users.
char *username Automatic login username. Password not required if defined.
HttpVerifyUserverifyUser Password verification.
HttpRole * * httpAddRole (HttpAuth *auth, cchar *role, cchar *abilities)

Add a role.

If the role already exists, the role is updated
Description:
This creates the role with given abilities. Ability words can also be other roles.
Parameters:
authAuth object allocated by httpCreateAuth
roleRole name to add.
abilitiesSpace separated list of abilities.
Returns:
Allocated role object.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
HttpUser * * httpAddUser (HttpAuth *auth, cchar *user, cchar *password, cchar *abilities)

Add a user.

If the user already exists, the user is updated
Description:
This creates the user and adds the user to the authentication database.
Parameters:
authAuth object allocated by httpCreateAuth
userUser name to add.
passwordUser password. The password should not be encrypted. The backend will encrypt as required.
abilitiesSpace separated list of abilities.
Returns:
The User object allocated or NULL for an error.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
bool httpCanUser (HttpStream *stream, cchar *abilities)

Test if a user has the required abilities.

Parameters:
streamHttpStream stream object created via httpCreateStream object.
abilitiesComma separated list of abilities or roles to test for. If null, then use the required abilities defined for the current request route.
Returns:
True if the user has all the required abilities.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
void httpComputeAllUserAbilities (HttpAuth *auth)
void httpComputeUserAbilities (HttpAuth *auth, HttpUser *user)
HttpAuth * * httpCreateAuth (void )
HttpAuthStore * * httpCreateAuthStore (cchar *name, HttpVerifyUser verifyUser)

Add an authorization store for password validation.

The pre-supplied types are "config" and "system"
Description:
This creates an AuthStore object with the defined name and callbacks.
Parameters:
nameUnique authorization store name.
verifyUserCallback to verify the username and password contained in the HttpStream object passed to the callback.
Returns:
Auth store if successful, otherwise NULL.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
int httpCreateAuthType (cchar *name, HttpAskLogin askLogin, HttpParseAuth parse, HttpSetAuth setAuth)

Create an authorization protocol type.

The pre-supplied types are 'basic', 'digest' and 'form'
Description:
This creates an AuthType with the defined name and callbacks. The basic and digest types are supported by most browsers. The form type is implemented via web form requests over HTTP.
Parameters:
nameUnique authorization type name.
askLoginCallback to generate a client login response.
parseCallback to parse the HTTP authentication headers.
setAuthCallback to set the HTTP response authentication headers.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
HttpAuthStore * * httpGetAuthStore (cchar *name)
bool httpIsAuthenticated (HttpStream *stream)
bool httpLogin (HttpStream *stream, cchar *username, cchar *password)

Log the user in.

Description:
This will verify the supplied username and password. If the user is successfully logged in, the user identity will be stored in session state for fast authentication on subsequent requests. Note: this does not verify any user abilities.
Parameters:
streamHttpStream stream object.
usernameUser name to authenticate.
passwordPassword for the user.
Returns:
True if the username and password have been authenticated.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
void httpLogout (HttpStream *stream)
HttpRole * * httpLookupRole (HttpAuth *auth, cchar *name)
HttpUser * * httpLookupUser (HttpAuth *auth, cchar *name)

Lookup a user by username.

Description:
This looks up a user in the internal user store. This is only used i.
Parameters:
authHttpAuth object. Stored in HttpStream.rx.route.auth.
nameUsername.
Returns:
User object.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
int httpRemoveRole (HttpAuth *auth, cchar *role)
int httpRemoveUser (HttpAuth *auth, cchar *user)
void httpSetAuthAllow (HttpAuth *auth, cchar *ip)
void httpSetAuthAnyValidUser (HttpAuth *auth)
void httpSetAuthDeny (HttpAuth *auth, cchar *ip)
void httpSetAuthFormDetails (struct HttpRoute *route, cchar *loginPage, cchar *loginService, cchar *logoutService, cchar *loggedInPage, cchar *loggedOutPage)

Define login service URLs for use with "form" authentication.

Description:
This defines the login form URL and login/out service URLs. Set arguments to null if they are not required because the application is implementing its own redirection management during login. This API should not be used for web frameworks like ESP or PHP that define their own login/out services.
Parameters:
routeRoute from which to inherit when creating a route for the login pages and services.
loginPageWeb page URI for the user to enter username and password.
loginServiceURI to use for the internal login service. To use your own login URI, set to this the empty string.
logoutServiceURI to use to log the user out. To use your won logout URI, set this to the empty string.
loggedInPageThe client is redirected to this URI once logged in. Use a "referrer:" prefix to the URI to redirect the user to the referring URI before the loginPage. If the referrer cannot be determined, the base URI is utilized.
loggedOutPageThe client is redirected to this URI once logged in. Use a "referrer:" prefix to the URI to redirect the user to the referring URI before the loginPage. If the referrer cannot be determined, the base URI is utilized.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
void httpSetAuthLogin (HttpAuth *auth, cchar *uri)
void httpSetAuthOrder (HttpAuth *auth, int order)
void httpSetAuthPermittedUsers (HttpAuth *auth, cchar *users)
void httpSetAuthQop (HttpAuth *auth, cchar *qop)

Set the required quality of service for digest authentication.

Description:
This configures the basic or digest authentication for the auth object.
Parameters:
authAuth object allocated by httpCreateAuth
qopQuality of service description.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
void httpSetAuthRealm (HttpAuth *auth, cchar *realm)

Set the required realm for basic or digest authentication.

Description:
This configures the authentication realm. The realm is displayed to the user in the browser login dialog box.
Parameters:
authAuth object allocated by httpCreateAuth
realmAuthentication realm.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
void httpSetAuthRequiredAbilities (HttpAuth *auth, cchar *abilities)
void httpSetAuthSession (HttpAuth *auth, bool noSession)

Control whether a session and session cookie will be created for user logins for this authentication route.

Description:
By default, a session and response cookie are created when a user is authenticated via httpLogin. This boosts performance because subsequent requests can supply the cookie and bypass authentication for each subseqent request. This API permits the default behavior to be suppressed and thus no cookie or session will be created.
Parameters:
authAuth object created via httpCreateAuth
noSessionSet to true to suppress creation of sessions or cookies.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
int httpSetAuthStore (HttpAuth *auth, cchar *store)
void httpSetAuthStoreSessions (HttpAuthStore *store, bool noSession)

Control whether sessions and session cookies are created for user logins.

Description:
By default, a session and response cookie are created when a user is authenticated via httpLogin. This boosts performance because subsequent requests can supply the cookie and bypass authentication for each subseqent request. This API permits the default behavior to be suppressed and thus no cookie or session will be created.
Parameters:
storeAuthStore object created via httpCreateAuthStore
noSessionSet to true to suppress creation of sessions or cookies.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
void httpSetAuthStoreVerify (HttpAuthStore *store, HttpVerifyUser verifyUser)

Set the global verify callback for an authentication store.

Description:
The verification callback is invoked to verify user credentials when authentication is required. The callback has the signature: typedef bool (*HttpVerifyUser)(HttpStream *stream, cchar *username, cchar *password);.
Parameters:
storeAuthStore object allocated by httpCreateAuthStore
verifyUserVerification callback.
API Stability:
Stable.
See Also:
httpGetAuthStore, httpSetAuthStoreVerifyByName, httpSetAuthVerify
void httpSetAuthStoreVerifyByName (cchar *storeName, HttpVerifyUser verifyUser)

Set the global verify callback for an authentication store.

Description:
The verification callback is invoked to verify user credentials when authentication is required. The callback has the signature: typedef bool (*HttpVerifyUser)(HttpStream *stream, cchar *username, cchar *password);.
Parameters:
storeNameString name of the store.
verifyUserVerification callback.
API Stability:
Stable.
See Also:
httpGetAuthStore, httpSetAuthStoreVerify, httpSetAuthVerify
int httpSetAuthType (HttpAuth *auth, cchar *proto, cchar *details)

Set the authentication protocol type to use.

Parameters:
authAuth object allocated by httpCreateAuth
protoProtocol name to use. Select from: 'basic', 'digest', 'form' or 'none'. Set to NULL or 'none' to disable authentication.
detailsExtra protocol details.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthUsername
void httpSetAuthUsername (HttpAuth *auth, cchar *username)

Set an automatic login username.

Description:
If defined, no password is required and the user will be automatically logged in as this username.
Parameters:
authAuth object allocated by httpCreateAuth
usernameUsername to automatically login with.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType
void httpSetAuthVerify (HttpAuth *auth, HttpVerifyUser verifyUser)

Set the verify callback for an authentication object that is part of a route.

Parameters:
authAuth object allocated by httpCreateAuth
verifyUserVerification callback.
API Stability:
Stable.
See Also:
httpSetAuthStoreVerify

HttpCache

HttpCache

Cache Control.

Description:
Configuration is not thread safe and must occur at initialization time when the application is single threaded. If the configuration is modified when the application is multithreaded, all requests must be first be quiesced.
See Also:
httpAddCache, httpUpdateCache
API Stability:
Internal.
Fields:
MprTicksclientLifespan Lifespan for client cached content.
MprHash *extensions Extensions to cache.
intflags Cache control flags.
MprHash *methods Methods to cache.
MprTicksserverLifespan Lifespan for server cached content.
MprHash *types MimeTypes to cache.
MprHash *uris URIs to cache.
void httpAddCache (struct HttpRoute *route, cchar *methods, cchar *uris, cchar *extensions, cchar *types, MprTicks clientLifespan, MprTicks serverLifespan, int flags)

Add caching for response content.

Description:
This call configures caching for request responses. Caching may be used for any HTTP method, though typically it is most useful for state-less GET requests. Output data may be uniquely cached for requests with different request parameters (query, post, and route parameters).

When server-side caching is requested and manual-mode is not enabled, the request response will be automatically cached. Subsequent client requests will revalidate the cached content with the server. If the server-side cached content has not expired, a HTTP Not-Modified (304) response will be sent and the client will use its client-side cached content. This results in a very fast transaction with the client as no response data is sent. Server-side caching will cache both the response headers and content.

If manual server-side caching is requested, the response will be automatically cached, but subsequent requests will require the handler to explicitly send cached content by calling httpWriteCached.

If client-side caching is requested, a 'Cache-Control' Http header will be sent to the client with the caching 'max-age' set to the lifespan argument value (converted to seconds). This causes the client to serve client-cached content and to not contact the server at all until the max-age expires. Alternatively, you can use httpSetHeader to explicitly set a 'Cache-Control' header. For your reference, here are some keywords that can be used in the Cache-Control Http header.

'max-age' Maximum time in seconds the resource is considered fresh. 's-maxage' Maximum time in seconds the resource is considered fresh from a shared cache. 'public' marks authenticated responses as cacheable. 'private' shared caches may not store the response. 'no-cache' cache must re-submit request for validation before using cached copy. 'no-store' response may not be stored in a cache. 'must-revalidate' forces clients to revalidate the request with the server. 'proxy-revalidate' similar to must-revalidate except only for proxy caches.

Use client-side caching for static content that will rarely change or for content for which using 'reload' in the browser is an adequate solution to force a refresh. Use manual server-side caching for situations where you need to explicitly control when and how cached data is returned to the client. For most other situations, use server-side caching.
Parameters:
routeHttpRoute object.
methodsList of methods for which caching should be enabled. Set to a comma or space separated list of method names. Method names can be any case. Set to null or '*' for all methods. Example: 'GET, POST'.
urisSet of URIs to cache. If the URI is set to '*' all URIs for that action are uniquely cached. If the request has POST data, the URI may include such post data in a sorted query format. E.g. {uri: /buy?item=scarf&quantity=1}.
extensionsList of document extensions for which caching should be enabled. Set to a comma or space separated list of extensions. Extensions should not have a period prefix. Set to null, '' or '*' for all extensions. Example: 'html, css, js'. The URI may include request parameters in sorted www-urlencoded format. For example: /example.esp?hobby=sailing&name=john.
typesList of document mime types for which caching should be enabled. Set to a comma or space separated list of types. The mime types are those that correspond to the document extension and NOT the content type defined by the handler serving the document. Set to null or '*' for all types. Example: image/gif, application/x-php.
clientLifespanLifespan of client cache items in milliseconds. If not set to positive integer, the lifespan will default to the route lifespan.
serverLifespanLifespan of server cache items in milliseconds. If not set to positive integer, the lifespan will default to the route lifespan.
flagsCache control flags. Select HTTP_CACHE_MANUAL to enable manual mode. In manual mode, cached content will not be automatically sent. Use httpWriteCached in the request handler to write previously cached content.

Select HTTP_CACHE_CLIENT to enable client-side caching. In this mode a 'Cache-Control' Http header will be sent to the client with the caching 'max-age'. WARNING: the client will not send any request for this URI until the max-age timeout has expired.

Select HTTP_CACHE_RESET to first reset existing caching configuration for this route.

Select HTTP_CACHE_SERVER to define the server-side caching mode.

Select HTTP_CACHE_UNIQUE to uniquely cache requests with different request parameters.
API Stability:
Stable.
See Also:
HttpCache, httpUpdateCache
ssize httpUpdateCache (HttpStream *stream, cchar *uri, cchar *data, MprTicks lifespan)

Update the cached content for a URI.

Parameters:
streamHttpStream stream object.
uriThe request URI for which to update the cache. The URI may contain the request parameters in sorted www-urlencoded format. The URI should include any route prefix.
dataData to cache for the URI. If you wish to cache response headers, include those at the start of the data followed by an additional new line.
lifespanLifespan in milliseconds for the cached content.
API Stability:
Stable.
See Also:
HttpCache, httpAddCache
ssize httpWriteCached (HttpStream *stream)

Write the cached content for a URI to the client.

Description:
This call explicitly writes cached content to the client. It is useful when the caching is configured in manual mode via the HTTP_CACHE_MANUAL flag to httpAddCache
Parameters:
streamHttpStream stream object.
API Stability:
Stable.
See Also:
HttpCache, httpAddCache, httpUpdateCache

HttpDir

HttpDir

Directory object for the DirHandler.

API Stability:
Internal.
Fields:
HttpDir * * httpGetDirObj (HttpRoute *route)

Get the HttpDir object for a route.

API Stability:
Stable.

HttpEndpoint

HttpEndpoint

Listening endpoints.

See Also:
httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
API Stability:
Internal.
Fields:
intasync Listening is in async mode (non-blocking).
void *context Embedding context.
MprDispatcher *dispatcher Event dispatcher.
intflags Endpoint control flags.
MprList *hosts List of host objects.
Http *http Http service object.
char *ip Listen IP address. May be null if listening on all interfaces.
HttpLimits *limits Alias for first host, default route resource limits.
boolmultiple Allow multiple binding on the endpoint.
MprMutex *mutex Multithread sync.
HttpNotifiernotifier Default connection notifier callback.
intport Listen port.
MprSocket *sock Listening socket.
MprSsl *ssl SSL configurations to use.
HttpNet * * httpAccept (HttpEndpoint *endpoint, MprEvent *event)

Accept a new connection.

Accept a new client connection on a new socket. If multithreaded, this will come in on a worker thread dedicated to this connection. This is called from the listen wait handler
Parameters:
endpointThe endpoint on which the server was listening.
eventMpr event object.
Returns:
A HttpNet object representing the new network.
API Stability:
Internal.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
void httpAddHostToEndpoint (HttpEndpoint *endpoint, struct HttpHost *host)

Add a host to an endpoint.

Description:
Add the host to the endpoint's list of hosts. A listening endpoint may have multiple virutal hosts.
Parameters:
endpointEndpoint to which the host will be added.
hostHttpHost object to add.
API Stability:
Internal.
See Also:
HttpEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
HttpEndpoint * * httpCreateConfiguredEndpoint (struct HttpHost *host, cchar *home, cchar *documents, cchar *ip, int port)

Create and configure a new endpoint.

Description:
Convenience function to create and configure a new endpoint without using a config file. If no host is supplied, a default host and route are created.
Parameters:
hostOptional HttpHost object.
homeHome directory for configuration files for the endpoint.
documentsDirectory containing the.
ipIP address to use for the endpoint. Set to null to listen on all interfaces.
portListening port number to use for the endpoint.
Returns:
A configured HttpEndpoint object instance.
API Stability:
Internal.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
HttpEndpoint * * httpCreateEndpoint (cchar *ip, int port, MprDispatcher *dispatcher)

Create an endpoint object.

Description:
Creates a listening endpoint on the given IP:PORT. Use httpStartEndpoint to begin listening for client connections.
Parameters:
ipIP address on which to listen.
portIP port number.
dispatcherDispatcher to use. Can be null.
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
void httpDestroyEndpoint (HttpEndpoint *endpoint)

Destroy the endpoint.

Description:
This destroys the endpoint created by httpCreateEndpoint. Calling this routine should not normally be necessary as the garbage collector will invoke as required.
Parameters:
endpointHttpEndpoint object returned from httpCreateEndpoint
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
void * * httpGetEndpointContext (HttpEndpoint *endpoint)

Get the endpoint context object.

Parameters:
endpointHttpEndpoint object created via httpCreateEndpoint
Returns:
The endpoint context object defined via httpSetEndpointContext.
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
int httpIsEndpointAsync (HttpEndpoint *endpoint)
struct HttpHost * HttpHost * httpLookupHostOnEndpoint (HttpEndpoint *endpoint, cchar *name)

Lookup a host name.

Description:
Lookup a host by name in the set of defined hosts for this endpoint.
Parameters:
endpointHttpEndpoint object created via httpCreateEndpoint
nameHost name to search for.
Returns:
An HttpHost object instance or null if the host cannot be found.
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
int httpSecureEndpoint (HttpEndpoint *endpoint, struct MprSsl *ssl)

Secure an endpoint.

Description:
Define the SSL parameters for an endpoint. This must be done before starting listening on the endpoint via httpStartEndpoint
Parameters:
endpointHttpEndpoint object created via httpCreateEndpoint
sslMprSsl object.
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
int httpSecureEndpointByName (cchar *name, struct MprSsl *ssl)

Secure an endpoint by name.

Description:
Define the SSL parameters for an endpoint that is selected by name. This must be done before starting listening on the endpoint via httpStartEndpoint
Parameters:
nameEndpoint name. The endpoint name is comprised of the IP and port. For example: "127.0.0.1:7777".
sslMprSsl object.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
int httpSetEndpointAddress (HttpEndpoint *endpoint, cchar *ip, int port)

Set the endpoint IP address.

Description:
This call defines the endpoint's IP address and port number. If the endpoint has already been started, this will stop and restart the endpoint. Current requests will not be disturbed. This is useful to modify the endpoints address when using dynamically assigned IP addresses.
Parameters:
endpointHttpEndpoint object created via httpCreateEndpoint
ipIP address to use for the endpoint. Set to null to listen on all interfaces.
portListening port number to use for the endpoint.
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
void httpSetEndpointAsync (HttpEndpoint *endpoint, int enable)
void httpSetEndpointContext (HttpEndpoint *endpoint, void *context)
void httpSetEndpointNotifier (HttpEndpoint *endpoint, HttpNotifier fn)

Define a notifier callback for this endpoint.

Description:
The notifier callback will be invoked as Http requests are processed.
Parameters:
endpointHttpEndpoint object created via httpCreateEndpoint
fnNotifier function.
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpStartEndpoint, httpStopEndpoint
int httpStartEndpoint (HttpEndpoint *endpoint)

Start listening for client connections on an endpoint.

Description:
Opens the endpoint socket and starts listening for connections.
Parameters:
endpointHttpEndpoint object created via httpCreateEndpoint
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStopEndpoint
int httpStartEndpoints (void )

Start listening for client connections on all endpoints.

Description:
Opens all endpoints and starts listening for connections.
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint
void httpStopEndpoint (HttpEndpoint *endpoint)

Stop the server listening for client connections.

Description:
Closes the socket endpoint. This preserves connections accepted via the listening endpoint.
Parameters:
endpointHttpEndpoint object created via httpCreateEndpoint
API Stability:
Stable.
See Also:
HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint
void httpStopEndpoints (void )

HttpHost

HttpHost

Host Object.

Description:
A Host object represents a logical host. Several logical hosts may share a single HttpEndpoint.
See Also:
httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
API Stability:
Internal.
Fields:
HttpEndpoint *defaultEndpoint Default endpoint for host.
HttpRoute *defaultRoute Default route for the host.
intflags Host flags.
cchar *hostname Host name portion only.
cchar *name Full host name with port.
void *nameCompiled Compiled name regular expression (not alloced).
struct HttpHost *parent Parent host to inherit aliases, dirs, routes.
MprCache *responseCache Response content caching store.
MprList *routes List of Route defintions.
HttpEndpoint *secureEndpoint Secure endpoint for host.
MprHash *streaming Hash of mime-types use streaming instead of buffering.
int httpAddRoute (HttpHost *host, HttpRoute *route)

Add a route to a host.

Description:
Add the route to the host list of routes. During request route matching, routes are processed in order, so it is important to define routes in the order in which you wish to match them.
Parameters:
hostHttpHost object.
routeRoute to add.
Returns:
"Zero" if the route can be added.
API Stability:
Stable.
See Also:
HttpHost, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
HttpHost * * httpCloneHost (HttpHost *parent)

Clone a host.

Description:
The parent host is cloned and a new host returned. The new host inherites the parent's configuration.
Parameters:
parentParent HttpHost object to clone.
Returns:
The new HttpHost object.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
HttpHost * * httpCreateDefaultHost (void )

Create the default host.

Description:
Create and define a default host. The host is added to the Http service's list of hosts. A default route is created for the host.
Returns:
The new HttpHost object.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
HttpHost * * httpCreateHost (void )

Create a host.

Description:
Create a new host object. The host is added to the Http service's list of hosts.
Returns:
The new HttpHost object.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
HttpHost * * httpGetDefaultHost (void )

Get the default host defined via httpSetDefaultHost.

Returns:
The defaul thost object.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
bool httpGetStreaming (struct HttpStream *stream)

Determine if input body content should be streamed or buffered for requests with content of a given mime type.

Description:
The mime type and URI are used to match the request. If streaming is not defined true or false for the mime and url, this routine return true if the request is not POST or PUT.
Parameters:
streamCurrent request stream.
Returns:
True if input should be streamed. False if it should be buffered.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
void httpResetRoutes (HttpHost *host)

Reset the list of routes for the host.

Parameters:
hostHttpHost object.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpSetHostName, httpSetHostProtocol
void httpSetDefaultHost (HttpHost *host)

Set the default host for all servers.

Parameters:
hostHost to define as the default host.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
void httpSetHostDefaultEndpoint (HttpHost *host, HttpEndpoint *endpoint)

Set the default endpoint for a host.

Description:
The host may have a default endpoint that is used when doing redirections to http.
Parameters:
hostHost to examine.
endpointSecure endpoint to use as the default.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
void httpSetHostDefaultRoute (HttpHost *host, HttpRoute *route)

Set the default route for a host.

Description:
The host has a default route which holds default configuration. Typically the default route is not directly used when routing URIs. Rather other routes inherit from the default route and are used to respond to client requests.
Parameters:
hostHost to examine.
routeRoute to define as the default.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
int httpSetHostName (HttpHost *host, cchar *name)

Set the host name.

Description:
The host name is used when matching client requests to virtual hosts using the Http request Host header. If the host name starts with "*", it will match names that contain the name. If the host name ends with "*", it will match names that start with the name. If the host name begins and ends with a "/", the name is assumed to be a regular expression. Regular expressions may match multiple host names by using the "|" character to separate names.
Parameters:
hostHttpHost object.
nameHost name to use.
Returns:
Zero if successful. May return a negative MPR error code if the name is a regular expression and cannot be compiled.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostProtocol
void httpSetHostProtocol (HttpHost *host, cchar *protocol)

Set the host HTTP protocol version.

Description:
Set the host protocol version to either HTTP/1.0 or HTTP/1.1.
Parameters:
hostHttpHost object.
protocolSet to either HTTP/1.0 or HTTP/1.1.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName
void httpSetHostRoot (HttpHost *host, cchar *root)

Set the server root for a host.

Description:
The server root is used as the default directory to locate configuration files for the host.
Parameters:
hostHttpHost object.
rootDirectory path for the host server root.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
void httpSetHostSecureEndpoint (HttpHost *host, HttpEndpoint *endpoint)

Set the default secure endpoint for a host.

Description:
The host may have a default secure endpoint that is used when doing redirections to https.
Parameters:
hostHost to examine.
endpointSecure endpoint to use as the default.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
int httpSetRouteCanonicalName (HttpRoute *route, cchar *name)

Set the route canonical name.

Description:
The route canonical name is the public perferred name to use for the server for this route. This is used when redirecting client requests for directories.
Parameters:
routeHttpRoute object.
nameHost canonical name to use.
Returns:
Zero if successful. May return a negative MPR error code if the name is a regular expression and cannot be compiled.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol
void httpSetStreaming (struct HttpHost *host, cchar *mime, cchar *uri, bool streaming)

Control if input body content should be streamed or buffered for requests with content of a given mime type and a URI path that starts with the specified URI prefix.

Parameters:
hostHost to modify.
mimeMime type to configure.
uriURI prefix to match.
streamingSet to true to enable streaming for this mime type.
API Stability:
Stable.
See Also:
HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol

HttpLimits

HttpLimits

Http limits.

See Also:
httpCreateLimits, httpEaseLimits, httpInitLimits
API Stability:
Internal.
Fields:
intcacheItemSize Maximum size of a cachable item.
ssizechunkSize Maximum chunk size for transfer encoding.
intclientMax Maximum number of unique clients (ip addresses).
intconnectionsMax Maximum number of simultaneous connections (sockets) for whole server.
intconnectionsPerClientMax Maximum number of simultaneous connections (sockets) per client (ip address).
intframeSize HTTP/2 maximum frame size.
intheaderMax Maximum number of header lines.
intheaderSize Maximum size of the total header.
inthpackMax HTTP/2 maximum size of the hpack header table.
MprTicksinactivityTimeout Timeout for keep-alive and idle requests (msec).
intkeepAliveMax Maximum number of Keep-Alive requests to perform per socket.
intpacketSize Maximum packet size for queues and stages.
intprocessMax Maximum number of processes (CGI).
intrequestMax Maximum number of simultaneous concurrent requests.
MprTicksrequestParseTimeout Time a request can take to parse the request headers (msec).
intrequestsPerClientMax Maximum number of requests per client (ip address).
MprTicksrequestTimeout Time a request can take (msec).
MprOffrxBodySize Maximum size of receive body data.
MprOffrxFormSize Maximum size of form data.
intsessionMax Maximum number of sessions.
MprTickssessionTimeout Time a session can persist (msec).
intstreamsMax HTTP/2 maximum number of streams per connection (both peer and self initiated).
MprOfftxBodySize Maximum size of transmission body content.
inttxStreamsMax HTTP/2 maximum number of streams the peer will permit per connection.
MprOffuploadSize Maximum size of an uploaded file.
inturiSize Maximum size of a uri.
intwebSocketsFrameSize Maximum size of sent WebSocket frames. Incoming frames have no limit except message size.
intwebSocketsMax Maximum number of WebSockets.
intwebSocketsMessageSize Maximum total size of a WebSocket message including all frames.
intwebSocketsPacketSize Maximum size of a WebSocket packet exchanged with the user callback.
MprTickswebSocketsPing Time between pings.
intwindow HTTP/2 Initial rx window size (size willing to receive).
HttpLimits * * httpCloneLimits (HttpLimits *base)

Clone a limits object.

Description:
Clone the limits and allocate a new limits object.
Returns:
The allocated limits object.
API Stability:
Stable.
See Also:
HttpLimits, httpCreateLimits, httpEaseLimits, httpInitLimits
HttpLimits * * httpCreateLimits (int serverSide)

Create a new limits object.

Description:
Create and initialize a new limits object with default values.
Parameters:
serverSideSet to "true" for server side limits. Set to "false" for client side default limits.
Returns:
The allocated limits object.
API Stability:
Stable.
See Also:
HttpLimits, httpEaseLimits, httpInitLimits
void httpEaseLimits (HttpLimits *limits)

Ease the limits.

Description:
This increases the receive body size, transmission body size and upload size to the maximum sizes supported by the system. Client side limits are eased by default.
Parameters:
limitsLimits object. This can be either HttpHost.limits HttpStream.limits or HttpEndpoint.limits.
API Stability:
Stable.
See Also:
HttpLimits, httpCreateLimits, httpInitLimits
void httpInitLimits (HttpLimits *limits, bool serverSide)

Initialize a limits object with default values.

Parameters:
limitsLimits object to modify.
serverSideSet to "true" for server side limits. Set to "false" for client side default limits.
API Stability:
Stable.
See Also:
HttpLimits, httpCreateLimits, httpEaseLimits

HttpMonitor

HttpMonitor

Monitor control structure.

API Stability:
Internal.
Fields:
intcounterIndex Counter item index to monitor.
cchar *counterName Name of counter to monitor.
MprList *defenses List of defensive measures.
intexpr Expression. Set to '<' or '>'.
uint64limit Comparison limit value.
MprTicksperiod Frequence of comparison.
MprEvent *timer Monitor timer.
int httpAddCounter (cchar *name)

Add a counter to be monitored.

Parameters:
nameName of the counter.
Returns:
The counter index in HttpAddress.counters[] to use.
API Stability:
Stable.
int httpAddDefense (cchar *name, cchar *remedy, cchar *args)

Add a defense.

Parameters:
nameName of defensive policy.
remedyRemedy action to invoke. Standard remedies include: ban, cmd, delay, email, http and log. This can be null and the remedy can be specified via REMEDY=remedy in the args.
argsArguments to pass to the remedy. These may include ${tokens}.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
int httpAddDefenseFromJson (cchar *name, cchar *remedy, MprJson *jargs)

Add a defense using JSON arguments.

Parameters:
nameName of defensive policy.
remedyRemedy action to invoke. Standard remedies include: ban, cmd, delay, email, http and log. This can be null and the remedy can be specified via REMEDY=remedy in the args.
jargsArguments to pass to the remedy as a JSON object. These may include ${tokens}.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
int httpAddMonitor (cchar *counter, cchar *expr, uint64 limit, MprTicks period, cchar *defenses)

Add a monitor.

Parameters:
counterName of counter to monitor. Some of the standard counter names are: ActiveClients, ActiveConnections, ActiveRequests, ActiveProcesses, BadRequestErrors, LimitErrors, Memory, NotFoundErrors, NetworkIO, Requests, SSLErrors, TotalErrors.
exprExpression operator. Select from "<" or ">".
limitLimit value to compare with the counter value.
periodTime period over which to determine the counter value.
defensesList of defenses to invoke if the counter exceeds the limit value over the designated period.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
int httpAddRemedy (cchar *name, HttpRemedyProc remedy)

Add a remedy.

Parameters:
nameName of the remedy.
remedyRemedy callback function.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
int httpBanClient (cchar *ip, MprTicks period, int status, cchar *msg)

Ban a client IP from service.

Parameters:
ipClient IP address to ban.
periodPeriod in milliseconds to ban the client.
statusIf non-zero, then return a HTTP response to the client with this HTTP status.
msgIf non-null, then return a HTTP response with this message. If both status and msg are zero and null respectively, then do not send a response to the client, rather immediately close the network connection.
API Stability:
Stable.
void httpDumpCounters (void )

Print the monitor counters to the error log.

API Stability:
Stable.
int64 httpMonitorEvent (struct HttpStream *stream, int counter, int64 adj)

Monitor an event and validate against defined limits and monitored resources.

Description:
The Http library supports a suite of resource limits that restrict the impact of a request on the system. This call validates a processing event for the current request against the server's endpoint limits.
Parameters:
streamHttpStream stream object.
counterThe counter to adjust.
adjValue to adjust the counter by. May be positive or negative.
Returns:
Monitor value after applying the adjustment.
API Stability:
Stable.
int64 httpMonitorNetEvent (struct HttpNet *net, int counter, int64 adj)

Monitor a network event and validate against defined limits and monitored resources.

Description:
The Http library supports a suite of resource limits that restrict the impact of a request on the system. This call validates a processing event for the current request against the server's endpoint limits.
Parameters:
netNetwork object.
counterThe counter to adjust.
adjValue to adjust the counter by. May be positive or negative.
Returns:
Monitor value after applying the adjustment.
API Stability:
Stable.

HttpNet

HttpNet

Control object for the network connection.

See Also:
httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
API Stability:
Internal.
Fields:
HttpAddress *address Per-client IP address reference.
boolasync Network is in async mode (non-blocking).
boolautoDestroy Destroy the network automatically after IO events if appropriate.
MprOffbytesWritten Total bytes written.
HttpNetCallbackcallback Network event callback.
void *context Embedding context (EjsRequest).
void *data Custom data.
intdelay Delay servicing requests due to defense strategy.
booldestroyed Net object has been destroyed.
MprDispatcher *dispatcher Event dispatcher.
struct HttpEndpoint *endpoint Endpoint object (if set - indicates server-side).
booleof Socket has been closed.
boolerror Hard network error - cannot continue.
cchar *errorMsg Error message for the last request (if any).
uinteventMask Last IO event mask.
HttpFrame *frame Current frame being parsed.
HttpQueue *holdq GC hold queue while scheduling.
Http *http Http service object
boolhttp2 Enable http 2.
boolinit Settings frame has been sent and network is ready to use.
HttpQueue *inputq Queue of packets received from the network (http-rx).
HttpIOCallbackioCallback I/O event callback.
MprOffioCount Count of bytes in iovec including file I/O.
MprFile *ioFile File to send.
intioIndex Next index into iovec.
MprOffioPos Position in file.
char *ip Remote client IP address.
MprTickslastActivity Last activity on the connection.
intlastStreamID Last stream ID.
HttpLimits *limits Service limits.
MprDispatcher *newDispatcher New dispatcher if using a worker thread.
intnextStreamID Next stream ID.
MprDispatcher *oldDispatcher Original dispatcher if using a worker thread.
HttpQueue *outputq Queue of packets to write to the network (http-tx).
boolownDispatcher Using own dispatcher and should destroy when closing.
intownStreams Number of peer created streams.
boolparsingHeaders Parsing HTTP/2 headers.
intport Remote port.
intprotocol HTTP protocol: 0 for HTTP/1.0, 1 for HTTP/1.1 or 2+.
boolpush Receiver will accept push.
boolreceivedGoaway Received goaway frame.
HttpHeaderTable *rxHeaders Cache of HPACK rx headers.
boolsecure Using https.
boolsentGoaway Sent goaway frame.
uint64seqno Unique network sequence number.
HttpQueue *serviceq List of queues that require service.
boolservicing Active httpIOEvent. Servicing net request (server side).
intsession Currently parsing frame for this session.
boolsharedDispatcher Dispatcher is shared and should not be destroyed.
boolskipTrace Omit trace from now on.
MprSocket *sock Underlying socket handle.
HttpQueue *socketq Queue of packets to write to the output socket (last queue).
struct HttpStream *stream Single stream for HTTP/1 == streams[0].
MprList *streams List of streams.
inttimeout Network timeout indication.
MprEvent *timeoutEvent Connection or request timeout event.
inttotalRequests Total number of requests serviced.
HttpTrace *trace Tracing configuration.
booltracing Network is tracing packets.
HttpHeaderTable *txHeaders Cache of HPACK tx headers.
intwindow Default HTTP/2 flow control window size for streams tx.
boolworker Use worker.
MprEvent *workerEvent Event for running connection via a worker thread (used by ejs).
boolwriteBlocked Transmission writing is blocked.
int httpConnectNet (HttpNet *net, cchar *ip, int port, MprSsl *ssl)

Connect the network to a remote peer.

Parameters:
netHttpNet Network object created via httpCreateNet
ipRemote IP address to connect to.
portTCP/IP port to connect to.
sslMprSsl object that defines the SSL context.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
HttpNet * * httpCreateNet (MprDispatcher *dispatcher, struct HttpEndpoint *endpoint, int protocol, int flags)

Create a network object.

Description:
The network object defines the underlying network connection over which HttpStream connection streams will be multiplexed.
Parameters:
dispatcherEvent MprDispatcher object to serialize events for the network.
endpointServer-side HttpEndpoint object. Set to NULL for client-side.
protocolHTTP protocol to use by default. Set to 1 for HTTP/1 and 2 for HTTP/2.
flagsSet to HTTP_NET_ASYNC if you wish to use async I/O. Otherwise set to zero.
Returns:
A new network object.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpDestroyNet (HttpNet *net)

Destroy the network object.

Description:
This call closes the network socket, destroys the connection dispatcher, disconnects the HttpStream objects and removes the network from the HttpHost list of networks. All active stream connections (HttpStream) will also be destroyed. Thereafter, the garbage collector can reclaim all memory. It may be called by client connections at any time from a top-level event running on the connection's dispatcher. Server-side code should not explicitly destroy the connection as it will be done automatically via httpIOEvent.
Parameters:
netHttpNet object created via httpCreateNet
API Stability:
Internal.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpEnableNetEvents (HttpNet *net)

Enable network events.

Description:
Network events are automatically disabled upon receipt of an I/O event on a network connection. This permits a network to process the I/O without fear of interruption by another I/O event. At the completion of processing of the I/O request, the network should be re-enabled via httpEnableNetEvents. This call is made for requests in httpIOEvent. Client-side networks may need to enable network events if they are running in async mode and encounter a blocking condition.
Parameters:
netHttpNet Network object created via httpCreateNet
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
bool httpGetAsync (HttpNet *net)

Get the async mode value for the network.

Parameters:
netHttpNet object created via httpCreateNet
Returns:
True if the Network is in async mode.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
cchar * * httpGetProtocol (HttpNet *net)

Get the Http protocol variant for this network connection.

Parameters:
netHttpNet Network object created via httpCreateNet
Returns:
HTTP/1.0, HTTP/1.1 or HTTP/2.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpIOEvent (struct HttpNet *net, MprEvent *event)

Respond to a HTTP I/O event.

Description:
This routine responds to I/O events. If any readable data is present, it allocates a standard sized packet and reads data into this packet and passes to the input queue pipeline.
Parameters:
netHttpNet object created via httpCreateNet
eventEvent structure.
API Stability:
Internal.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpNetError (HttpNet *net, cchar *fmt, ...)

Error handling for the network.

Description:
The httpNetError call is used to flag the current network as failed. If httpNetError is called multiple times, those calls are ignored and only the first call to httpNetError has effect. This call will close all network streams and discard all data in output pipeline queues.
Parameters:
netHttpNet object created via httpCreateNet
fmtPrintf style formatted string.
...Arguments for fmt.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpNetTimeout (HttpNet *net)

Schedule a network connection timeout event on a network.

Description:
This call schedules a timeout event to run serialized on the network's dispatcher. When run, it will cancel all current requests on the network, disconnect the socket and issue an error to the error log. This call is normally invoked by the httpTimer which runs regularly to check for timed out requests.
Parameters:
netHttpNet Network object created via httpCreateNet
API Stability:
Internal.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
bool httpQueuesNeedService (HttpNet *net)

Test if the network queues need service.

Parameters:
netHttpNet object created via httpCreateNet
Returns:
True if there are queues that require servicing.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
bool httpReadIO (HttpNet *net)

Read input from a HTTP connected socket.

Description:
This routine reads I/O events. It allocates a standard sized packet and reads data into this packet and passes to the input queue pipeline.
Parameters:
netHttpNet object created via httpCreateNet
API Stability:
Internal.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpServiceNetQueues (HttpNet *net, int flags)

Service pipeline queues to flow data.

Description:
This routine should not be called by handlers, filters or user applications. It should only be called by the http pipeline and support routines.
Parameters:
netHttpNet object created via httpCreateNet
flagsSet to HTTP_BLOCK to yield for GC if due.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpSetAsync (HttpNet *net, bool async)

Set the async mode value for the network.

Parameters:
netHttpNet object created via httpCreateNet
asyncSet to 1 to enable async mode.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetIOCallback, httpSetNetContext
void httpSetIOCallback (struct HttpNet *net, HttpIOCallback fn)

Define an I/O callback for network connections.

Description:
The I/O callback is invoked when I/O events are detected on the network. The default I/O callback is httpIOEvent
Parameters:
netHttpNet object created via httpCreateNet
fnCallback function to invoke.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetNetContext
void httpSetNetCallback (HttpNet *net, HttpNetCallback callback)

Define a network event callback.

Description:
This callback is invoked when networks closed or receive a peer disconnect.
Parameters:
netIf defined, set the callback on the net object. Otherwise update the default net callback for future network objects.
callbackThe callback is invoked with the signature: void callback(HttpNet *net).
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpSetNetContext (HttpNet *net, void *context)

Set the network context object.

Parameters:
netHttpNet object created via httpCreateNet
contextNew context object. Must be a managed memory reference.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback
void httpSetNetEof (HttpNet *net)

Set the EOF flag in the network to indicate a peer disconnect.

Parameters:
netHttpNet Network object created via httpCreateNet
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpSetNetError (HttpNet *net)

Set the error flag in the network to indicate a peer disconnect.

Parameters:
netHttpNet Network object created via httpCreateNet
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
void httpSetNetProtocol (HttpNet *net, int protocol)

Set the Http protocol variant for this network connection.

Description:
Set the Http protocol variant to use.
Parameters:
netHttpNet Network object created via httpCreateNet
protocolInteger representing the protocol variant. Valid values are: 0 for HTTP/1.0, 1 for HTTP/1.1 and 2 for HTTP/2.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
Socket httpStealSocketHandle (HttpNet *net)

Steal the O/S socket handle from the network socket object.

Description:
This removes the O/S socket handle from active management by the network. After calling, normal request and inactivity timeouts will apply to the network, but will not disturb the underlying actual socket handle. It is the callers responsibility to call close() on the socket handle when ready.
Parameters:
netHttpNet object created via httpCreateNet
Returns:
The O/S Socket handle.
API Stability:
Deprecated.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext

HttpPacket

HttpPacket

Packet object.

Description:
The request/response pipeline sends data and control information in HttpPacket 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 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.
See Also:
HttpFillProc, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
API Stability:
Internal.
Fields:
MprBuf *content Chunk content.
void *data Managed data reference.
MprOffepos Data position in entity (file).
MprOffesize Data size in entity (file).
HttpFillProcfill Callback to fill packet with data.
uintfin Web sockets frame fin bit.
uintflags Packet flags.
uintlast Last packet in a message.
struct HttpPacket *next Next packet in chain.
MprBuf *prefix Prefix message to be emitted before the content.
uintreserved Reserved.
struct HttpStream *stream Reference to owning stream.
uinttype Packet type extension.
void httpAdjustPacketEnd (HttpPacket *packet, MprOff size)

Adjust the packet end position.

Description:
This adjusts the packet content by the given size. The packet length (size) is decremented by the requested amount. If the packet describes entity data, the Packet.esize field is reduced by the requested size amount. If the packet has actual data buffered in Packet.content, the content buffer end position is reduced by by the size amount.
Parameters:
packetPacket to modify.
sizeSize to adjust packet end position.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
void httpAdjustPacketStart (HttpPacket *packet, MprOff size)

Adjust the packet starting position.

Description:
This adjusts the packet content by the given size. The packet position is incremented by start and the packet length (size) is decremented. If the packet describes entity data, the given size amount to the Packet.epos and decrements the Packet.esize fields. If the packet has actual data buffered in Packet.content, the content buffer start is incremeneted by the size amount.
Parameters:
packetPacket to modify.
sizeSize to add to the packet current position.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
HttpPacket * * httpClonePacket (HttpPacket *orig)
HttpPacket * * httpCreateDataPacket (ssize size)

Create a data packet.

Description:
Create a packet and set the HTTP_PACKET_DATA flag Data packets convey data through the response pipeline.
Parameters:
sizeSize of the package data storage.
Returns:
HttpPacket object.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
HttpPacket * * httpCreateEndPacket (void )

Create an end-of-stream packet.

Description:
Create an end-of-stream packet and set the HTTP_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.
Returns:
HttpPacket object.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
HttpPacket * * httpCreateEntityPacket (MprOff pos, MprOff size, HttpFillProc fill)

Create an entity data packet.

Description:
Create an entity packet and set the HTTP_PACKET_DATA flag. Entity packets describe the resource (entity) to send to the client and provide a HttpFillProc procedure used to fill packets with data from the entity.
Parameters:
posPosition within the entity for packet data.
sizeSize of the entity data.
fillHttpFillProc callback to supply the entity data.
Returns:
HttpPacket object.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
HttpPacket * * httpCreateHeaderPacket (void )

Create a response header packet.

Description:
Create a response header packet and set the HTTP_PACKET_HEADER flag. A header packet is used by the pipeline to hold the response headers.
Returns:
HttpPacket object.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
HttpPacket * * httpCreatePacket (ssize size)

Create a data packet.

Description:
Create a packet of the required size.
Parameters:
sizeSize of the package data storage.
Returns:
HttpPacket object.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
ssize httpGetPacketContents (HttpPacket *packet)

Get the packet data contents.

Description:
Get the packet content reference. This is an MprBuf object.
Parameters:
packetPacket to examine.
Returns:
MprBuf reference or zero if there are not contents.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
ssize httpGetPacketLength (HttpPacket *packet)

Get the length of the packet data contents.

Description:
Get the content length of a packet. This does not include the prefix or virtual data length just the pure buffered data contents.
Parameters:
packetPacket to examine.
Returns:
Count of bytes contained by the packet.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
char * * httpGetPacketStart (HttpPacket *packet)
char * * httpGetPacketString (HttpPacket *packet)

Get the packet data contents as a string.

Description:
Get the packet content reference. The packet contents will be null terminated.
Parameters:
packetPacket to examine.
Returns:
A reference to the start of the packet contents.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
bool httpIsLastPacket (HttpPacket *packet)

Test if the packet is the last in a logical message.

Description:
Useful for WebSockets to test if the packet is the last frame in a message.
Parameters:
packetPacket to examine.
Returns:
True if the packet is the last in a message.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
int httpJoinPacket (HttpPacket *packet, HttpPacket *other)

Join two 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.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
HttpPacket * * httpSplitPacket (HttpPacket *packet, ssize 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. NOTE: when splitting packets, the HttpPacket.content reference may be modified.
Parameters:
packetPacket to split.
offsetLocation in the original packet at which to split. This is an offset relative to the current 'start' read position not the beginning of the packet content buffer.
Returns:
New HttpPacket 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.
API Stability:
Stable.
See Also:
HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext

HttpQueue

HttpQueue

Queue object.

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 HttpQueue 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.

Data flows downstream from one queue to the next queue linked via the nextQ field.
See Also:
HttpPacket, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
API Stability:
Internal.
Fields:
HttpQueueCloseclose Close the queue.
ssizecount Bytes in queue (Does not include virt packet data).
intdirection Flow direction.
HttpPacket *first First packet in queue (singly linked).
intflags Queue flags.
HttpPacket *last Last packet in queue (tail pointer).
ssizelow Low water mark for flow control.
ssizemax Advisory maxiumum queue size.
cchar *name Queue name for debugging.
struct HttpNet *net Network connection owning this queue.
struct HttpQueue *nextQ Downstream queue for next stage.
HttpQueueOpenopen Open the queue.
ssizepacketSize Maximum acceptable packet size.
struct HttpQueue *pair Queue for the same stage in the opposite direction.
struct HttpQueue *prevQ Upstream queue for prior stage.
HttpQueueDataput Callback to receive a packet.
void *queueData Stage instance data - must be a managed reference.
struct HttpQueue *scheduleNext Next linkage when queue is on the service queue.
struct HttpQueue *schedulePrev Previous linkage when queue is on the service queue.
HttpQueueServiceservice Service the queue.
intservicing Currently being serviced.
struct HttpStage *stage Stage owning this queue.
HttpQueueStartstart Start the queue.
void *staticData Stage instance data - must be an unmanaged reference.
struct HttpStream *stream Stream owning this queue may be null.
ssizewindow HTTP/2 flow control window size.
void httpDiscardQueueData (HttpQueue *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. Oherwise, just discard the data and preserve the packets.
Parameters:
qQueue reference.
removePacketsIf "true", the data packets will be removed from the queue.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
bool httpFlushQueue (HttpQueue *q, int flags)

Flush queue data.

Description:
This initiates writing buffered data (flushes) by scheduling the queue and servicing the queues.

If blocking mode is selected, all queues will be immediately serviced and the call may block while output drains. If non-blocking, the queues will be serviced but the call will not block nor yield. In blocking mode, this routine may invoke mprYield before it blocks to consent for the garbage collector to trun. Callers must ensure they have retained all required temporary memory before invoking this routine.

This routine when used with HTTP_BLOCK should never be used in filters, connectors or by handlers outside their open, close, ready, start and writable callbacks.
Parameters:
qQueue to flush.
flagsIf set to HTTP_BLOCK, this call will block until the data has drained through the network connector.
Returns:
"True" if there is room for more data in the queue after flushing.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
HttpPacket * * httpGetPacket (struct HttpQueue *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 is full and upstream queues are blocked, they will be enabled.
Parameters:
qQueue reference.
Returns:
The packet removed from the queue.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
ssize httpGetQueueRoom (HttpQueue *q)
bool httpIsEof (struct HttpStream *stream)

Test if the connection has received all incoming content.

Description:
This tests if the connection is at an "End of File condition. @param stream HttpStream object created via #httpCreateStream @return "True" if all Receive content has been received.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
bool httpIsPacketTooBig (struct HttpQueue *q, HttpPacket *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.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
bool httpIsQueueEmpty (HttpQueue *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.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
bool httpIsQueueSuspended (HttpQueue *q)
void httpJoinPacketForService (struct HttpQueue *q, HttpPacket *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.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
void httpJoinPackets (HttpQueue *q, ssize size)

Join packets together.

Description:
This call joins data packets on the given queue into a single packet. The given size specifies the maximum size of data to be joined. The maximum size may also limited by the downstream queue maximum packet size.
Parameters:
qQueue to examine.
sizeThe maximum-sized packet that will be created by joining queue packets is the minimum of the given size and the downstream queues maximum packet size. Note: this routine will not split packets and so the maximum is advisory only.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
bool httpNextQueueFull (HttpQueue *q)
void httpPutBackPacket (struct HttpQueue *q, HttpPacket *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.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
void httpPutForService (struct HttpQueue *q, HttpPacket *packet, bool serviceQ)

Put a packet into the service queue for deferred processing.

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.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
void httpPutPacket (struct HttpQueue *q, HttpPacket *packet)

Put a packet to the queue.

Description:
The packet is passed to the queue by invoking its put() callback. Note the receiving queue may immediately process the packet or it may choose to defer processing by putting to its service queue.
Parameters:
qQueue reference

Note: the garbage collector may run while calling httpSendBlock to reclaim unused packets. It is essential that all required memory be retained by a relevant manager calling mprMark as required.
packetPacket to put.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
void httpPutPacketToNext (struct HttpQueue *qp, HttpPacket *packet)

Put a packet to the next queue downstream.

Description:
Put a packet onto the next downstream queue by calling the downstream queue's put() method. Note the receiving queue may immediately process the packet or it may choose to defer processing by putting to its service queue.
Parameters:
qpQueue reference. The packet will not be queued on this queue, but rather on the queue downstream.
packetPacket to put.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
void httpRemoveQueue (HttpQueue *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.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
void httpReplayPackets (HttpQueue *inq, HttpQueue *outq)

Replay incoming packets through the pipeline.

Description:
This routine is used to process previously received packets once the pipeline is configured. It transfers already received packets back through the new pipeline stages for processing.
Parameters:
inqInput q.
outqOutput q.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
HttpPacket * * httpResizePacket (struct HttpQueue *q, HttpPacket *packet, ssize 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. The q->nextQ will be examined to see if the packet will fit.
packetPacket to put.
sizeIf size is > 0, then also ensure the packet is not larger than this size.
Returns:
Zero if the packet is not resized. Otherwise return the tail packet that was put back onto the queue.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
bool httpResumeQueue (HttpQueue *q, bool force)

Resume a queue.

Description:
Resume a queue for service and schedule it to run. This will cause the service routine to run as soon as possible. This is normally called automatically called by the pipeline when downstream congestion has cleared.
Parameters:
qQueue reference.
forceForce a queue to be scheduled regardless. Set to true to force.
Returns:
True if the queue was resumed.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
void httpScheduleQueue (HttpQueue *q)
void httpSetQueueLimits (HttpQueue *q, HttpLimits *limits, ssize packetSize, ssize low, ssize max, ssize window)

Set a queue's max packetSize and flow control low, max and window thresholds.

Description:
If size parameters are set to -1, default values from the limits are used.
Parameters:
qQueue reference.
limitsDefault limits to use if other arguments are not provided.
packetSizeThe default maximum packet size.
lowThe low water mark. Typically set to packet size by default.
maxThe high water mark. Set by default to packetSize * 4.
windowHTTP/2 flow control window size. Must be at least HTTP_DEFAULT_WINDOW_SIZE.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
void httpSuspendQueue (HttpQueue *q)

Suspend a queue.

Description:
Suspended a queue so that it will not be scheduled for service. The pipeline will will automatically call httpResumeQueue when the downstream queues are less congested.
Parameters:
qQueue reference.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
void httpTransferPackets (HttpQueue *inq, HttpQueue *outq)
bool httpWillNextQueueAcceptPacket (HttpQueue *q, HttpPacket *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 httpPutPacketToNext to send the packet downstream.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
bool httpWillNextQueueAcceptSize (HttpQueue *q, ssize size)

Determine if the downstream queue will accept a certain amount of data.

Description:
Test if the downstream queue will accept data of a given size.
Parameters:
qQueue reference.
sizeSize of data to test for.
Returns:
"True" if the downstream queue will accept the given sized data.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString
bool httpWillQueueAcceptPacket (HttpQueue *q, HttpQueue *nextQ, HttpPacket *packet)

Determine if the given queue will accept this packet.

Description:
Test if the queue will accept a packet. The packet will be resized, if split is true, in an attempt to get the downstream queue to accept it.
Parameters:
qQueue reference.
nextQNext (downstream) queue reference.
packetPacket to put.
Returns:
"True" if the queue will accept the packet.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString
ssize httpWrite (HttpQueue *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 always accepts all the data and will buffer as required. This call may block waiting for the downstream queue to drain if it is or becomes full. Data written after httpFinalizeOutput or httpError is called will be ignored.

Handlers may only call httpWrite in their open, close, ready, start and writable callbacks as these are the only callbacks permitted to block. If a handler needs to write in other callbacks, it should use httpWriteBlock and use the HTTP_NON_BLOCK or HTTP_BUFFER flags.

Filters and connectors must never call httpWrite as it may block.
Parameters:
qQueue reference.
fmtPrintf style formatted string.
...Arguments for fmt.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWriteBlock, httpWriteString
ssize httpWriteBlock (HttpQueue *q, cchar *buf, ssize size, int flags)

Write a block of data to the queue.

Description:
Write a block of data onto the end of the queue. This will queue the data and may initiaite writing to the connection if the queue is full. Data will be appended to last packet in the queue if there is room. Otherwise, data packets will be created as required to store the write data.

This call operates in buffering mode by default unless either the HTTP_BLOCK OR HTTP_NON_BLOCK flag is specified. When blocking, the call will either accept and write all the data or it will fail, it will never return "short" with a partial write.

In blocking mode (HTTP_BLOCK), it blocks for up to the inactivity timeout specified in the stream->limits->inactivityTimeout value. In blocking mode, this routine may invoke mprYield before blocking to consent for the garbage collector to run. Callers must ensure they have retained all required temporary memory before invoking this routine.

In non-blocking mode (HTTP_NON_BLOCK), the call may return having written fewer bytes than requested.

In buffering mode (HTTP_BUFFER), the data is always absorbed without blocking and queue size limits are ignored. In buffering mode, this routine may invoke mprYield if required to consent for the garbage collector to run. Callers must ensure they have retained all required temporary memory before invoking this routine.

Data written after calling httpFinalize, httpFinalizeOutput or httpError will be discarded.
Parameters:
qQueue reference.
bufBuffer containing the write data.
sizeof the data in buf.
flagsSet to HTTP_BLOCK for blocking operation or HTTP_NON_BLOCK for non-blocking. Set to HTTP_BUFFER to buffer the data if required and never block. Set to zero will default to HTTP_BUFFER. This call may yield via mprYield if flags are set to HTTP_BLOCK.
Returns:
The size value if successful or a negative MPR error code.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteString
ssize httpWriteString (HttpQueue *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. Data written after httpFinalizeOutput or httpError is called will be ignored.
Parameters:
qQueue reference.
sString containing the data to write.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, HttpStream, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, httpWillQueueAcceptPacket, httpWrite, httpWriteBlock

HttpRange

HttpRange

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.
See Also:
API Stability:
Internal.
Fields:
MprOffend End byte of range + 1.
MprOfflen Redundant range length.
struct HttpRange *next Next range.
MprOffstart Start of range.

HttpRoute

HttpRoute

Route Control.

Description:
Configuration is not thread safe and must occur at initialization time when the application is single threaded. If the configuration is modified when the application is multithreaded, all requests must be first be quiesced.
See Also:
httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
API Stability:
Internal.
Fields:
HttpAuth *auth Per route block authentication.
boolautoDelete Automatically delete uploaded files.
boolautoFinalize Auto finalize the request (ESP).
MprList *caching Items to cache.
HttpRouteCallbackcallback Route callback hook.
HttpUri *canonical Canonical host name (optional canonial public name for redirections).
cchar *charSet Character set to use with the Content-Type.
cchar *clientConfig Configuration to send to the client.
MprList *conditions Route conditions.
MprJson *config Configuration file content.
HttpStage *connector Network connector to use.
void *context Hosting context (Appweb == EjsPool).
cchar *cookie Cookie name for session data.
intcorsAge Age in seconds of the pre-flight authorization.
boolcorsCredentials Whether to emit an Access-Control-Allow-Credentials.
cchar *corsHeaders Headers to add for Access-Control-Expose-Headers.
cchar *corsMethods Methods to add for Access-Control-Allow-Methods.
cchar *corsOrigin CORS permissible client origins.
MprHash *data Hash of extra data configuration.
cchar *database Name of database for route.
booldebug Application running in debug mode.
char *defaultLanguage Default language.
cchar *documents Documents directory.
char *envPrefix Environment strings prefix.
void *eroute Extended route information for esp.
boolerror Parse or runtime error.
MprHash *errorDocuments Set of error documents to use on errors.
void *extended Extended route information for handlers (only).
MprHash *extensions Hash of handlers by extensions.
intflags Route flags.
HttpStage *handler Fixed handler.
MprList *handlers List of handlers for this route.
MprList *headers Response header values.
cchar *home Home directory for configuration files.
struct HttpHost *host Owning host.
Http *http Http service object (copy of appweb->http).
boolignoreEncodingErrors Ignore UTF8 encoding errors.
MprList *indexes Directory index documents.
MprList *inputStages Input stages.
booljson Response format is json.
MprHash *languages Languages supported.
MprTickslifespan Default lifespan for all cache items in route.
HttpLimits *limits Host resource limits.
MprHash *map Map of alternate extensions (gzip|minified).
MprHash *methods Matching HTTP methods.
MprHash *mimeTypes Hash table of mime types (key is extension).
cchar *mode Application run profile mode (debug|release).
intnextGroup Next route with a different startWith.
char *optimizedPattern Processed pattern (excludes prefix).
MprList *outputStages Output stages.
MprList *params Matching param field data.
struct HttpRoute *parent Parent route.
char *pattern Original matching URI pattern for the route (includes prefix).
void *patternCompiled Compiled pattern regular expression (not alloced).
char *prefix Application scriptName prefix. Set to '' for '/'. Always set.
ssizeprefixLen Prefix length.
intrenameUploads Rename uploaded files.
MprList *requestHeaders Required request header values.
cchar *responseFormat Client response format.
intresponseStatus Response status code.
cchar *source Final source for route target.
cchar *sourceName Source name for route target.
struct MprSsl *ssl SSL configuration.
char *startSegment First starting literal segment of pattern.
ssizestartSegmentLen Prefix length.
char *startWith Starting literal portion of pattern.
ssizestartWithLen Length of startWith.
char *target Route target details.
char *targetRule Target rule.
MprList *tokens Tokens in pattern, {name}.
char *tplate URI template for forming links based on this route (includes prefix).
HttpTrace *trace Per-route tracing configuration.
MprList *updates Route and request updates.
MprHash *vars Route variables. Used to expand Path ${token} refrerences.
MprTickswebSocketsPingPeriod Time between pings (msec).
char *webSocketsProtocol WebSockets sub-protocol.
HttpParseCallback httpAddConfig (cchar *key, HttpParseCallback callback)
void httpAddPermResource (HttpRoute *parent, cchar *resource)
void httpAddPostGroup (HttpRoute *parent, cchar *resource)

Add routes that use POST methods to enable extra parameters to be included in the body.

Useful for a group of resources in a single page application. The resource ID is provided in the request POST body
Description:
This routing adds a set of RESTful routes for a resource group. It will add the following routes:
NameMethodPatternAction
createPOST/NAME/create$create
editGET/NAME/edit$edit
getGET/NAME/get$get
initGET/NAME/init$init
listPOST/NAME/find$find
removeDELETE/NAME/remove$remove
updatePUT/NAME/update$update
actionPOST/NAME/{action}$${action}
Parameters:
parentParent route from which to inherit configuration.
resourceResource name. This should be a lower case, single word, alphabetic resource name.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpAddResource (HttpRoute *parent, cchar *resource)

Add routes for a resource.

Description:
This routing adds a set of RESTful routes for a resource. It will add the following routes:
NameMethodPatternAction
createPOST/NAME(/)*$create
editGET/NAME/edit$edit
getGET/NAME$get
initGET/NAME/init$init
updatePUT/NAME$update
removeDELETE/NAME$remove
default*/NAME/{action}$cmd-${action}
Parameters:
parentParent route from which to inherit configuration.
resourceResource name. This should be a lower case, single word, alphabetic resource name.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpAddResourceGroup (HttpRoute *parent, cchar *resource)

Add routes for a group of resources.

Description:
This routing adds a set of RESTful routes for a resource group. It will add the following routes:
NameMethodPatternAction
createPOST/NAME(/)*$create
editGET/NAME/{id=[0-9]+}/edit$edit
getGET/NAME/{id=[0-9]+}$get
initGET/NAME/init$init
listGET/NAME(/)*$list
removeDELETE/NAME/{id=[0-9]+}$remove
updatePUT/NAME/{id=[0-9]+}$update
actionPOST/NAME/{action}/{id=[0-9]+}$${action}
default*/NAME/{action}$cmd-${action}
Parameters:
parentParent route from which to inherit configuration.
resourceResource name. This should be a lower case, single word, alphabetic resource name.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
HttpRoute * * httpAddRestfulRoute (HttpRoute *parent, cchar *methods, cchar *pattern, cchar *target, cchar *resource)

Define a RESTful route.

Description:
This creates a restful route and then configures it using the given parameters. The route is finalized and added to the parent host.
Parameters:
parentParent route from which to inherit configuration.
methodsHttp methods for which this route is active.
patternMatching URI pattern for which this route will qualify.
targetRoute target string expression. This is used by handlers to determine the physical or virtual resource to serve.
resourceResource basename to use when constructing a source file name.
Returns:
Created route.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
int httpAddRouteCondition (HttpRoute *route, cchar *name, cchar *details, int flags)

Add a route condition.

Description:
A route condition is run after matching the route pattern. For a route to be accepted, all conditions must match. Route conditions are built-in rules that can be applied to routes.
Parameters:
routeRoute to modify.
nameCondition rule to add. Supported conditions are: "auth", "missing", "directory", "exists", and "match". The "auth" rule is used internally to implement basic and digest authentication.

The "missing" rule tests if the target filename is missing. The "missing" rule takes no arguments.

The "directory" rule tests if the condition argument is a directory. The form of the "directory" rule is: "directory pathString". For example: "directory /stuff/${request:pathInfo}.txt"

The "exists" rule tests if the condition argument is present in the file system. The form of the "exists" rule is: "exists pathString". For example: "exists ${request.filename}.gz",

The match directory tests a regular expression pattern against the rest of the condition arguments. The form of the match rule is: "match RegExp string". For example: "match https ${request.scheme}".
detailsCondition parameters. See httpSetRouteTarget for a list of the token values that can be included in the condition rule details.
flagsSet to HTTP_ROUTE_NOT to negate the condition test.
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpAddRouteErrorDocument (HttpRoute *route, int status, cchar *uri)
int httpAddRouteFilter (HttpRoute *route, cchar *name, cchar *extensions, int direction)

Add a route filter.

Description:
This configures the route pipeline by adding processing filters for a request. must match. Route conditions are built-in rules that can be applied to routes.
Parameters:
routeRoute to modify.
nameFilter name to add.
extensionsRequest extensions for which the filter will be run. A request extension may come from the URI if present or from the corresponding filename.
directionSet to HTTP_STAGE_TX for transmit direction and HTTP_STAGE_RX for receive data flow.
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
int httpAddRouteHandler (HttpRoute *route, cchar *name, cchar *extensions)

Add a route handler.

Description:
This configures the route pipeline by adding the given handler. Must only be called at initialization time for the route.
Parameters:
routeRoute to modify.
nameFilter name to add.
extensionsRequest extensions for which the handler will be selected. A request extension may come from the URI if present or from the corresponding filename.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpAddRouteIndex (HttpRoute *route, cchar *path)
int httpAddRouteLanguageDir (HttpRoute *route, cchar *language, cchar *path)

Add a route language directory.

Description:
This configures the route pipeline by adding the given language content directory. When creating filenames for matching requests, the language directory is prepended to the request filename.
Parameters:
routeRoute to modify.
languageLanguage symbolic name. For example: "en" for english.
pathFile system directory to contain content for matching requests.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
int httpAddRouteLanguageSuffix (HttpRoute *route, cchar *language, cchar *suffix, int flags)

Add a route language suffix.

Description:
This configures the route pipeline by adding the given language for request processing. The language definition includes a suffix which will be added to the request filename.
Parameters:
routeRoute to modify.
languageLanguage symbolic name. For example: "en" for english.
suffixExtension suffix to add when creating filenames for the request. For example: "fr" to add to "index.html" could produce: "index.fr.html".
flagsSet to HTTP_LANG_BEFORE to insert the suffix before the filename extension. Set to HTTP_LANG_AFTER to append after the extension. For example: HTTP_LANG_AFTER would produce "index.html.fr".
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpAddRouteMapping (HttpRoute *route, cchar *extensions, cchar *mappings)

Add a route mapping.

Description:
Route mappings will map the request filename by changing the default extension to the mapped extension. This is used primarily to select compressed content.
Parameters:
routeRoute to modify.
extensionsComma separated list of extensions to map. For example: "css,html,js,less,txt,xml" Set to "*" or the empty string to match all extensions.
mappingsList of new file extensions to consider. This may include a "${1}" token to replace the previous extension. The extensions are searched in order and the first matching extensions for which there is an existing file will be selected. For example: "${1}.gz, min.${1}.gz, min.${1}".
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpAddRouteMethods (HttpRoute *route, cchar *methods)
void httpAddRouteParam (HttpRoute *route, cchar *field, cchar *value, int flags)
void httpAddRouteRequestHeaderCheck (HttpRoute *route, cchar *header, cchar *value, int flags)
void httpAddRouteResponseHeader (HttpRoute *route, int cmd, cchar *header, cchar *value)

Add a response header.

Description:
This modifies the response header set.
Parameters:
routeRoute to modify.
cmdSet to HTTP_ROUTE_HEADER_ADD to add a header if it is not already present in the response header set. Set to HTTP_ROUTE_HEADER_REMOVE to remove a header. Set to HTTP_ROUTE_HEADER_SET to define a header and overwrite any prior values. Set to HTTP_ROUTE_HEADER_APPEND to append to an existing header value.
headerHeader field to interrogate.
valueHeader value that will match.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpAddRouteSet (HttpRoute *route, cchar *set)
int httpAddRouteUpdate (HttpRoute *route, cchar *name, cchar *details, int flags)

Add a route update rule.

Description:
This configures the route pipeline by adding processing update rules for a request. Updates are built-in rules that can be applied to routes.
Parameters:
routeRoute to modify.
nameUpdate rule to add. Supported update rules include: "cmd", "field" and "lang".

The "cmd" rule is used to run external commands. For example: "cmd touch /tmp/filename".

The "param" rule is used to set values in the request param fields. For example: "param priority high".

The "lang" update rule is used internally to implement the various language options. See httpSetRouteTarget for a list of the token values that can be included in the condition rule details.
detailsUpdate rule parameters.
flagsReserved.
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpAddSpaGroup (HttpRoute *parent, cchar *resource)

Add routes for a group of resources for use by a single page application.

Description:
This routing adds a set of RESTful routes for a resource group. It will add the following routes:
NameMethodPatternAction
createPOST/NAME(/)*$create
editGET/NAME/{id=[0-9]+}/edit$edit
getGET/NAME/{id=[0-9]+}$get
initGET/NAME/init$init
listPOST/NAME/list$list
removeDELETE/NAME/{id=[0-9]+}$remove
updatePUT/NAME/{id=[0-9]+}$update
actionPOST/NAME/{action}/{id=[0-9]+}$${action}
default*/NAME/{action}$cmd-${action}
Parameters:
parentParent route from which to inherit configuration.
resourceResource name. This should be a lower case, single word, alphabetic resource name.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
HttpRoute * * httpAddWebSocketsRoute (HttpRoute *route, cchar *action)
void httpClearRouteStages (HttpRoute *route, int direction)
HttpRoute * * httpCreateActionRoute (HttpRoute *parent, cchar *pattern, HttpAction action)
HttpRoute * * httpCreateAliasRoute (HttpRoute *parent, cchar *pattern, cchar *path, int status)

Create a route suitable for use as an alias.

Description:
The parent supplies the owning host for the route. A route is not added to its owning host until it is finalized by calling httpFinalizeRoute
Parameters:
parentParent route to inherit from.
patternPattern to match URIs.
pathFile system directory containing documents for this route.
statusHttp redirect status for matching requests. Set to zero if not using redirects.
Returns:
Allocated HttpRoute object.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
HttpRoute * * httpCreateConfiguredRoute (struct HttpHost *host, int serverSide)
HttpRoute * * httpCreateDefaultRoute (struct HttpHost *host)
HttpRoute * * httpCreateInheritedRoute (HttpRoute *route)
HttpRoute * * httpCreateRoute (struct HttpHost *host)
HttpRoute * * httpDefineRoute (HttpRoute *parent, cchar *methods, cchar *pattern, cchar *target, cchar *source)

Define a route.

Description:
This creates a route and then configures it using the given parameters. The route is finalized and added to the parent host.
Parameters:
parentParent route from which to inherit configuration.
methodsHttp methods for which this route is active.
patternMatching URI pattern for which this route will qualify.
targetRoute target string expression. This is used by handlers to determine the physical or virtual resource to serve.
sourceSource file pattern containing the resource to activate or serve.
Returns:
Created route.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpDefineRouteCondition (cchar *name, HttpRouteProc *proc)
HttpRouteSetProc httpDefineRouteSet (cchar *name, HttpRouteSetProc fn)
void httpDefineRouteTarget (cchar *name, HttpRouteProc *proc)
void httpDefineRouteUpdate (cchar *name, HttpRouteProc *proc)
cchar * * httpExpandRouteVars (HttpRoute *route, cchar *str)
void httpFinalizeRoute (HttpRoute *route)
bool httpGetBoolToken (cchar *tok)
HttpRoute * * httpGetDefaultRoute (HttpHost *host)
cchar * * httpGetDir (HttpRoute *route, cchar *name)
HttpRoute * * httpGetHostDefaultRoute (HttpHost *host)
void * * httpGetRouteData (HttpRoute *route, cchar *key)

Get extra route data.

Description:
Routes can store extra configuration information indexed by key. This is used by handlers, filters, connectors and updates to store additional information on a per-route basis.
Parameters:
routeRoute to modify.
keyUnique string key to identify the data.
Returns:
A reference to the route data. Otherwise return null if the route data for the given key was not found.
See Also:
API Stability:
Stable.
cchar * * httpGetRouteDocuments (HttpRoute *route)
cchar * * httpGetRouteHome (HttpRoute *route)
cchar * * httpGetRouteMethods (HttpRoute *route)
cchar * * httpGetRouteTop (HttpStream *stream)
cchar * * httpGetRouteVar (HttpRoute *route, cchar *key)
HttpLimits * * httpGraduateLimits (HttpRoute *route, HttpLimits *limits)
void httpInitConfig (HttpRoute *route)
int httpLoadConfig (HttpRoute *route, cchar *path)
void httpLogRoutes (HttpHost *host, bool full)
HttpRoute * * httpLookupRoute (HttpHost *host, cchar *pattern)
cchar * * httpLookupRouteErrorDocument (HttpRoute *route, int status)
char * * httpMakePath (HttpRoute *route, cchar *dir, cchar *path)

Make a filename path.

Description:
This makes a filename by expanding the tokens "${token}" and then normalizing the path. Relative paths are resolved relative to the optional dir parameter. The supported tokens are:
  • DOCUMENTS_DIR - for the default directory containing documents to serve
  • HOME_DIR - for the directory containing the web server configuration files
  • BIN_DIR - for the shared library directory. E.g. /usr/local/lib/appweb/bin
  • OS - for the operating system name. E.g. LINUX, MACOSX, VXWORKS, or WIN
  • PRODUCT - for the product name
  • VERSION - for the product version. E.g. 4.0.2
Additional tokens can be defined via httpSetRouteVar
Parameters:
routeRoute to modify.
dirDirectory to use as a base directory for relative paths.
pathPath name to examine.
Returns:
A resolved absolute path name.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
cchar * * httpMapContent (HttpStream *stream, cchar *filename)
void httpMapFile (HttpStream *stream)

Map the request URI to a filename in physical storage for a handler.

Description:
This routine is invoked by handlers to map the request URI to a filename and should be called by handlers that serve physical documents. The request URI is resolved relative to the route documents directory. If a route language directory is defined, that directory is prefixed to the filename after the route documents directory.

If route maps have been defined, the filename may be mapped to a preferred compressed or minified filename to serve.

After computing the filename, this routine calls httpSetFilename to set the HttpTx.filename, ext, etag and fileInfo fields. If a filename has already been defined by a prior call to httpMapFile or httpSetFilename, this routine will do nothing. To reset a prior filename, use httpSetFilename with a null argument.
Parameters:
streamHttpStream stream object.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpParseAll (HttpRoute *route, cchar *key, MprJson *prop)
void httpRemoveRouteMethods (HttpRoute *route, cchar *methods)
void httpResetRouteIndexes (HttpRoute *route)
void httpResetRoutePipeline (HttpRoute *route)
void httpSetDir (HttpRoute *route, cchar *name, cchar *value)
void httpSetRouteAuth (HttpRoute *route, HttpAuth *auth)
void httpSetRouteAutoDelete (HttpRoute *route, bool on)
void httpSetRouteAutoFinalize (HttpRoute *route, bool on)
int httpSetRouteConnector (HttpRoute *route, cchar *name)
void httpSetRouteCookie (HttpRoute *route, cchar *cookie)
void httpSetRouteCookiePersist (HttpRoute *route, int enable)
void httpSetRouteCookieSame (HttpRoute *route, cchar *value)
void httpSetRouteData (HttpRoute *route, cchar *key, void *data)
void httpSetRouteDefaultLanguage (HttpRoute *route, cchar *language)
void httpSetRouteDocuments (HttpRoute *route, cchar *path)
void httpSetRouteEnvEscape (HttpRoute *route, bool on)
void httpSetRouteEnvPrefix (HttpRoute *route, cchar *prefix)

Define a prefix string for environment variables.

Description:
When mapping URI query parameters and form variables to environment variables, it is important to prevent important system variables like SHELL, PATH and IFS being overwritten or corrupted. Defining a unique prefix for such parameters ensures they have their own namespace.
Parameters:
routeRoute to modify.
prefixPrefix to use in front of environment variables for URI and form parameters.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpSetRouteFlags (HttpRoute *route, int flags)
int httpSetRouteHandler (HttpRoute *route, cchar *name)
void httpSetRouteHome (HttpRoute *route, cchar *home)
void httpSetRouteIgnoreEncodingErrors (HttpRoute *route, bool on)
void httpSetRouteMethods (HttpRoute *route, cchar *methods)
void httpSetRoutePattern (HttpRoute *route, cchar *pattern, int flags)

Set the route pattern.

Description:
This call defines the route regular expression pattern that is used to match against the request URI. The route pattern is an enhanced JavaScript-compatibile regular expression. It is enhanced by optionally embedding braced tokens "{name}" in the pattern. During request URI matching, these tokens are extracted and defined in the request params and are available to the request. The normal regular expression repeat syntax also uses "{}". To use the traditional (uncommon) repeat syntax, back quote with "\\". Sub-expressions and token expressions are also available in various rules as numbered tokens "$1". For example: the pattern "/app/(.*)(.html)$" will permit a file target "$1.${request.Language=fr}.$2".
Parameters:
routeRoute to modify.
patternRoute regular expression pattern.
flagsSet to HTTP_ROUTE_NOT to negate the pattern match result.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpSetRoutePrefix (HttpRoute *route, cchar *prefix)
void httpSetRoutePreserveFrames (HttpRoute *route, bool on)
void httpSetRouteRenameUploads (HttpRoute *route, bool enable)
void httpSetRouteSessionVisibility (HttpRoute *route, bool visible)
void httpSetRouteShowErrors (HttpRoute *route, bool on)
void httpSetRouteSource (HttpRoute *route, cchar *source)
void httpSetRouteStealth (HttpRoute *route, bool on)
int httpSetRouteTarget (HttpRoute *route, cchar *name, cchar *details)

Set a route target.

Description:
This configures the route pipeline by defining a route target. The route target is interpreted by the selected route handler to process the request. Route targets can contain symbolic tokens that are expanded at run-time with their corresponding values. There are three classes of tokens:
  • System and Route varibles - such as DOCUMENTS_DIR, HOME_DIR, BIN_DIR, PRODUCT, OS, VERSION.
  • Route URI tokens - these are the braced tokens in the route pattern.
  • Request fields - these are request state and property values.
System and URI tokens are of the form: "${token}" where "token" is the name of the variable or URI token. Request fields are of the form: "${family:name=defaultValue}" where the family defines a set of values. If the named field is not present, an optional default value "=defaultValue" will be used instead. These supported request field families are:
  • header - for request HTTP header values
  • param - for request params
  • query - for request query field values
  • request - for request details
  • Any URI pattern token
For example: "run ${header:User-Agent}" to select the client's browser string passed in the HTTP headers. For example: "run ${field:name}" to select the client's browser string passed in the HTTP headers. For example: "run ${name}.html" where {name} was a token in the route pattern. For example: "run ${name}.html" where {name} was a token in the route pattern. The supported request key names are:
  • clientAddress - The client IP address
  • clientPort - The client port number
  • error - Any request or connection error message
  • ext - The request extension
  • extraPath - The request extra path after the script extension
  • filename - The mapped request filename in physical storage
  • language - The selected language for the request
  • languageDir - The langauge directory
  • host - The host name owning the route for the request
  • method - The request HTTP method
  • originalUri - The original, pre-decoded URI
  • pathInfo - The path portion of the URI after the host and port information
  • prefix - The route prefix
  • query - The request query information
  • reference - The request reference fragment. This is the URI portion after "#"
  • scheme - The request protocol scheme. E.g. "http"
  • scriptName - The request script or application name
  • serverAddress - The server IP address
  • serverPort - The server port number
  • uri - The full request URI. May be modified by routes, handlers and filters
Also see httpMakePath for additional tokens (DOCUMENTS_DIR, HOME_DIR, BIN_DIR, PRODUCT, OS, VERSION).
Parameters:
routeRoute to modify.
nameTarget rule to add. Supported update rules include: "close", "redirect", "run" and "write".

The "close" rule is used to do abortive closes for the request. This is useful for ward off known security attackers. For example: "close immediate". The "close" rule takes no addition parameters.

The "redirect" rule is used to redirect the request to a new resource. For example: "redirect 302 /tryAgain.html". The "redirect" takes the form: "redirect status URI". The status code is used as the HTTP response code. The URI can be a fully qualified URI beginning with "http" or it can be a relative URI.

The "run" target is used to run the configured handler to respond to the request. For example: "file ${DOCUMENTS}/${request.uri}.gz".

The "write" rule is used to write literal data back to the client. For example: "write 200 Hello World\r\n". The "write" rule takes the form: "write [-r] status message". Write data is by default HTML encoded to help eliminate XSS security exposures. The "-r" option selects "raw" output and bypasses the HTML encoding of the write data string.

WARNING: Take great care when using raw writes with tokens. Write data is not HTML encoded and echoing back to raw data to the client can cause XSS and other security issues. The status field defines the HTTP status code to use in the response.
detailsUpdate rule parameters.
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev
void httpSetRouteTemplate (HttpRoute *route, cchar *tplate)
void httpSetRouteUploadDir (HttpRoute *route, cchar *dir)
void httpSetRouteVar (HttpRoute *route, cchar *token, cchar *value)
void httpSetRouteXsrf (HttpRoute *route, bool enable)
void httpSetStageData (struct HttpStream *stream, cchar *key, cvoid *data)
char * * httpTemplate (HttpStream *stream, cchar *tplate, MprHash *options)
bool httpTokenize (HttpRoute *route, cchar *str, cchar *fmt, ...)

Tokenize a string based on route data.

Description:
This is a utility routine to parse a string into tokens given a format specifier. Mandatory tokens can be specified with "%" format specifier. Optional tokens are specified with "?" format. Supported tokens:
  • B - Boolean. Parses: on/off, true/false, yes/no.
  • N - Number. Parses numbers in base 10.
  • S - String. Removes quotes.
  • P - Path string. Removes quotes and expands ${PathVars}. Resolved relative to host->dir (Home).
  • W - Parse words into a list
  • %! - Optional negate. Set value to HTTP_ROUTE_NOT present, otherwise zero.
Values wrapped in quotes will have the outermost quotes trimmed.
Parameters:
routeRoute to modify.
strString to expand.
fmtFormat string specifier.
Returns:
True if the string can be successfully parsed.
API Stability:
Stable.
See Also:
HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDocuments, httpLink, httpLinkEx, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteAutoFinalize, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDocuments, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenizev
bool httpTokenizev (HttpRoute *route, cchar *str, cchar *fmt, va_list args)

HttpRx

HttpRx

Http Rx.

Description:
Most of the APIs in the rx group still take a HttpStream object as their first parameter. This is to make the API easier to remember - APIs take a stream object rather than a rx or tx object.
See Also:
HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
API Stability:
Internal.
Fields:
cchar *accept Accept header.
cchar *acceptCharset Accept-Charset header.
cchar *acceptEncoding Accept-Encoding header.
cchar *acceptLanguage Accept-Language header.
cchar *authDetails Header details: authorization|www-authenticate provided by peer.
boolauthenticated Request has been authenticated.
boolauthenticateProbed Request has been authenticated.
cchar *authType Type of authentication: set to basic, digest, post or a custom name.
boolautoDelete Automatically delete uploaded files.
MprOffbytesRead Length of content read by user (includes bytesUloaded).
MprOffbytesUploaded Length of uploaded content by user.
intchunkState Chunk encoding state.
cchar *connection Connection header.
cchar *contentLength Content length string value.
cchar *cookie Cookie header - may contain many cookies.
MprOffdataFrameLength Size of HTTP/2 data frames read.
boolendStream HTTP/2 end of input stream.
booleof All read data has been received by the protocol layer (http*Filter).
boolerrorDoc Processing an error document.
MprList *etags Document etag to uniquely identify the document version.
cchar *extraPath Extra path information (CGI|PHP).
MprList *files List of uploaded files (HttpUploadFile objects).
intflags Rx modifiers.
boolform Using mime-type application/x-www-form-urlencoded.
HttpPacket *headerPacket HTTP headers.
MprHash *headers Header variables.
cchar *hostHeader Client supplied host name header.
MprOffhttp2ContentLength Pre-parsed content-length header for http/2.
boolifMatch If-Match processing requested.
boolifModified If-Modified processing requested.
boolinputEnded End packet appended to input stream.
MprList *inputPipeline Input processing.
HttpRange *inputRange Specified range for rx (post) data.
booljson Using a JSON body.
HttpLang *lang Selected language.
MprOfflength Content length header value (ENV: CONTENT_LENGTH).
cchar *method Request method.
cchar *mimeType Mime type of the request payload (ENV: CONTENT_TYPE).
boolneedInputPipeline Input pipeline required to process received data.
cchar *origin Origin header (not used).
cchar *originalMethod Original method from the client.
cchar *originalUri Original URI passed by the client.
boolownParams Do own parameter handling.
MprJson *params Request params (Query and post data variables).
cchar *paramString Cached param data as a string.
HttpUri *parsedUri Parsed request uri.
cchar *passwordDigest User password digest for authentication.
cchar *pathInfo Path information after the scriptName (Decoded and normalized).
cchar *pragma Pragma header.
char *protocol Request protocol: HTTP/1.0 or HTTP/1.1.
cchar *redirect Redirect route header.
cchar *referrer Refering URL.
MprOffremainingContent Remaining content data to read (in next chunk if chunked).
boolrenameUploads Rename uploaded files to the client specified filename.
MprHash *requestData General request data storage. Set via httpSetStageData
HttpRoute *route Route for request.
cchar *scheme HTTP/2 request scheme.
cchar *scriptName ScriptName portion of the uri (Decoded). May be empty or start with "/".
cchar *securityToken Security form token.
boolseenRegularHeader Seen a regular HTTP/2 header (non pseudo).
intseqno Unique request sequence number.
HttpSession *session Session for request.
boolsessionProbed Session has been resolved.
MprTimesince If-Modified date.
intstatus HTTP response status.
cchar *statusMessage HTTP Response status message.
HttpStream *stream HttpStream object.
boolstreaming Stream incoming content. Forms typically buffer and dont stream.
MprHash *svars Server variables.
char *target Route target.
cchar *traceId Request trace id.
cchar *upgrade Protocol upgrade header.
boolupload Request is using file upload.
cchar *uri Current URI (not decoded, may be rewritten).
cchar *userAgent User-Agent header.
struct HttpWebSocket *webSocket WebSocket state.
int httpAddBodyParams (HttpStream *stream)

Add parameters from the request body content.

Description:
This adds query data to the request params.
Parameters:
streamHttpStream stream object.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Internal.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
void httpAddJsonParams (HttpStream *stream)
void httpAddQueryParams (HttpStream *stream)
bool httpContentNotModified (HttpStream *stream)

Test if the content has not been modified.

Description:
This call tests if the file content to be served has been modified since the client last requested this resource. The client must provide an Etag and Since or If-Modified headers.
Parameters:
streamHttpStream stream object.
Returns:
True if the content is current and has not been modified.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
void httpCreateCGIParams (HttpStream *stream)

Create CGI parameters.

Description:
This call creates request params corresponding to the standard CGI/1.1 environment variables. This is used by the CGI and PHP handlers. It may also be useful to handlers that wish to expose CGI style environment variables through the form vars interface.
Parameters:
streamHttpStream stream object.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
MprOff httpGetContentLength (HttpStream *stream)

Get the receive body content length.

Description:
Get the length of the receive body content (if any). This is used in servers to get the length of posted data and in clients to get the response body length.
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
A count of the response content data in bytes.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
cchar * * httpGetCookie (HttpStream *stream, cchar *name)

Get a request cookie.

Description:
Get a request cookie by name.
Parameters:
streamHttpStream stream object created via httpCreateStream
nameName of cookie retrieve.
Returns:
The cookie value. Return null if the cookie is not defined.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
cchar * * httpGetCookies (HttpStream *stream)

Get the request cookies.

Description:
Get the cookies defined in the current requeset.
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
Return a string containing the cookies sent in the Http header of the last request. Return null if there are not cookies defined.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
cchar * * httpGetHeader (HttpStream *stream, cchar *key)

Get an rx http header.

Description:
Get a http request header value for a given header key.
Parameters:
streamHttpStream stream object created via httpCreateStream
keyName of the header to retrieve.
Returns:
Value associated with the header key or null if the key did not exist in the request.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
MprHash * * httpGetHeaderHash (HttpStream *stream)

Get the hash table of rx Http headers.

Description:
Get the internal hash table of rx headers.
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
Hash table. See MprHash for how to access the hash table.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
char * * httpGetHeaders (HttpStream *stream)

Get all the request http headers.

Description:
Get all the rx headers. The returned string formats all the headers in the form: key: value\nkey2: value2\n.
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
String containing all the headers. The caller must free this returned string.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
char * * httpGetHeadersFromHash (MprHash *hash)
int httpGetIntParam (HttpStream *stream, cchar *var, int defaultValue)

Get a request parm as an integer.

Description:
Get the value of a named form variable as an integer. Request parameters are define via www-urlencoded query or post data contained in the request and route parameters.
Parameters:
streamHttpStream stream object.
varName of the parameter to retrieve.
defaultValueDefault value to return if the variable is not defined. Can be null.
Returns:
Integer containing the parameter variable's value.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
HttpLang * * httpGetLanguage (HttpStream *stream, MprHash *spoken, cchar *defaultLang)

Get the language to use for the request.

Description:
This call tests if the file content to be served has been modified since the client last requested this resource. The client must provide an Etag and Since or If-Modified headers.
Parameters:
streamHttpStream stream object.
spokenHash table of HttpLang records. This is typically route->languages.
defaultLangDefault language to use if none specified in the request Accept-Language header.
Returns:
A HttpLang reference, or null if no language requested or no language found in the spoken table.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
cchar * * httpGetParam (HttpStream *stream, cchar *var, cchar *defaultValue)

Get a request param.

Description:
Get the value of a named request param. Request parameters are define via POST data or www-urlencoded query data.
Parameters:
streamHttpStream stream object.
varName of the request param to retrieve.
defaultValueDefault value to return if the variable is not defined. Can be null.
Returns:
String containing a reference to the the request param's value. Caller should not mutate this value. Returns defaultValue if not defined.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
MprJson * * httpGetParamObj (HttpStream *stream, cchar *var)

Get a parameter as a JSON object.

Description:
Get a JSON subtree for a named parameter from the request parameters. Request parameters are define via www-urlencoded query, post data contained in the request or route parameters.
Parameters:
streamHttpStream stream object.
varName of the parameter to retrieve.
Returns:
JSON object containing the selected subtree.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
MprJson * * httpGetParams (HttpStream *stream)

Get the request params table.

Description:
This call gets the form var table for the current request. Query data and www-url encoded form data is entered into the table after decoding. Use mprLookupKey to retrieve data from the table.
Parameters:
streamHttpStream stream object.
Returns:
MprJson JSON object instance containing the form vars.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
cchar * * httpGetParamsString (HttpStream *stream)

Get the request params table as a string.

Description:
This call gets the request params encoded as a string. The params are always in the same order regardless of the form parameter order. Request parameters include query parameters, form data and routing parameters.
Parameters:
streamHttpStream stream object.
Returns:
A string representation in www-urlencoded format.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
char * * httpGetPathExt (cchar *path)
cchar * * httpGetQueryString (HttpStream *stream)

Get the request query string.

Description:
Get query string sent with the current request.
Parameters:
streamHttpStream stream object.
Returns:
String containing a reference to the request query string. Caller should not mutate this value.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
ssize httpGetReadCount (HttpStream *stream)

Get the number of bytes that can be read from the read queue.

Parameters:
streamHttpStream stream object.
Returns:
The number of bytes available in the read queue for the connection.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
cvoid * * httpGetStageData (struct HttpStream *stream, cchar *key)

Get stage data.

Description:
Stages can store extra configuration information indexed by key. This is used by handlers, filters, connectors and and handlers.
Parameters:
streamHttpStream stream object.
keyKey index into the stage data.
Returns:
A reference to the stage data. Otherwise return null if the route data for the given key was not found.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
int httpGetStatus (HttpStream *stream)
cchar * * httpGetStatusMessage (HttpStream *stream)

Get the Http response status message.

The Http status message is supplied on the first line of the Http response
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
A Http status message.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
bool httpMatchParam (HttpStream *stream, cchar *var, cchar *expected)

Match a form variable with an expected value.

Description:
Compare a form variable and return true if it exists and its value matches.
Parameters:
streamHttpStream stream object.
varName of the form variable.
expectedExpected value to match with.
Returns:
True if the value matches.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
ssize httpRead (HttpStream *stream, char *buffer, ssize size)

Read rx body data.

Description:
This routine will read body data from the connection read queue (HttpStream.readq) which is at the head of the response pipeline.

This call will block depending on whether the connection is in async or sync mode. Sync mode is the default for client connections and async for server connections.

If in sync mode, this call may block to wait for data. If in async mode, the call will not block and will return with whatever data is available.

In sync mode, this routine may invoke mprYield before blocking to consent for the garbage collector to run. Callers must ensure they have retained all required temporary memory before invoking this routine.

This call will block for at most the timeout specified by the connection inactivity timeout defined in HttpStream.limits.inactivityTimeout. Use httpSetTimeout to change the timeout value.

Server applications often prefer to access packets directly from the connection readq which offers a higher performance interface.
Parameters:
streamHttpStream stream object created via httpCreateStream
bufferBuffer to receive read data.
sizeSize of buffer.
Returns:
The number of bytes read. Returns zero for not data. EOF can be detected by testing httpIsEof
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
ssize httpReadBlock (HttpStream *stream, char *buffer, ssize size, MprTicks timeout, int flags)

Read a block of rx body data.

Description:
This routine will read body data and provide control over blocking and call duration.

If in blocking mode (the default for client connections), this call may block to wait for data. If in non-blocking mode (the default for server connections), the call will not block and will return with whatever data is available. The blocking mode is set via the flags parameter.

In blocking mode, this routine may invoke mprYield before blocking to consent for the garbage collector to run. Callers must ensure they have retained all required temporary memory before invoking this routine.

This call will block for at most the timeout specified by the connection inactivity timeout defined in HttpStream.limits.inactivityTimeout. Use httpSetTimeout to change the timeout value.

Server applications should not call httpReadBlock in blocking mode as it will consume a valuable thread. Rather, server apps should perform non-blocking reads or access packets directly from the connection readq which offers a higher performance interface.
Parameters:
streamHttpStream stream object created via httpCreateStream
bufferBuffer to receive read data.
sizeSize of buffer.
timeoutTimeout in milliseconds to wait. Set to -1 to use the default inactivity timeout. Set to zero to wait forever.
flagsSet to HTTP_BLOCK to wait for data before returning. Set to HTTP_NON_BLOCK to read what is available and return without blocking. If set to zero, it will default to HTTP_BLOCK for sync connections and HTTP_NON_BLOCK for async connections.
Returns:
The number of bytes read. Returns zero for not data. EOF can be detected by testing httpIsEof
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
char * * httpReadString (HttpStream *stream)

Read response data as a string.

This will read all rx body and return a string that the caller should free. This will block and should not be used in async mode
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
A string containing the rx body.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
void httpRemoveParam (HttpStream *stream, cchar *var)

Remove a request param.

Description:
Remove the value of a named request param.
Parameters:
streamHttpStream stream object.
varName of the request param to retrieve.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
void httpSetEof (HttpStream *stream)

Set the HttpRx eof condition.

Description:
This routine should be called rather than setting HttpRx.eof manually. This is because it will advance the HttpStream state to HTTP_STATE_FINALIZED if the request and connector have been finalized.
Parameters:
streamHttpStream stream object.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
void httpSetIntParam (HttpStream *stream, cchar *var, int value)

Set an integer request param value.

Description:
Set the value of a named request param to an integer value. Request parameters are define via www-urlencoded query or post data contained in the request and route parameters.
Parameters:
streamHttpStream stream object.
varName of the request param to retrieve.
valueDefault value to return if the variable is not defined. Can be null.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
void httpSetMethod (HttpStream *stream, cchar *method)

Set a new HTTP method for processing.

Description:
This modifies the request method to alter request processing. The original method is preserved in the HttpRx.originalMethod field. This is only useful to do before request routing has matched a route.
Parameters:
streamHttpStream stream object.
methodNew method to use.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
void httpSetParam (HttpStream *stream, cchar *var, cchar *value)

Set a request param value.

Description:
Set the value of a named request param to a string value. Request parameters are define via www-urlencoded query or post data contained in the request and route parameters.
Parameters:
streamHttpStream stream object.
varName of the request param to retrieve.
valueDefault value to return if the variable is not defined. Can be null.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetUri, httpTestParam, httpTrimExtraPath
void httpSetRequestCallback (HttpRequestCallback callback)

Define a request completion callback.

Description:
This callback is invoked when the request is completed.
Parameters:
callbackThe callback is invoked with the signature: void callback(HttpStream *stream).
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath
int httpSetUri (HttpStream *stream, cchar *uri)

Set a new URI for processing.

Description:
This modifies the request URI to alter request processing. The original URI is preserved in the HttpRx.originalUri field. This is only useful to do before request routing has matched a route.
Parameters:
streamHttpStream stream object.
uriNew URI to use. The URI can be fully qualified starting with a scheme ("http") or it can be a partial/relative URI. Missing portions of the URI will be completed with equivalent portions from the current URI. For example: if the current request URI was http://example.com:7777/index.html, then a call to httpSetUri(stream, "/new.html", 0) will set the request URI to http://example.com:7777/new.html. The request script name will be reset and the pathInfo will be set to the path portion of the URI.
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpTestParam, httpTrimExtraPath
int httpTestParam (HttpStream *stream, cchar *var)

Test if a request param is defined.

Parameters:
streamHttpStream stream object.
varName of the request param to retrieve.
Returns:
True if the request param is defined.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTrimExtraPath
void httpTrimExtraPath (HttpStream *stream)

Trim extra path from the URI.

Description:
This call trims extra path information after the uri extension. This is used by CGI and PHP. The strategy is to heuristically find the script name in the uri. This is assumed to be the original uri up to and including first path component containing a "." Any path information after that is regarded as extra path. WARNING: Extra path is an old, unreliable, CGI specific technique. Do not use directories with embedded periods.
Parameters:
streamHttpStream stream object.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam

HttpSession

HttpSession

Session state object.

See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
API Stability:
Internal.
Fields:
MprCache *cache Cache store reference.
MprHash *data Intermediate session data before writing to cache.
intdirty Session updated and needs saving.
char *id Session ID key.
MprTickslifespan Session inactivity timeout (msecs).
intseqno Unique sequence number.
int httpAddSecurityToken (HttpStream *stream, bool recreate)

Add the security token to the response.

Description:
To minimize form replay attacks, a security token may be required for POST requests on a route. This call will set a security token in the response as a response header and as a response cookie. Client-side Javascript must then send this token as a request header in subsquent POST requests. To configure a route to require security tokens, use httpSetRouteXsrf
Parameters:
streamHttp stream object.
recreateSet to true to recreate the security token.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
HttpSession * * httpAllocSession (HttpStream *stream, cchar *id, MprTicks lifespan)

Allocate a new session state object.

Parameters:
streamHttp stream object.
idUnique session state ID.
lifespanSession lifespan in ticks.
Returns:
A session state object.
API Stability:
Internal.
See Also:
httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
bool httpCheckSecurityToken (HttpStream *stream)

Check a security token.

Description:
Check the request security token against the security token defined in the session state.
Parameters:
streamHttp stream object.
Returns:
True if the security token matches the session held token.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
HttpSession * * httpCreateSession (HttpStream *stream)

Create a session object.

Description:
This call creates a session object. If one already exists, it is destroyed and a fresh session is created. Use httpGetSession to retrieve an existing session object.
Parameters:
streamHttp stream object.
Returns:
A session state object.
API Stability:
Internal.
See Also:
httpAllocSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
void httpDestroySession (HttpStream *stream)

Destroy a session state object.

This destroys a session. It will emit an expired cookie to force the client to remove the old session cookie
Description:
Parameters:
streamHttp stream object.
API Stability:
Internal.
See Also:
httpAllocSession, httpCreateSession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
cchar * * httpGetSecurityToken (HttpStream *stream, bool recreate)

Get a unique security token.

Description:
This will get an existing security token or create a new token if one does not exist. If recreate is true, the security token will be recreated. Use httpAddSecurityToken to add the token to the response headers.
Parameters:
streamHttpStream stream object.
recreateSet to true to recreate the security token.
Returns:
The security token string.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
HttpSession * * httpGetSession (HttpStream *stream, int create)

Get a session state object.

This will optionally create a session if one does not already exist. It will not re-create a session that exists
Description:
Parameters:
streamHttp stream object.
createSet to "true" to create a session state object if one does not already exist for this client.
Returns:
A session state object.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
cchar * * httpGetSessionID (HttpStream *stream)

Get the session ID.

Description:
Parameters:
streamHttp stream object.
Returns:
The session ID string.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
MprHash * * httpGetSessionObj (HttpStream *stream, cchar *key)

Get an object from the session state store.

Description:
Retrieve an object from the session state store by deserializing all properties.
Parameters:
streamHttp stream object.
keySession state key.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
cchar * * httpGetSessionVar (HttpStream *stream, cchar *name, cchar *defaultValue)

Get a session state variable.

Parameters:
streamHttp stream object.
nameVariable name to get.
defaultValueIf the variable does not exist, return the defaultValue.
Returns:
The variable value or defaultValue if it does not exist.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
bool httpLookupSessionID (cchar *id)

Lookup a session ID.

Parameters:
idSession ID to lookup.
Returns:
True if the ID is associated with a session.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
int httpRemoveSessionVar (HttpStream *stream, cchar *name)

Remove a session state variable.

Parameters:
streamHttp stream object.
nameVariable name to remove.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpSetSessionObj, httpSetSessionVar
void httpSetSessionNotify (MprCacheProc notifyProc)

Set a notification callback to be invoked for session notification events.

WARNING: the callback may happen on any thread. Use careful locking to synchronize access to data. Take care not to block the thread issuing the callback
Parameters:
notifyProcMprCacheProc notification callback. Invoked for events of interest on cache items. The event is set to MPR_CACHE_NOTIFY_REMOVE when items are removed from the cache. Invoked as:

(*MprCacheProc)(MprCache *cache, cchar *key, cchar *data, int event);.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar
int httpSetSessionObj (HttpStream *stream, cchar *key, MprHash *value)

Set an object into the session state store.

Description:
Store an object in the session state store by serializing all properties.
Parameters:
streamHttp stream object.
keySession state key.
valueObject to serialize. This must be an MprHash object.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionVar
int httpSetSessionVar (HttpStream *stream, cchar *name, cchar *value)

Set a session variable.

Description:
Parameters:
streamHttp stream object.
nameVariable name to set.
valueString variable value to use. This must point to a valid null terminated string.
Returns:
A session state object.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj
int httpWriteSession (HttpStream *stream)

Write the session state to persistent data storage.

Description:
This is called internally by the ESP handler at the completion of any processing.
Parameters:
streamHttp stream object.
API Stability:
Stable.
See Also:
httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar

HttpStage

HttpStage

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 HttpStage 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. The order of these callbacks will vary depending if HttpRx.streaming is set. FileUpload requires streaming and the input callback for some stages in the standard pipeline may be invoked before the request is routed.
See Also:
HttpQueue, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
API Stability:
Internal.
Fields:
void(*close) (HttpQueue *q) Close the stage. Description:Close the stage and cleanup any request resources. Handlers may block or yield in this callback. qQueue instance objectAPI Stability:Stable
MprHash *extensions Matching extensions for this filter.
intflags Stage flags.
void(*incoming) (HttpQueue *q, HttpPacket *packet) Process incoming data. Description:Accept an incoming packet of data. Filters and handlers recieve packets via their incoming callback. They can choose to immediately process or forward the packet, or they can queue the packet on their queue and schedule their incomingService callback for batch processing of all queued packets. This is a common pattern where the incoming routine is not used and packets are automatically queued and the incomingService callback is used to process. Not used by connectors. Stages should not block or yield in this callback. qQueue instance object packetPacket of dataAPI Stability:Stable
void(*incomingService) (HttpQueue *q) Service the incoming data queue. Description:This callback should service packets on the queue and process or forward as appropriate. A service routine should check upstream queues by calling httpWillNextQueueAcceptPacket before forwarding packets to ensure they do not overfow upstream queues. Handlers may not block or yield in this callback. qQueue instance objectAPI Stability:Stable
int(*match) (struct HttpStream *stream, struct HttpRoute *route, int dir) Match a request. Description:This routine is invoked to see if the stage wishes to handle the request. For handlers, the match callback is invoked when selecting the appropriate route for the request. For filters, the callback is invoked subsequently when constructing the request pipeline. If a filter declines to handle a request, the filter will be removed from the pipeline for the specified direction. The direction argument should be ignored for handlers. Handlers and filters must not actually handle the request in the match callback and must not call httpError. Errors can be reported via mprError. Handlers can defer error reporting until their start callback. streamHttpStream stream object routeRoute object dirQueue direction. Set to HTTP_QUEUE_TX or HTTP_QUEUE_RX. Always set to HTTP_QUEUE_TX for handlers. HTTP_ROUTE_OK if the request is acceptable. Return HTTP_ROUTE_REROUTE if the request has been rewritten. Return HTTP_ROUTE_REJECT it the request is not acceptable.API Stability:Stable
MprModule *module Backing module.
char *name Stage name.
int(*open) (HttpQueue *q) Open the stage. Description:Open the stage for this request instance. A handler may service the request in the open routine and may call httpError if required. Handlers may block or yield in this callback. qQueue instance object Zero for success. Otherwise a negative MPR error code.API Stability:Stable
void(*outgoing) (HttpQueue *q, HttpPacket *packet) Process outgoing data. Description:Accept a packet as outgoing data. Not used by handlers as handler generate packets internally. Filters will use this entry point to accept outgoing packets. Filters can choose to immediately process or forward the packet, or they can queue the packet on their queue and schedule their outgoingService callback for batch processing of all queued packets. This is a common pattern where the outgoing routine is not used and packets are automatically queued and the outgoingService callback is used to process data. Filters should not block or yield in this callback. qQueue instance object packetPacket of dataAPI Stability:Stable
void(*outgoingService) (HttpQueue *q) Service the outgoing data queue. Description:This callback should service packets on the queue and process or forward as appropriate. A service routine should check downstream queues by calling httpWillNextQueueAcceptPacket before forwarding packets to ensure they do not overfow downstream queues. Stages should not block or yield in this callback. qQueue instance objectAPI Stability:Stable
char *path Backing module path (from LoadModule).
void(*ready) (HttpQueue *q) The request is now fully ready. Description:This callback will be invoked when all incoming data has been received. The ready callback will not be called if the request already has an error. If a handler finishes processing the request, it should call httpFinalizeOutput in the ready routine. Handlers may block or yield in this callback. qQueue instance objectAPI Stability:Stable
int(*rewrite) (struct HttpStream *stream) Rewrite a request after matching. Description:This callback will be invoked for handlers after matching and selecting the handler. streamHttpStream stream object Zero for success. Otherwise a negative MPR error code.API Stability:Stable
void *stageData Private stage data.
void(*start) (HttpQueue *q) Start the handler. Description:The start callback is primarily responsible for starting the request processing. Depending on the request Content Type, the request will be started at different times. Form requests with a Content-Type of "application/x-www-form-urlencoded", will be started after fully receiving all input data. Other requests will be started immediately after the request headers have been parsed and before receiving input data. This enables such requests to stream large quantities of input data without buffering. The start callback should test the HTTP method in stream->rx->method and only respond to supported HTTP methods. It should call httpError for unsupported methods. The start callback will not be called if the request already has an error. Handlers may block or yield in this callback. qQueue instance objectAPI Stability:Stable
void(*writable) (HttpQueue *q) The outgoing pipeline is writable and can accept more response data. Description:This callback will be invoked after all incoming data has been receeived and whenever the outgoing pipeline can absorb more output data (writable). As such, it may be called multiple times and can be effectively used for non-blocking generation of a response. The writable callback will not be invoked if the request output has been finalized or if an error has occurred. Handlers may block or yield in this callback. qQueue instance objectAPI Stability:Stable
HttpStage * * httpCloneStage (HttpStage *stage)

Create a clone of an existing state.

This is used when creating filters configured to match certain extensions
Parameters:
stageStage object to clone.
Returns:
A new stage object.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
HttpStage * * httpCreateConnector (cchar *name, MprModule *module)

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:
nameName of connector stage.
moduleOptional module object for loadable stages.
Returns:
A new stage object.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
HttpStage * * httpCreateFilter (cchar *name, MprModule *module)

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:
nameName of connector stage.
moduleOptional module object for loadable stages.
Returns:
A new stage object.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
HttpStage * * httpCreateHandler (cchar *name, MprModule *module)

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:
nameName of connector stage.
moduleOptional module object for loadable stages.
Returns:
A new stage object.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
HttpStage * * httpCreateStage (cchar *name, int flags, MprModule *module)

Create a connector stage.

Description:
Create a new stage.
Parameters:
nameName of connector stage.
flagsStage flags.
moduleOptional module object for loadable stages.
Returns:
A new stage object.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
void httpDefaultIncoming (HttpQueue *q, HttpPacket *packet)

Default stage incoming handling.

Description:
This routine provides default incoming handling of data for stages. It puts the packet to the next Stage's incoming service queue or incoming routine if there is no service routine defined.
Parameters:
qQueue object.
packetPacket object.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
void httpDefaultOutgoing (HttpQueue *q, HttpPacket *packet)

Default stage outgoing handling.

Description:
This routine provides default outgoing handling of data for stages. It puts the packet to the next Stage's outgoing service queue or outgoing routine if there is no service routine defined.
Parameters:
qQueue object.
packetPacket to send.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
void httpDefaultService (HttpQueue *q)

Default stage service routine handling.

Description:
This routine provides default service handling of data for stages. It simply sends all packets downstream. It handles flow control automatically.
Parameters:
qQueue object.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
void httpDiscardService (HttpQueue *q)

Stage service routine that discards packets.

Parameters:
qQueue object.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
void httpHandleOptions (struct HttpStream *stream)

Handle a Http Options method request.

Description:
Convenience routine to respond to an OPTIONS request.
Parameters:
streamHttpStream object created via httpCreateStream
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData
struct HttpStage * HttpStage * httpLookupStage (cchar *name)

Lookup a stage by name.

Parameters:
nameName of stage to locate.
Returns:
Stage or NULL if not found.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStageData, httpSetStageData
void * * httpLookupStageData (cchar *name)

Lookup stage data.

Description:
This looks up the stage by name and returns the private stage data.
Parameters:
nameName of the stage concerned.
Returns:
Reference to the stage data block.
API Stability:
Stable.
See Also:
HttpQueue, HttpStage, HttpStream, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultService, httpGetStageData, httpLookupStage, httpSetStageData

HttpStats

HttpStats

HttpStats.

API Stability:
Internal.
Fields:
intactiveClients Current active client IPs.
intactiveConnections Current active connections.
intactiveProcesses Current active processes.
intactiveRequests Current active requests.
intactiveSessions Current active sessions.
uint64cpuUsage Total process CPU usage in ticks.
uint64heap Current application heap memory.
uint64heapFree Current heap memory available.
uint64heapPeak Peak heap memory usage.
uintheapRegions Count of heap memory regions.
uint64heapUsed Current heap memory in use.
uint64mem Current application memory (includes code + data + heap).
uint64memMax Memory heap maximum permitted.
uint64memRedline Memory heap warnHeap limit.
uint64memSessions Memory used for sessions.
uint64ram System total RAM.
uint64totalConnections Total connections accepted.
uint64totalRequests Total requests served.
uint64totalSweeps Total GC sweeps.
intworkersBusy Current busy worker threads.
intworkersIdle Current idle worker threads.
intworkersMax Maximum number of workers in the thread pool.
intworkersYielded Number of busy workers that are yielded for GC.
void httpGetStats (HttpStats *sp)

Get the Http performance statistics.

Parameters:
spReference to a HttpStats structure.
API Stability:
Internal.
char * * httpStatsReport (int flags)

Get an Http performance report.

Parameters:
flagsreserved.
Returns:
String containing the report.
API Stability:
Internal.

HttpStream

HttpStream

Http request stream.

Description:
The HttpStream object represents a logical request stream to a peer. A stream object is created for each request transaction. A stream object uses the underlying HttpNet network object. If using HTTP/2 there may be multiple HttpStream objects multiplexed over a single HttpNet object. If using HTTP/1, a single HttpStream object may service many Http requests due to HTTP/1.1 keep-alive.

In prior versions before HTTP/2, this was called the HttpConn (connection) object. For compatibility, a macro define will redefine HttpConn references to HttpStream.

Each connection has a request timeout and inactivity timeout. These can be set via httpSetTimeout. The set of APIs that block and yield to the garbage collector are:
  • httpFlushQueue(, HTTP_BLOCK)
  • httpWriteBlock(, HTTP_BLOCK)
  • httpSendBlock(, HTTP_BLOCK)
  • httpRead() when in sync mode
  • httpReadBlock(, HTTP_BLOCK)
  • httpWait()
  • httpWriteUploadData
When these APIs block and yield, the garbage collector may reclaim allocated memory that does not have a managed reference. Read Appweb memory allocation at https://embedthis.com/appweb/doc/ref/memory.html.

Some of the HttpStream fields are replicated from the HttpNet object for API compatibility.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
API Stability:
Internal.
Description:
The Action Handler provides a simple mechanism to bind 'C' callback functions with URIs.
API Stability:
Stable.
Fields:
boolactive httpProcess active on this stack.
void *authData Authorization state data.
boolauthRequested Authorization requested based on user credentials.
char *authType Type of authentication: set to basic, digest, post or a custom name.
char *boundary File upload boundary.
boolcompleted Request complete and completeRequest schedule.
void *context Embedding context (EjsRequest).
boolcounted Request counted by/ monitor event.
void *data Custom data for request - must be a managed reference.
booldestroyed Stream has been destroyed.
booldisconnect Must disconnect/reset the connection - can not continue.
MprDispatcher *dispatcher Event dispatcher.
boolencoded True if the password is MD5(username:realm:password).
struct HttpEndpoint *endpoint Endpoint object (if set - indicates server-side).
boolerror An error has occurred and the request cannot be completed.
cchar *errorMsg Error message for the last request (if any).
boolfollowRedirects Follow redirects for client requests.
void *grid Current request database grid for MVC apps.
inth2State HTTP/2 stream state.
HttpHeadersCallbackheadersCallback Callback to fill headers.
void *headersCallbackArg Arg to fillHeaders.
struct HttpHost *host Host object (if relevant).
Http *http Http service object
HttpQueue *inputq Start of the read pipeline (tailFilter-rx).
HttpIOCallbackioCallback I/O event callback.
char *ip Remote client IP address.
intkeepAliveCount Count of remaining Keep-Alive requests for this connection.
MprTickslastActivity Last activity on the connection.
HttpLimits *limits Service limits. Alias to HttpRoute.limits for this request.
void *mark Reference for GC marking.
HttpNotifiernotifier Http state change notification callback.
HttpQueue *outputq End of the write pipeline (tailFilter-tx).
boolownDispatcher Own the dispatcher and should destroy when closing connection.
cchar *password Password for client requests (only).
boolpeerCreated Stream created by peer.
void *pool Pool of VMs.
intport Remote port.
char *protocol Default client protocol: HTTP/1.0 or HTTP/1.1.
char *protocols Supported WebSocket protocols (clients).
boolproxied Stream carried by a proxy connection.
HttpQueue *readq Application queue reading (qhead).
void *record Current request database record for MVC apps.
void *reqData Extended request data for use by web frameworks.
struct HttpRx *rx Rx object for HTTP/1.
HttpQueue *rxHead Receive queue head.
boolsecure Using https.
uint64seqno Unique monotonically increasing sequence number.
intsettingState Running httpSetState.
MprSocket *sock Underlying socket handle.
MprTicksstarted When the request started (ticks).
uint64startMark High resolution tick time of request.
intstate Stream state.
void *staticData Custom data for request - must be an unmanaged reference.
intstreamID Http/2 stream.
boolsuppressTrace Do not trace this connection.
inttargetState Ultimate target state.
inttimeout Timeout indication.
HttpTimeoutCallbacktimeoutCallback Request and inactivity timeout callback.
MprEvent *timeoutEvent Connection or request timeout event.
HttpTrace *trace Tracing configuration.
HttpQueue *transferq After routing, transfer already read packets to this queue for processing.
struct HttpTx *tx Tx object for HTTP/1.
HttpQueue *txHead Transmit queue head.
boolupgraded Request protocol upgraded.
struct HttpUser *user Authorized User record for access checking.
cchar *username Supplied user name.
HttpQueue *writeq Application queue to write outgoing data (handler).
void httpAddInputEndPacket (HttpStream *stream, HttpQueue *q)
void httpBadRequestError (HttpStream *stream, int status, cchar *fmt, ...)
bool httpClientStream (HttpStream *stream)
void void void httpClosePipeline (HttpStream *stream)
int httpCreateEvent (uint64 streamSeqno, HttpEventProc callback, void *data)

Invoke a callback on a stream using a stream sequence number.

Description:
This routine invokes a callback on a stream's event dispatcher in a thread-safe manner. This API is the only safe way to invoke APIs on a stream from foreign threads.
Parameters:
streamSeqnoHttpStream->seqno identifier extracted when running in an MPR (Appweb) thread.
callbackCallback function to invoke. The callback will always be invoked if the call is successful so that you can free any allocated resources. If the stream is destroyed before the event is run, the callback will be invoked and the "stream" argument will be set to NULL.

If is important to check the HttpStream.error and HttpStream.state in the callback to ensure the Stream is in an acceptable state for your logic. Typically you want HttpStream.state to be greater than HTTP_STATE_BEGIN and less than HTTP_STATE_COMPLETE. You may also wish to check HttpStream.error incase the stream request has errored.
dataData to pass to the callback. This is unmanaged data. The caller is responsible for retaining and freeing.
Returns:
"Zero" if the stream can be found and the event is scheduled, Otherwise returns MPR_ERR_CANT_FIND.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpCreatePipeline (HttpStream *stream)
void httpCreateRxPipeline (HttpStream *stream, struct HttpRoute *route)
HttpStream * * httpCreateStream (HttpNet *net, bool peerCreated)

Create a stream object.

Description:
Most interactions with the Http library are via a stream object. It is used for server-side communications when responding to client requests and it is used to initiate outbound client requests. In HTTP/2 networks, connections are multiplexed onto HttpNet objects.
Parameters:
netNetwork object owning the connection. Can be NULL and a HttpNetwork object will be transparently created and defined as HttpStream.net.
peerCreatedSet to true if the connection is being created in response to an incoming peer request.
Returns:
A new stream object.
API Stability:
Internal.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpCreateTxPipeline (HttpStream *stream, struct HttpRoute *route)
void httpDestroyStream (HttpStream *stream)

Destroy the stream object.

Description:
This call closes the connection socket, destroys the connection dispatcher, disconnects the HttpTx and HttpRx property objects and removes the connection from the HttpHost list of connections. Thereafter, the garbage collector can reclaim all memory. It may be called by client connections at any time from a top-level event running on the connection's dispatcher. Server-side code should not need to explicitly destroy the connection as it will be done automatically via httpIOEvent. This routine should not be called deep within the stack as it will zero the HttpStream.http property to signify the connection is destroyed.
Parameters:
streamHttpStream object created via httpCreateStream
API Stability:
Internal.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpDiscardData (HttpStream *stream, int dir)
void httpDisconnectStream (HttpStream *stream)

Disconnect the connection's socket.

Description:
This call will close the socket and signal a connection error by setting connError. Subsequent use of the connection socket will not be possible. It will also set HttpRx.eof and will finalize the request. Used internally when a connection times out and for abortive errors. This should not be generally used. Rather, httpDestroyStream and httpError should be used in preference.
Parameters:
streamHttpStream stream object created via httpCreateStream
API Stability:
Internal.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpEnableUpload (HttpStream *stream)
void httpError (HttpStream *stream, int status, cchar *fmt, ...)

Error handling for the connection.

Description:
The httpError call is used to flag the current request as failed. If httpError is called multiple times, those calls are ignored and only the first call to httpError has effect. This call will discard all data in the output pipeline queues. If some data has already been written to the client the connection will be aborted so the client can get some indication that an error has occurred after the headers have been transmitted.
Parameters:
streamHttpStream stream object created via httpCreateStream
statusHttp status code. The status code can be ored with the flags HTTP_ABORT to immediately abort the connection or HTTP_CLOSE to close the connection at the completion of the request.
fmtPrintf style formatted string.
...Arguments for fmt.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void HttpStream * HttpStream * httpFindStream (uint64 seqno, HttpEventProc proc, void *data)

Find a stream given a stream sequence number.

Description:
Find a stream in a thread-safe manner given a stream sequence number. Each stream has a unique 64-bit sequence number that can be used to retrieve a stream object. When using foreign threads, this is preferable as another thread may disconnect and destroy the stream at any time.

A callback may be provided which will be invoked if the stream is found before returning from the API. This should be used if utilizing this API in a foreign thread. httpFindStream will lock the stream while the callback is invoked.
Parameters:
seqnoHttpStream stream sequence number retrieved from HttpStream.seqno.
procCallback function to invoke with the signature void (*HttpEventProc)(struct HttpStream *stream, void *data);.
dataData to pass to the callback.
Returns:
The steam object reference. Returns NULL if the stream is not found. Only use this value if invoked in an MPR thread. While foreign threads using this API may return a stream reference, the stream may be destroyed before the reference can be used.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void ssize ssize httpGetChunkSize (HttpStream *stream)
cchar * * httpGetError (HttpStream *stream)
char * * httpGetExt (HttpStream *stream)
int httpGetKeepAliveCount (HttpStream *stream)

Get the count of Keep-Alive requests that will be used for this stream object.

Description:
Http Keep-Alive means that the TCP/IP connection is preserved accross multiple requests. This typically means much higher performance and better response. Http Keep-Alive is enabled by default for Http/1.1 (the default). Disable Keep-Alive when talking to old, broken HTTP servers.
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
The maximum count of Keep-Alive requests.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void * * httpGetStreamContext (HttpStream *stream)
int httpGetStreamEventMask (HttpStream *stream)
void * * httpGetStreamHost (HttpStream *stream)
ssize httpGetWriteQueueCount (HttpStream *stream)
void httpLimitError (HttpStream *stream, int status, cchar *fmt, ...)
struct HttpHost * HttpHost * httpMatchHost (HttpNet *net, cchar *hostname)

Match the HttpHost object that should serve this request.

Description:
This selects the appropriate host object for this request. If no suitable host can be found, httpError will be called and stream->error will be set.
Parameters:
netNetwork object created via httpCreateNet
hostnameHost name to select.
Returns:
Host object to serve the request. Also sets stream->host.
API Stability:
Internal.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
MprSsl * * httpMatchSsl (MprSocket *sp, cchar *hostname)
void httpMemoryError (HttpStream *stream)
void httpNotify (HttpStream *stream, int event, int arg)
void httpReadyHandler (HttpStream *stream)
bool httpRequestExpired (HttpStream *stream, MprTicks timeout)

Test if a request has exceeded its timeout limits.

Description:
This tests the request against the HttpLimits.requestTimeout and HttpLimits.inactivityTimeout limits. It uses the HttpStream.started and HttpStream.lastActivity time markers.
Parameters:
streamHttpStream object created via httpCreateStream
timeoutOverriding timeout in milliseconds. If timeout is zero, override default limits and wait forever. If timeout is < 0, use default connection inactivity and duration timeouts. If timeout is > 0, then use this timeout as an additional timeout.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpResetClientStream (HttpStream *stream, bool keepHeaders)
void httpResetCredentials (HttpStream *stream)
void httpRouteRequest (HttpStream *stream)
bool httpServerStream (HttpStream *stream)
void httpSetChunkSize (HttpStream *stream, ssize size)
void httpSetCredentials (HttpStream *stream, cchar *user, cchar *password, cchar *authType)

Set the Http credentials.

Description:
Define a user and password to use with Http authentication for sites that require it. This will be used for the next client connection.
Parameters:
streamHttpStream stream object created via httpCreateStream
userString user.
passwordDecrypted password string.
authTypeAuthentication type. Set to basic or digest. Defaults to nothing.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpSetFileHandler (HttpStream *stream, cchar *path)
void httpSetForkCallback (MprForkCallback proc, void *arg)
void httpSetHeadersCallback (struct HttpStream *stream, HttpHeadersCallback fn, void *arg)
void httpSetKeepAliveCount (HttpStream *stream, int count)

Control Http Keep-Alive for the connection.

Description:
Http Keep-Alive means that the TCP/IP connection is preserved accross multiple requests. This typically means much higher performance and better response. Http Keep-Alive is enabled by default for Http/1.1 (the default). Disable Keep-Alive when talking to old, broken HTTP servers.
Parameters:
streamHttpStream stream object created via httpCreateStream
countCount of Keep-Alive transactions to use before closing the connection. Set to zero to disable keep-alive.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpSetState (HttpStream *stream, int state)

Set the connection state and invoke notifiers.

Description:
The connection states are, in order : HTTP_STATE_BEGIN HTTP_STATE_CONNECTED HTTP_STATE_FIRST HTTP_STATE_PARSED HTTP_STATE_CONTENT HTTP_STATE_READY HTTP_STATE_RUNNING HTTP_STATE_FINALIZED HTTP_STATE_COMPLETE. When httpSetState advances the state it will invoke any registered HttpNotifier. If the state is set to a state beyond the next intermediate state, the HttpNotifier will be invoked for all intervening states. This is true even if the request has no content, the HTTP_STATE_CONTENT will still be visited.
Parameters:
streamHttpStream object created via httpCreateStream
stateNew state to enter.
API Stability:
Internal.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpSetStreamContext (HttpStream *stream, void *context)
void httpSetStreamHost (HttpStream *stream, void *host)
void httpSetStreamNotifier (HttpStream *stream, HttpNotifier notifier)

Define a notifier callback for this connection.

Description:
The notifier callback will be invoked for state changes and I/O events as Http requests are processed. The notifier is invoked when transitioning to these states. i.e. the activities for these states may not yet be complete. The supported events are:
  • HTTP_EVENT_STATE The request is changing state. Valid states are: HTTP_STATE_BEGIN, HTTP_STATE_CONNECTED, HTTP_STATE_FIRST, HTTP_STATE_CONTENT, HTTP_STATE_READY, HTTP_STATE_RUNNING, HTTP_STATE_FINALIZED and HTTP_STATE_COMPLETE. A request will always visit all states and the notifier will be invoked for each and every state. This is true even if the request has no content, the HTTP_STATE_CONTENT will still be visited.
  • HTTP_EVENT_READABLE There is data available to read
  • HTTP_EVENT_WRITABLE The outgoing pipeline can absorb more data. The WRITABLE event is issued when the outgoing pipeline is empties and can absorb more data.
  • HTTP_EVENT_ERROR The request has encountered an error
  • HTTP_EVENT_DESTROY The HttpStream object is about to be destoyed
  • HTTP_EVENT_APP_OPEN The application layer is now open
  • HTTP_EVENT_APP_CLOSE The application layer is now closed
Parameters:
streamHttpStream stream object created via httpCreateStream
notifierNotifier function.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpSetStreamUser (HttpStream *stream, struct HttpUser *user)
void httpSetTimeout (HttpStream *stream, MprTicks requestTimeout, MprTicks inactivityTimeout)

Set the Http inactivity timeout.

Description:
Define an inactivity timeout after which the Http connection will be closed.
Parameters:
streamHttpStream object created via httpCreateStream
requestTimeoutRequest timeout in msec. This is the total time for the request. Set to -1 to preserve the existing value.
inactivityTimeoutInactivity timeout in msec. This is maximum connection idle time. Set to -1 to preserve the existing value.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
void httpSetTimestamp (MprTicks period)
bool httpShouldRenderDirListing (HttpStream *stream)
void httpStartPipeline (HttpStream *stream)
void httpStreamTimeout (HttpStream *stream)

Schedule a connection timeout event on a connection.

Description:
This call schedules an event to run serialized on the connection dispatcher. When run, it will cancels the current request, disconnects the socket and issues an error to the error log. This call is normally invoked by the httpTimer which runs regularly to check for timed out requests.
Parameters:
streamHttpStream stream object created via httpCreateStream
API Stability:
Internal.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline
bool httpVerifyWebSocketsHandshake (HttpStream *stream)
ssize httpWriteUploadData (HttpStream *stream, MprList *formData, MprList *fileData)

Write Http upload body data.

Description:
Write files and form fields as request body data. This will use transfer chunk encoding. This routine will block until all the buffer is written. This routine may invoke mprYield before it blocks to consent for the garbage collector to turn. Callers must ensure they have retained all required temporary memory before invoking this routine.
Parameters:
streamHttp stream object created via httpCreateStream
fileDataList of string file names to upload.
formDataList of strings containing "key=value" pairs. The form data should be already www-urlencoded.
Returns:
Number of bytes successfully written.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout

HttpTrace

HttpTrace

Trace management structure.

API Stability:
Stable.
Fields:
intbackupCount Trace logger backup count.
MprBuf *buf Output buffer.
MprHash *events Configuration of events.
MprFile *file Trace logger file object.
intflags Trace control flags (append|anew).
cchar *format Output format (used by Common Log Format).
HttpTraceFormatterformatter Trace formatter.
MprTimelastMark When lastTime was last updated.
cchar *lastTime Most recent time string.
intlevel Trace level.
HttpTraceLoggerlogger Trace logger.
ssizemaxContent Maximum content size to trace.
MprMutex *mutex Multithread sync.
struct HttpTrace *parent Parent trace.
cchar *path Trace logger filename.
MprOffsize Max log size.
void httpCommonFormatter (HttpTrace *trace, cchar *event, cchar *type, int flags, cchar *buf, ssize len, cchar *fmt, va_list args)

Common Log trace formatter.

Parameters:
traceHttpTrace object.
eventEvent to trace.
typeEvent type.
flagsFormatting flags.
bufData buffer to trace.
lenLength of the data buf.
fmtPrintf style formatted string.
argsVarargs arguments for fmt.
API Stability:
Stable.
HttpTrace * * httpCreateTrace (HttpTrace *parent)

Create a trace object.

Description:
If parent is defined, inherit default settings from the parent.
Parameters:
parentParent trace object from which to inherit settings.
API Stability:
Stable.
void httpDetailFormatter (HttpTrace *trace, cchar *event, cchar *type, int flags, cchar *buf, ssize len, cchar *fmt, va_list args)

Detailed log trace formatter.

Parameters:
traceHttpTrace object.
eventEvent to trace.
typeEvent type to trace.
flagsFormatting flags.
bufData buffer to trace.
lenLength of the data buf.
fmtPrintf style formatted string.
argsVarargs arguments for fmt.
API Stability:
Stable.
void httpFormatTrace (HttpTrace *trace, cchar *event, cchar *type, int flags, cchar *buf, ssize len, cchar *fmt, va_list args)

Convenience routine to format trace via the configured formatter.

Description:
The formatter will invoke the trace logger and actually write the trace mesage.
Parameters:
traceHttpTrace object.
typeEvent type to trace.
flagsFormatting flags.
eventEvent name to trace.
bufTrace data buffer to write.
lenLength of data buffer.
fmtPrintf style formatted string.
argsVarargs arguments for fmt.
API Stability:
Stable.
int httpGetTraceLevel (HttpTrace *trace)

Get the current tracing level.

Returns:
The tracing level 0-5.
Parameters:
traceTrace object.
API Stability:
Stable.
bool httpLog (HttpTrace *trace, cchar *event, cchar *type, cchar *fmt, ...)

Log (trace) an event of interest.

Description:
The Http trace log is for operational request and server messages and should be used in preference to the MPR error log which should be used only for configuration and hard system-wide errors.
Parameters:
traceHttpTrace object. Typically used via HttpStream.trace or HttpNet.trace.
eventEvent name to trace. Typically dot separated module names.
typeEvent type to trace. Events are grouped into types that are traced at the same level. The standard set of types and their default trace levels are: debug: 1, error: 1, request:2, result:2, headers: 3, context:4, packet:5, detail:6. Users can create custom types. The request type is used for the initial http request line. The result type is used for the request status. The context type is used for general information including http headers. The form type is used for POST form data. The body type is used for request body data.

Context type events may include a "msg" value field. By convention, these messages should be aggregated by trace formatters so that subsequent context events do not overwrite prior msg values.

Event types are orthogonal to event names.
fmtPrintf style format string. String should be comma separated key=value pairs.
...Arguments for fmt.
Returns:
True if the event was traced.
API Stability:
Stable.
void httpLogCompleteRequest (struct HttpStream *stream)

Trace the completion of a request.

Description:
This traces the request metrics.
Parameters:
streamHttpStream object.
API Stability:
Stable.
void void void httpLogRxPacket (struct HttpNet *net, cchar *buf, ssize len)

Trace a packet received from the network.

Parameters:
netHttpNet object.
bufData buffer to trace.
lenSize of buffer.
API Stability:
Stable.
void httpLogTxPacket (struct HttpNet *net, ssize len)

Trace packets sent to the network.

Description:
This traces the packets referenced by net->socketq->iovec.
Parameters:
netHttpNet object.
lenLength in bytes actually written.
API Stability:
Stable.
void httpPrettyFormatter (HttpTrace *trace, cchar *event, cchar *type, int flags, cchar *buf, ssize len, cchar *fmt, va_list args)

Pretty log trace formatter for debugging.

Parameters:
traceHttpTrace object.
eventEvent to trace.
typeEvent type to trace.
flagsFormatting flags.
bufData buffer to trace.
lenLength of the data buf.
fmtPrintf style formatted string.
argsVarargs arguments for fmt.
API Stability:
Stable.
void httpSetTraceContentSize (HttpTrace *trace, ssize size)

Set the maximum content size to trace.

Description:
Tracing will be suspended for files that are larger than this size.
Parameters:
traceTracing object.
sizeMaximum content size to trace.
API Stability:
Stable.
void httpSetTraceEventLevel (HttpTrace *trace, cchar *type, int level)

Configure the tracing level for an event type.

Parameters:
traceTracing object.
typeEvent type to modify.
levelDesired trace level (0-5).
API Stability:
Stable.
void httpSetTraceFormat (HttpTrace *trace, cchar *format)

Set the logging format.

Description:
This is used by the Common log formatter to define the fields written to the log.
Parameters:
traceTrace object.
formatThe format string defaults to: "%h %l %u %t \"%r\" %>s %b %n".
API Stability:
Stable.
HttpTraceFormatter httpSetTraceFormatter (HttpTrace *trace, HttpTraceFormatter callback)

Set the formatter callback to use with a trace object.

Description:
The trace formatter should.
Parameters:
traceTrace object to configure.
callbackFormatter callback.
Returns:
Prior trace formatter.
API Stability:
Stable.
void httpSetTraceFormatterName (HttpTrace *trace, cchar *name)

Define the trace formatter by name.

Parameters:
traceTracing object.
nameFormatter name. Set to "common" for the Common Log format or "detail" for the Appweb detailed trace format.
API Stability:
Stable.
void httpSetTraceLevel (HttpTrace *trace, int level)

Set the current tracing verbosity level.

Description:
This call defines the maximum trace level of messages that will be traced. Trace events have an associated verbosity level at which they will be enabled. If the event level is greater than the defined tracing verbosity level, the event is ignored.
Parameters:
levelNew tracing level. Must be 0-5 inclusive.
traceTrace object.
API Stability:
Stable.
int httpSetTraceLogFile (HttpTrace *trace, cchar *path, ssize size, int backup, cchar *format, int flags)

Configure the request trace log.

Parameters:
traceHttpTrace object.
pathPath for request trace log file.
sizeMaximum size of the log file before archiving.
backupSet to true to create a backup of the log file if archiving.
formatLog file format.
flagsSet to MPR_LOG_ANEW to archive the log when the application reboots.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
void httpSetTraceLogger (HttpTrace *trace, HttpTraceLogger callback)

Set the trace callback to use with a trace object.

Description:
The trace logger is responsible for taking formatted messages and writing to the log.
Parameters:
traceTrace object to configure.
callbackTrace logger callback.
API Stability:
Stable.
bool httpShouldTrace (HttpTrace *trace, cchar *type)

Should trace be emitted.

Parameters:
traceTracing object.
typeEvent type to consider.
API Stability:
Stable.
Returns:
True if trace should be emitted.
int httpStartTracing (cchar *traceSpec)

Start tracing for the given trace log file when instructed via a command line switch.

Parameters:
traceSpecSet the trace log file name and level. The format is "pathName[:level]". The following levels are generally observed:
  • 0 - Essential messages, fatal errors and critical warnings
  • 1 - Hard errors
  • 2 - Configuration setup and soft warnings
  • 3 - Useful informational messages
  • 4 - Debug information
  • 5 - Most verbose levels of messages useful for debugging
If the traceSpec is null, not tracing is enabled.
Returns:
Zero if successful, otherwise a negative Mpr error code. See the Appweb log for diagnostics.
API Stability:
Stable.
void httpWriteTrace (HttpTrace *trace, cchar *buf, ssize len)

Convenience routine to write data to the trace logger.

Should only be used by formatters
Parameters:
traceHttpTrace object.
bufTrace message to write.
lenLength of message.
API Stability:
Stable.
void httpWriteTraceLogFile (HttpTrace *trace, cchar *buf, ssize len)

Write a message to the trace file logger.

Parameters:
traceHttpTrace object.
bufMessage to write.
lenLength of message.
API Stability:
Stable.

HttpTx

HttpTx

Http Tx.

Description:
The tx object controls the transmission of data. This may be client requests or responses to client requests. Most of the APIs in the Response group still take a HttpStream object as their first parameter. This is to make the API easier to remember - APIs take a stream object rather than a rx or transmission object.
See Also:
HttpRx, HttpStream, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
API Stability:
Internal.
Fields:
boolallDataSent Processed the last data packet.
cchar *altBody Alternate transmission for errors.
MprOffbytesWritten Bytes written including headers.
HttpCache *cache Cache control entry (only set if this request is being cached).
MprBuf *cacheBuffer Response caching buffer.
ssizecacheBufferLength Current size of the cache buffer data.
cchar *cachedContent Retrieved cached response to send.
cchar *charSet Character set to use with the Content-Type.
ssizechunkSize Chunk size to use when using transfer encoding. Zero for unchunked.
HttpStage *connector Network connector to send / receive socket data.
MprHash *cookies Browser cookies.
HttpRange *currentRange Current range being fullfilled.
MprOffentityLength Original content length before range subsetting.
cchar *errorDocument Error document to render.
char *etag Unique identifier tag.
cchar *ext Filename extension.
MprFile *file File to be served.
MprPathfileInfo File information if there is a real file to serve.
cchar *filename Name of a real file being served (typically pathInfo mapped).
MprOfffilePos Position in file.
boolfinalized Request response generated and handler processing is complete.
boolfinalizedConnector Connector has finished sending the response.
boolfinalizedInput Handler has finished processing all input.
boolfinalizedOutput Handler or surrogate has finished writing output.
uintflags Response flags.
HttpStage *handler Final handler serving the request.
MprHash *headers Transmission headers.
ssizeheaderSize Size of the header written.
MprOfflength Transmission content length.
cchar *method Client request method GET, HEAD, POST, DELETE, OPTIONS, PUT, TRACE.
cchar *mimeType Mime type of the request payload.
boolneedChunking Use chunk encoding.
MprList *outputPipeline Output processing.
HttpRange *outputRanges Data ranges for tx data.
HttpUri *parsedUri Client request uri.
boolpendingFinalize Call httpFinalize again once the Tx pipeline is created.
boolputEndPacket Handler has manually put the END package (httpFinalizeOutput to skip).
char *rangeBoundary Inter-range boundary.
MprOffrangePos Current range I/O position in response data.
boolresponded The handler has started to respond. Some output has been initiated.
uintsimplePipeline Output pipeline doesn't use custom filters or HTTP/2, SSL or ranges.
boolstarted Handler has been started.
boolstartedHeader Already started sending at least one header packet in the output queue.
intstatus HTTP response status.
struct HttpStream *stream Current HttpStream object.
inttraceMethods Handler methods supported.
char *webSockKey Sec-WebSocket-Key header.
void httpAddHeader (HttpStream *stream, cchar *key, cchar *fmt, ...)

Add a header to the transmission using a format string.

Description:
Add a header if it does not already exits.
Parameters:
streamHttpStream stream object created via httpCreateStream
keyHttp response header key.
fmtPrintf style formatted string to use as the header key value.
...Arguments for fmt.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void void void httpAddHeaderString (HttpStream *stream, cchar *key, cchar *value)
void httpAppendHeader (HttpStream *stream, cchar *key, cchar *fmt, ...)

Append a transmission header.

Description:
Set the header if it does not already exists. Append with a ", " separator if the header already exists.
Parameters:
streamHttpStream stream object created via httpCreateStream
keyHttp response header key.
fmtPrintf style formatted string to use as the header key value.
...Arguments for fmt.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void void void httpAppendHeaderString (HttpStream *stream, cchar *key, cchar *value)

Append a transmission header string.

Description:
Set the header if it does not already exists. Append with a ", " separator if the header already exists.
Parameters:
streamHttpStream stream object created via httpCreateStream
keyHttp response header key.
valueValue to set for the header.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
int httpConnect (HttpStream *stream, cchar *method, cchar *uri, struct MprSsl *ssl)

Connect to a server and issue Http client request.

Description:
Start a new Http request on the http object and return. This routine does not block. After starting the request, you can use httpWait to wait for the request to achieve a certain state or to complete.
Parameters:
streamHttpStream stream object created via httpCreateStream
methodHttp method to use. Valid methods include: "GET", "POST", "PUT", "DELETE", "OPTIONS" and "TRACE".
uriURI to fetch.
sslSSL configuration to use if a secure connection.
Returns:
"Zero" if the request was successfully sent to the server. Otherwise a negative MPR error code is returned.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
HttpPacket * * httpCreateHeaders (HttpQueue *q, HttpPacket *packet)

Create a HTTP header packet.

Description:
Write the Http transmission headers into the given packet. 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 transmission length. This way, a non-chunked transmission can be sent with a content-length header. This is the fastest HTTP transmission.
Parameters:
qQueue owning the packet.
packetPacket into which to place the headers.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
HttpTx * * httpCreateTx (HttpStream *stream, MprHash *headers)
void httpDestroyTx (HttpTx *tx)
void httpFinalize (HttpStream *stream)

Indicate the request is finalized.

Description:
Calling this routine indicates that the handler has fully finished processing the request including processing all input, generating a full response and any other required processing. This call will invoke httpFinalizeOutput and then set the request finalized flag. If the request is already finalized, this call does nothing. A handler MUST call httpFinalize when it has completed processing a request. As background: there are three finalize concepts: HttpTx.finalizedOutput means the handler has generated all the response output but it may not yet be fully transmited through the pipeline and to the network by the connector. HttpTx.finalizedConnector means the connector has sent all the output to the network. HttpTx.finalized means the application has fully processed the request including reading all the input data it wishes to read and has generated all the output that will be generated. A fully finalized request has both HttpTx.finalized and HttpTx.finalizedConnector true.
Parameters:
streamHttpStream stream object.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpFinalizeConnector (HttpStream *stream)
void httpFinalizeHttp2Stream (HttpStream *stream)
void httpFinalizeInput (HttpStream *stream)

Finalize receiption of the http content.

Description:
This routine should be called by clients and Handlers to signify that all processing of the input is complete. the request or response body.
Parameters:
streamHttpStream Queue object.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpFinalizeOutput (HttpStream *stream)

Finalize transmission of the http response.

Description:
This routine should be called by applications and handlers to signify the end of the body content being sent with the request or response body. This call will force the transmission of buffered content to the peer. HttpFinalizeOutput will set the HttpTx.finalizedOutput flag and write a final chunk trailer if using chunked transfers. If the output is already finalized, this call does nothing. Note that after finalization, incoming content may continue to be processed. i.e. httpFinalizeOutput can be called before all incoming data has been received. Use httpFinalizeInput to signify that processing all input is complete.

The difference between httpFinalize and httpFinalizeOutput is that httpFinalize implies that all request processing is complete including both input and output. Whereas httpFinalizeOutput implies that the output is generated. Note that while the output may be fully generated, it may not be fully transmitted by the pipeline and connector. When the output is fully transmitted, the connector will call httpFinalizeConnector
Parameters:
streamHttpStream Queue object.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpFlush (HttpStream *stream)

Flush transmit data.

Description:
This call initiates writing buffered data an will not block. If you need to wait until all the data has been written to the socket, use httpFlushAll. Handlers may only call this routine in their open, close, ready, start and writable callbacks.
Parameters:
streamHttpStream stream object created via httpCreateStream
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpFlushAll (HttpStream *stream)

Flush transmit data and wait for all the data to be written to the socket.

Description:
This call initiates writing buffered data. If in sync mode this call may block until the output queues drain. In sync mode, this may invoke mprYield before blocking to consent for the garbage collector to run. Callers must ensure they have retained all required temporary memory before invoking this routine. Filters and connectors should not call this routine as it may block. Use httpFlush in filters or connectors. Handlers may only call this routine in their open, close, ready, start and writable callbacks. See httpFlush if you do need to wait for all the data to be written to the socket.
Parameters:
streamHttpStream stream object created via httpCreateStream
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpFollowRedirects (HttpStream *stream, bool follow)

Follow redirctions.

Description:
Enabling follow redirects enables the Http service to transparently follow 301 and 302 redirections and fetch the redirected URI.
Parameters:
streamHttpStream stream object created via httpCreateStream
followSet to true to enable transparent redirections.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpFormatError (HttpStream *stream, int status, cchar *fmt, ...)

Format an error transmission.

Description:
Format an error message to use instead of data generated by the request processing pipeline. This is typically used to send errors and redirections. The message is also sent to the error log.
Parameters:
streamHttpStream stream object created via httpCreateStream
statusHttp response status code.
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.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void ssize ssize httpFormatResponse (HttpStream *stream, cchar *fmt, ...)

Format an alternate response.

Description:
Format a response to use instead of data generated by the request processing pipeline. This is used for alternate responses that are not errors.
Parameters:
streamHttpStream stream object created via httpCreateStream
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 transmission body.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
ssize httpFormatResponseBody (HttpStream *stream, cchar *title, cchar *fmt, ...)

Format a response body.

Description:
Format a transmission body to use instead of data generated by the request processing pipeline. The body will be created in HTML or in plain text depending on the value of the request Accept header. This call is used for alternate responses that are not errors.
Parameters:
streamHttpStream stream object created via httpCreateStream
titleTitle string to format into the HTML transmission 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 transmission body.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void ssizessize ssize ssize httpFormatResponsev (HttpStream *stream, cchar *fmt, va_list args)

Format an alternate response.

Description:
Format a response to use instead of data generated by the request processing pipeline. This is similar to httpFormatResponse
Parameters:
streamHttpStream stream object created via httpCreateStream
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.
argsVarargs style list of arguments.
Returns:
A count of the number of bytes in the transmission body.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
ssizecchar * cchar * httpGetTxHeader (HttpStream *stream, cchar *key)

Get a tx http header.

Description:
Get a http response header value for a given header key.
Parameters:
streamHttpStream stream object created via httpCreateStream
keyName of the header to retrieve.
Returns:
Value associated with the header key or null if the key did not exist in the response.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
int httpIsChunked (HttpStream *stream)
int httpIsFinalized (HttpStream *stream)
int httpIsOutputFinalized (HttpStream *stream)

Test if request response has been fully generated.

Description:
This call tests if all transmit data has been generated and finalized. Handlers call httpFinalizeOutput to signify the end of transmit data.
Parameters:
streamHttpStream stream object.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
bool httpNeedRetry (HttpStream *stream, cchar **url)

Determine if the transmission needs a transparent retry to implement authentication or redirection.

This is used by client requests. If authentication is required, a request must first be tried once to receive some authentication key information that must be resubmitted to gain access
Parameters:
streamHttpStream stream object created via httpCreateStream
urlReference to a string to receive a redirection URL. Set to NULL if not redirection is required.
Returns:
True if the request needs to be retried.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpRedirect (HttpStream *stream, int status, cchar *uri)
void httpRemoveCookie (HttpStream *stream, cchar *name)

Remove a cookie from the client (browser) This will emit a Set-Cookie response header with the value set to "" and a one second lifespan.

Parameters:
streamHttpStream stream object created via httpCreateStream
nameName of the cookie created with httpSetCookie.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
int httpRemoveHeader (HttpStream *stream, cchar *key)

Remove a header from the transmission.

Description:
Remove a header if present.
Parameters:
streamHttpStream stream object created via httpCreateStream
keyHttp response header key.
Returns:
"Zero" if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
HttpStream * * httpRequest (cchar *method, cchar *uri, cchar *data, int protocol, char **err)

Issue a http request.

Parameters:
methodHTTP method to use.
uriURI to request.
dataOptional data to send with request. Set to null for GET requests.
protocolHTTP protocol to use. Set to 1 for HTTP/1.1 and 2 for HTTP/2.
errOutput parameter to receive any error messages.
Returns:
HttpStream object. Use httpGetStatus to read status and httpReadString to read the response data.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpSetCharSet (HttpStream *stream, cchar *charSet)
void httpSetContentLength (HttpStream *stream, MprOff length)

Define a content length header in the transmission.

This will define a "Content-Length: NNN" request header and set Tx.length
Parameters:
streamHttpStream stream object created via httpCreateStream
lengthNumeric value for the content length header.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpSetContentType (HttpStream *stream, cchar *mimeType)
void httpSetCookie (HttpStream *stream, cchar *name, cchar *value, cchar *path, cchar *domain, MprTicks lifespan, int flags)

Set a transmission cookie.

Description:
Define a cookie to send in the transmission Http header.
Parameters:
streamHttpStream stream object created via httpCreateStream
nameCookie name.
valueCookie value.
pathURI path to which the cookie applies.
domainDomain in which the cookie applies. Must have 2-3 dots. If null, a domain is created using the current request host header. If set to the empty string, the domain field is omitted. If the domain is a numerical IP address or localhost, the domain will not be included as the browsers do not support this pattern consistently. Note that hostname port numbers are ignored by browsers and so web sites with the same domain name but different port numbers may have conflicting cookies. This is according to the Cookie RFC standard.
lifespanDuration for the cookie to persist in msec. Set to zero to create a session cookie that is meant to be automatically removed when the user exits their browser. However, beware, Chrome subverts this and will persist session cookies if "Continue where you left off" is enabled in Chrome preferences.
flagsCookie options mask. The following options are supported:
  • HTTP_COOKIE_SECURE - Set the 'Secure' attribute on the cookie.
  • HTTP_COOKIE_HTTP - Set the 'HttpOnly' attribute on the cookie.
  • HTTP_COOKIE_SAME_LAX - Set the 'SameSite=Lax' attribute on the cookie.
  • HTTP_COOKIE_SAME_STRICT - Set the 'SameSite=Strict' attribute on the cookie. See RFC 6265 for details about the 'Secure' and 'HttpOnly' cookie attributes.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
bool httpSetFilename (HttpStream *stream, cchar *filename, int flags)

Set the filename to serve for a request.

Description:
This routine defines a non-default response document filename. The filename may be virtual and not correspond to a physical file. It also may be a file outside the documents root directory. If it is not a file under the route documents directory, set the flags parameter to HTTP_TX_NO_CHECK. Otherwise, the filename will be checked to ensure it is inside the route documents directory.

Typically a handler will call httpMapFile to perform default request URI to filename mapping and should not need to call httpSetFilename unless a file outside the route documents directory is required to be served.

This routine will set the HttpTx filename, ext, etag and fileInfo fields.

Note: the response header mime type will be set based on the request URI. To override, use httpSetContentType
Parameters:
streamHttpStream stream object.
filenameTx filename to define. Set to NULL to reset the filename.
flagsFlags word. Or together the desired flags. Include to HTTP_TX_NO_CHECK to bypass checking if the filename resides inside the route documents directory.
Returns:
True if the filename exists and is readable.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpSetHeader (HttpStream *stream, cchar *key, cchar *fmt, ...)

Set a transmission header.

Description:
Set a Http header to send with the request. If the header already exists, it its value is overwritten.
Parameters:
streamHttpStream stream object created via httpCreateStream
keyHttp response header key.
fmtPrintf style formatted string to use as the header key value.
...Arguments for fmt.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void void void httpSetHeaderString (HttpStream *stream, cchar *key, cchar *value)

Set a simple key/value transmission header.

Description:
Set a Http header to send with the request. If the header already exists, it its value is overwritten.
Parameters:
streamHttpStream stream object created via httpCreateStream
keyHttp response header key.
valueString value for the key.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetResponded, httpSetStatus, httpWait, httpWriteUploadData
void httpSetResponded (HttpStream *stream)

Set the responded flag for the request.

Description:
This call sets the requests responded status. Once the HTTP response status code has been defined, HTTP response headers or any output has been generated, the request is regarded as having "responded" in-part to the client. This means that any errors cannot revise the HTTP response status and may need to prematurely abort the request to signify to the clien that the request has failed.
Parameters:
streamHttpStream stream object.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetStatus, httpWait, httpWriteUploadData
void httpSetRouteCharSet (HttpRoute *route, cchar *charSet)
void httpSetStatus (HttpStream *stream, int status)
int httpWait (HttpStream *stream, int state, MprTicks timeout)

Wait for the client connection to achieve the requested state.

Description:
This call blocks until the connection reaches the desired state. It creates a wait handler and services events while waiting. This is useful for blocking client requests, and should never be used on server-side connections.

It is often required to call mprStartDispatcher on the connection dispatcher after calling $httpCreateStream. This ensures that all foreground activity on the connection is serialized with respect to work done in response to I/O events while waiting in httpWait.

This routine may invoke mprYield before it sleeps to consent for the garbage collector to turn. Callers must ensure they have retained all required temporary memory before invoking this routine.
Parameters:
streamHttpStream stream object created via httpCreateStream
stateHTTP_STATE_XXX to wait for.
timeoutTimeout in milliseconds to wait. Set to -1 to use the default connection timeouts. Set to zero to wait forever.
Returns:
"Zero" if successful. Otherwise return a negative MPR error code. Specific returns include: MPR_ERR_TIMEOUT and MPR_ERR_BAD_STATE.
API Stability:
Stable.
See Also:
HttpRx, HttpStream, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWriteUploadData

HttpUploadFile

HttpUploadFile

Upload File.

Description:
Each uploaded file has an HttpUploadedFile entry. This is managed by the upload handler.
API Stability:
Stable.
API Stability:
Internal.
Fields:
cchar *clientFilename Client side name of the file.
cchar *contentType Content type.
cchar *filename Local (temp) name of the file.
cchar *name Form field name.
ssizesize Uploaded file size.

HttpUri

HttpUri

URI management.

Description:
The HTTP provides routines for formatting and parsing URIs. Routines are also provided to escape dangerous characters for URIs as well as HTML content and shell commands.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
API Stability:
Internal.
Fields:
cchar *ext Document extension.
cchar *host Host name.
cchar *path Uri path (without scheme, host, query or fragements).
intport Port number.
cchar *query Query string.
cchar *reference Reference fragment within the specified resource.
cchar *scheme URI scheme (http|https|...).
intsecure Using https.
intvalid Uri was successfully created.
intwebSockets Using WebSockets.
HttpUri * * httpCloneUri (HttpUri *base, int flags)

Clone a URI.

Description:
This call copies the base URI and optionally completes missing fields in the URI.
Parameters:
baseBase URI to copy.
flagsSet to HTTP_COMPLETE_URI to add missing components. ie. Add scheme, host and port if not supplied.
Returns:
A new URI object.
API Stability:
Stable.
See Also:
HttpStream, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
HttpUri * * httpCompleteUri (HttpUri *uri, HttpUri *other)

Complete the given URI.

Description:
Complete the URI supplying missing URI components from the other URI. This modifies the supplied URI and does not allocate or create a new URI.
Parameters:
uriURI to complete.
otherOther URI to supply the missing components.
Returns:
The supplied URI.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
HttpUri * * httpCreateUri (cchar *uri, int flags)

Create and initialize a URI.

Description:
Parse a uri and return a tokenized HttpUri structure.
Parameters:
uriUri string to parse.
flagsSet to HTTP_COMPLETE_URI to add missing components. ie. Add scheme, host and port if not supplied.
Returns:
A newly allocated HttpUri structure.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
HttpUri * * httpCreateUriFromParts (cchar *scheme, cchar *host, int port, cchar *path, cchar *reference, cchar *query, int flags)

Create a URI from parts.

Description:
This call constructs a URI from the given parts. Various URI parts can be omitted by setting to null. The URI path is the only mandatory parameter.
Parameters:
schemeThe URI scheme. This is typically "http" or "https".
hostThe URI host name portion. This can be a textual host and domain name or it can be an IP address.
portThe URI port number. Set to zero to accept the default value for the selected scheme.
pathThe URI path to the requested document.
referenceURI reference with an HTML document. This is the URI component after the "#" in the URI path.
queryURI query component. This is the URI component after the "?" in the URI.
flagsSet to HTTP_COMPLETE_URI to add missing components. ie. Add scheme, host and port if not supplied.
Returns:
A new URI.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
char * * httpFormatUri (cchar *scheme, cchar *host, int port, cchar *path, cchar *ref, cchar *query, int flags)

Format a URI.

Description:
Format a URI string using the input components.
Parameters:
schemeProtocol string for the uri. Example: "http".
hostHost or IP address.
portTCP/IP port number.
pathURL path.
refURL reference fragment.
queryAdditiona query parameters.
flagsSet to HTTP_COMPLETE_URI to add missing components. ie. Add scheme, host and port if not supplied.
Returns:
A newly allocated uri string.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
HttpUri * * httpGetRelativeUri (HttpUri *base, HttpUri *target, int clone)

Get a relative URI from the base to the target.

Description:
This creates a URI relative from the base to the target. This may contain ".." segments. This API is designed to create relative URIs for use in a browser web page.

If the target is null, an absolute URI, or if a relative URI from the base cannot be constructed, then the target will be returned. If clone is true, then a clone of the target will be returned.
Parameters:
baseThe base URI considered to be the current URI. Think of this as the current directory.
targetThe destination URI for which a relative URI will be crafted to reach.
cloneIf true, the target URI will be cloned if the target is an absolute URI or if a relative URI cannot be constructed.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
HttpUri * * httpJoinUri (HttpUri *base, int argc, HttpUri **others)

Join URIs.

Parameters:
baseBase URI to being with.
argcCount of URIs in others.
othersArray of URIs to join to the base.
Returns:
The resulting, joined URI.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
HttpUri * * httpJoinUriPath (HttpUri *result, HttpUri *base, HttpUri *other)

Join a URI path.

Parameters:
resultURI that will be modified with a joined path.
baseURI supplying the base path.
otherOther URI whose path is joined to the base.
Returns:
The result URI.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
char * * httpLink (struct HttpStream *stream, cchar *target)

Create a URI link.

Description:
Create a URI link based on a given target relative to the current request. This API expands embedded tokens based on the current request and route state. The target URI parameter may contain partial or complete URI information. The missing parts are supplied using the current request and route tables.
Parameters:
streamHttpStream stream object.
targetThe URI target. The target parameter can be a URI string or JSON style set of options. The target will have any embedded "{tokens}" expanded by using token values from the request parameters. If the target has an absolute URI path, that path is used directly after tokenization. If the target begins with "~", that character will be replaced with the route prefix. This is a very convenient way to create application top-level relative links.

If the target is a string that begins with "{AT}" it will be interpreted as a service/action pair of the form "{AT}Service/action". If the "service/" portion is absent, the current service is used. If the action component is missing, the "list" action is used. A bare "{AT}" refers to the "list" action of the current service.

If the target starts with "{" it is interpreted as being a JSON style set of options that describe the link. If the target is a relative URI path, it is appended to the current request URI path.

If the is a JSON style of options, it can specify the URI components: scheme, host, port, path, reference and query. If these component properties are supplied, these will be combined to create a URI.

If the target specifies either a service/action or a JSON set of options, The URI will be created according to the route URI template. The template may be explicitly specified via a "route" target property. Otherwise, if an "action" property is specified, the route of the same name will be used. If these don't result in a usable route, the "default" route will be used.

These are the properties supported in a JSON style "{ ... }" target:
  • scheme String URI scheme portion
  • host String URI host portion
  • port Number URI port number
  • path String URI path portion
  • reference String URI path reference. Does not include "#"
  • query String URI query parameters. Does not include "?"
  • service String Service name if using a Service-based route. This can also be specified via the action option.
  • action String Action to invoke. This can be a URI string or a Service action of the form {AT}Service/action.
  • route String Route name to use for the URI template
Returns:
A normalized Uri string.
Remarks:
Examples:
httpLink(stream, "http://example.com/index.html");
httpLink(stream, "/path/to/index.html");
httpLink(stream, "../images/splash.png");
httpLink(stream, "~/static/images/splash.png");
httpLink(stream, "${app}/static/images/splash.png");
httpLink(stream, "@service/checkout");
httpLink(stream, "@service/")               //  Service = Service, action = index
httpLink(stream, "@init")                   //  Current service, action = init
httpLink(stream, "@")                       //  Current service, action = index
httpLink(stream, "{ action: '@post/create' }");
httpLink(stream, "{ action: 'checkout' }");
httpLink(stream, "{ action: 'logout', service: 'admin' }");
httpLink(stream, "{ action: 'admin/logout'");
httpLink(stream, "{ product: 'candy', quantity: '10', template: '/cart/${product}/${quantity}' }");
httpLink(stream, "{ route: '~/STAR/edit', action: 'checkout', id: '99' }");
httpLink(stream, "{ template: '~/static/images/${theme}/background.jpg', theme: 'blue' }");
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
char * * httpLinkAbs (struct HttpStream *stream, cchar *target)

Create an absolute link that includes scheme and host.

Parameters:
streamHttpStream stream object.
targetThe URI target. See httpLink for details of the target parameter.
Returns:
A normalized Uri string.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
char * * httpLinkEx (struct HttpStream *stream, cchar *target, MprHash *options)

Extended URI link creation.

Description:
Extended httpLink with custom options. This routine extends the httpLink API with an options hash of token values.
Parameters:
streamHttpStream stream object.
targetThe URI target. See httpLink for details.
optionsHash of option values for embedded tokens. This hash is blended with the route variables.
Returns:
A normalized Uri string.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
cchar * * httpLookupMimeType (cchar *ext)

Get the mime type for an extension.

This call will return the mime type from a limited internal set of mime types for the given path or extension
Parameters:
extPath or extension to examine.
Returns:
Mime type. This is a static string.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
HttpUri * * httpMakeUriLocal (HttpUri *uri)

Make a URI local.

Description:
This routine removes the scheme, host and port portions of a URI.
Parameters:
uriURI to modify.
Returns:
The given URI.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpNormalizeUriPath, httpResolveUri, httpUriToString
HttpUri * * httpNormalizeUri (HttpUri *uri)

Normalize a URI.

Description:
Validate and canonicalize a URI. This invokes httpNormalizeUriPath to normalize the URI path. This removes redundant ./ and ../ segments including leading ../ segments. It does not make the URI absolute.
Parameters:
uriURI object to normalize.
Returns:
The supplied uri so it can be used in chaining. Returns null if the URI cannot be normalized.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
char * * httpNormalizeUriPath (cchar *uri)

Normalize a URI.

Description:
Validate and canonicalize a URI path. This removes redundant "./" and "../dir" sequences including leading "../" segments.
Parameters:
uriUri path string to normalize. This is the URI path portion without scheme, host and port components.
Returns:
A new validated uri string. Returns null if the URI cannot be normalized.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpResolveUri, httpUriToString
HttpUri * * httpResolveUri (struct HttpStream *stream, HttpUri *base, HttpUri *target)

Resolve URIs relative to a base.

Parameters:
streamHttpStream stream object.
baseBase URI to begin with.
targetURI to resolve relative to the base.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpUriToString
char * * httpUriToString (HttpUri *uri, int flags)

Convert a Uri to a string.

Description:
Convert the given Uri to a string, optionally completing missing parts such as the host, port and path.
Parameters:
uriA Uri object created via httpCreateUri.
flagsSet to HTTP_COMPLETE_URI to add missing components. ie. Add scheme, host and port if not supplied.
Returns:
A newly allocated uri string.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri
char * * httpValidateUriPath (cchar *uri)

Validate a URI path as expected in a HTTP request line.

Description:
This expects a URI beginning with "/" and containing only valid URI characters. The URI is decoded, and normalized removing "../" and "." segments. The URI must begin with a "/" both before and after decoding and normalization.
Parameters:
uriURI to validate.
Returns:
A validated, normalized URI path.
API Stability:
Stable.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString
bool httpValidUriChars (cchar *uri)

Test if a URI is using only valid characters Note this does not test if the URI is fully legal.

Some components of the URI have restricted character sets that this routine does not test. This tests if the URI has only characters valid to use in a URI before decoding. i.e. It will permit NN encodings. The set of valid characters is: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%"
Parameters:
uriUri to test.
Returns:
True if the URI string is comprised of legal URI characters.
See Also:
HttpStream, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString

HttpWebSocket

HttpWebSocket

WebSocket Service to implement the WebSockets RFC 6455 specification for client and server communications.

Description:
WebSockets is a technology providing interactive communication between a server and client. Normal HTML connections follow a request / response paradigm and do not easily support asynchronous communications or unsolicited data pushed from the server to the client. WebSockets solves this by supporting bi-directional, full-duplex communications over persistent connections. A WebSocket connection is established over a standard HTTP connection and is then upgraded without impacting the original connection. This means it will work with existing networking infrastructure including firewalls and proxies.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
API Stability:
Internal.
Fields:
cchar *closeReason Reason for closure.
intcloseStatus Close status provided by peer.
intclosing Started closing sequnce.
HttpPacket *currentFrame Message frame being currently read.
HttpPacket *currentMessage Current incoming messsage so far.
intcurrentMessageType Current incoming messsage type.
void *data Custom data for applications (marked).
uchardataMask[4] Mask for data.
cchar *errorMsg Error message for last I/O.
ssizeframeLength Length of the current frame.
intframeState Message frame state.
intmaskOffset Offset in dataMask.
ssizemessageLength Length of the current message.
intmore More data to send in a message.
intpartialUTF Last frame had a partial UTF codepoint.
MprEvent *pingEvent Ping timer event.
intpreserveFrames Do not join frames.
intrxSeq Incoming packet number.
intstate State.
char *subProtocol Application level sub-protocol.
HttpPacket *tailMessage Subsequent message frames.
inttxSeq Outgoing packet number.
cchar * * httpGetWebSocketCloseReason (HttpStream *stream)

Get the close reason supplied by the peer.

Description:
The peer may supply a UTF8 messages reason for the closure.
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
The UTF8 reason string supplied by the peer when closing the WebSocket.
API Stability:
Stable.
See Also:
httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
void * * httpGetWebSocketData (HttpStream *stream)

Get the WebSocket private data.

Description:
Get the private data defined with httpSetWebSocketData
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
The private data reference.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
ssize httpGetWebSocketMessageLength (HttpStream *stream)

Get the message length for the current message.

Description:
The message length will be updated as the message frames are received. The message length is only complete when the last frame has been received. See httpIsLastPacket
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
The size of the message.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
char * * httpGetWebSocketProtocol (HttpStream *stream)

Get the selected WebSocket protocol selected by the server.

Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
The WebSocket protocol string.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
ssize httpGetWebSocketState (HttpStream *stream)

Get the WebSocket state.

Returns:
The WebSocket state. Will be WS_STATE_CONNECTING, WS_STATE_OPEN, WS_STATE_CLOSING or WS_STATE_CLOSED.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
ssize httpSend (HttpStream *stream, cchar *fmt, ...)

Send a UTF-8 text message to the WebSocket peer.

Description:
This call invokes httpSend with a type of WS_MSG_TEXT and flags of HTTP_BUFFER. The message must be valid UTF8 as the peer will reject invalid UTF8 messages.
Parameters:
streamHttpStream stream object created via httpCreateStream
fmtPrintf style formatted string.
...Arguments for the format.
Returns:
Number of bytes written.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
ssize httpSendBlock (HttpStream *stream, int type, cchar *msg, ssize len, int flags)

Send a message of a given type to the WebSocket peer.

Description:
This is the lower-level message send routine. It permits control of message types and message framing.

This routine can operate in a blocking, non-blocking or buffered mode. Blocking mode is specified via the HTTP_BLOCK flag. When blocking, the call will wait until it has written all the data. The call will either accept and write all the data or it will fail, it will never return "short" with a partial write. If in blocking mode, the call may block for up to the inactivity timeout specified in the stream->limits->inactivityTimeout value.

Non-blocking mode is specified via the HTTP_NON_BLOCK flag. In this mode, the call will consume that amount of data that will fit within the outgoing WebSocket queues. Consequently, it may return "short" with a partial write. If this occurs the next call to httpSendBlock should set the message type to WS_MSG_CONT to indicate a continued message. This is required by the WebSockets specification.

Buffered mode is the default and may be explicitly specified via the HTTP_BUFFER flag. In buffered mode, the entire message will be accepted and will be buffered if required.

This API may split the message into frames such that no frame is larger than the limit stream->limits->webSocketsFrameSize. However, if the HTTP_MORE flag is specified to indicate there is more data to complete this entire message, the data provided to this call will not be split into frames and will not be aggregated with previous or subsequent messages. i.e. frame boundaries will be presserved and sent as-is to the peer.

In blocking mode, this routine may invoke mprYield before blocking to consent for the garbage collector to run. Callers must ensure they have retained all required temporary memory before invoking this routine.
Parameters:
streamHttpStream stream object created via httpCreateStream
typeWeb socket message type. Choose from WS_MSG_TEXT, WS_MSG_BINARY or WS_MSG_PING. Use httpSendClose to send a close message. Do not send a WS_MSG_PONG message as it is generated internally by the Web Sockets module. If using HTTP_NON_BLOCK and the call returns having written only a portion of the data, you must set the type to WS_MSG_CONT for the.
msgMessage data buffer to send.
lenLength of msg.
flagsInclude the flag HTTP_BLOCK for blocking operation or HTTP_NON_BLOCK for non-blocking. Set to HTTP_BUFFER to buffer the data if required and never block. Set to zero will default to HTTP_BUFFER. Include the flag HTTP_MORE to indicate there is more data to come to complete this message. This will set frame continuation bit. Setting HTTP_MORE preserve the frame boundaries. i.e. it will ensure the data written is not split into frames or aggregated with other data.
Returns:
Number of data message bytes written. Should equal len if successful, otherwise returns a negative MPR error code.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
ssize httpSendClose (HttpStream *stream, int status, cchar *reason)

Send a close message to the WebSocket peer.

Description:
This call invokes httpSendBlock with a type of WS_MSG_CLOSE and flags of HTTP_BUFFER. The status and reason are encoded in the message. The reason is an optional UTF8 closure reason message.
Parameters:
streamHttpStream stream object created via httpCreateStream
statusWeb socket status.
reasonOptional UTF8 reason text message. The reason must be less than 124 bytes in length.
Returns:
Number of data message bytes written. Should equal len if successful, otherwise returns a negative MPR error code.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
void httpSetWebSocketData (HttpStream *stream, void *data)

Set the WebSocket private data.

Description:
Set private data to be retained by the garbage collector.
Parameters:
streamHttpStream stream object created via httpCreateStream
dataManaged data reference.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
void httpSetWebSocketPreserveFrames (HttpStream *stream, bool on)

Preserve frames for incoming messages.

Description:
This routine enables user control of message framing. When preserving frames, sent message boundaries will be preserved and will not be split into frames or aggregated with other message frames. Received messages will similarly have their frame boundaries preserved and will be stored one frame per HttpPacket. Note: enabling this option may prevent full validation of UTF8 text messages if UTF8 codepoints span frame boundaries.
Parameters:
streamHttpStream stream object created via httpCreateStream
onSet to true to preserve frames.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
void httpSetWebSocketProtocols (HttpStream *stream, cchar *protocols)

Set a list of application-level protocols supported by the client.

Parameters:
streamHttpStream stream object created via httpCreateStream
protocolsComma separated list of application-level protocols.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpWebSocketOrderlyClosed
int httpUpgradeWebSocket (HttpStream *stream)

Upgrade a client HTTP connection connection to use WebSockets.

Description:
This requests an upgrade to use WebSockets. Note this is the upgrade request and the confirmation handshake response must still be received and validated. The connection must be upgraded before sending any data to the server.
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
Return Zero if the connection upgrade can be requested.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed
bool httpWebSocketOrderlyClosed (HttpStream *stream)

Test if WebSocket connection was orderly closed by sending an acknowledged close message.

Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
True if the WebSocket was orderly closed.
API Stability:
Stable.
See Also:
httpGetWebSocketCloseReason, httpGetWebSocketData, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWebSocketState, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketData, httpSetWebSocketPreserveFrames, httpSetWebSocketProtocols

Functions

bool httpAuthenticate (HttpStream *stream)

Authenticate a user based on session data.

Description:
This authenticates a user by testing the user supplied session cookie against login credentials stored in the server-side session store. The httpAuthenticate call is not automatically performed by the request pipeline. Web Frameworks should call this if required.
Parameters:
streamHttpStream stream object created via httpCreateStream object.
Returns:
True if the user is authenticated.
void httpDefineAction (cchar *uri, HttpAction fun)

Define a function procedure to invoke when the specified URI is requested.

Description:
This creates the role with given abilities. Ability words can also be other roles.
Parameters:
uriURI to bind with. When this URI is requested, the callback will be invoked if the procHandler is configured for the request route.
funCallback function procedure.
API Stability:
Stable.
cchar * * httpGetBodyInput (HttpStream *stream)

Get the receive body input.

Description:
This will return all the body input. The request must have received all input (rx->eof == 1) and must not be streaming (rx->streaming).
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
A string containing the body input.
API Stability:
Stable.
void * * httpGetQueueData (HttpStream *stream)

Get the queue data for the connection.

Description:
The queue data is stored on the stream->writeq.
Parameters:
streamHttpStream stream object created via httpCreateStream
Returns:
The private queue data object.
void httpHideRoute (HttpRoute *route, bool on)

Hide the route from route tables.

The route is still active, just not displayed in route tables. This is used to hide parent routes that are used just for inheritance for child routes
Parameters:
routeRoute to hide.
onSet to true to hide the route.
API Stability:
Stable.
void httpOmitBody (HttpStream *stream)

Tell the tx to omit sending any body.

Parameters:
streamHttpStream stream object created via httpCreateStream
bool httpPumpOutput (HttpQueue *q)

Get more output by invoking the handler's writable callback.

Called by processRunning. Also issues an HTTP_EVENT_WRITABLE for application level notification
Description:
Get more output by invoking the handler's writable callback. Called by processRunning. Also issues an HTTP_EVENT_WRITABLE for application level notification.
Parameters:
qHttpQueue input queue object.
API Stability:
Internal.
void httpSetHandler (HttpStream *stream, HttpStage *handler)

Set the handler for this request Use this request from the Handler rewrite callback to change the selected handler to process a request.

Most useful to set the Tx.filename and pass to the fileHandler
Parameters:
streamHttpStream stream object created via httpCreateStream
handlerHandler to set.
API Stability:
Stable.
void httpSetStreamData (HttpStream *stream, void *data)

Set the connection data field.

Description:
The HttpStream.data field is a managed reference that applications can use to retain their own per connection state. It will be marked for GC retention by Http. See also HttpStream.reqData and HttpQueue.stageData;.
Parameters:
streamHttpStream object created via httpCreateStream
dataData object to associate with the connection. Must be a managed memory reference.
API Stability:
Stable.

Typedefs

typedef int() HttpRouteProc(HttpStream *stream, HttpRoute *route, HttpRouteOp *item).

General route procedure.

Used by targets, conditions and updates
Returns:
Zero for success. Otherwise a negative MPR error code.
typedef void(* HttpConfigureProc) (void *arg).

Callback procedure for HttpConfigure.

Parameters:
argUser definable data. May be managed or unmanaged.
API Stability:
Stable.
See Also:
Http, HttpEndpoint, HttpStream, httpConfigure, httpCreate, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware
typedef void(* HttpAskLogin) (HttpStream *stream).
typedef int(* HttpParseAuth) (HttpStream *stream, cchar **username, cchar **password).

AuthType callback to parse the HTTP 'Authorize' (client) and 'www-authenticate' (server) headers.

Description:
This callback must extract the username and password. The username is set on HttpStream.username. The password is returned by this call.
Parameters:
streamHttpStream stream object.
Returns:
The password if successful, otherwise NULL.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
typedef bool(* HttpSetAuth) (HttpStream *stream, cchar *username, cchar *password).
typedef bool(* HttpVerifyUser) (HttpStream *stream, cchar *username, cchar *password).

AuthStore callback Verify the user credentials.

Parameters:
streamHttpStream stream object.
usernameUsers login name.
passwordActual user password.
Returns:
True if the user credentials can validate.
API Stability:
Stable.
See Also:
HttpAskLogin, HttpAuth, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthLogin, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType, httpSetAuthUsername
typedef void(* HttpRemedyProc) (MprHash *args).

Defense remedy callback.

Parameters:
argsHash of configuration args for the callback.
API Stability:
Stable.
typedef void(* HttpIOCallback) (struct HttpNet *net, MprEvent *event).

I/O callback for network connections.

Parameters:
netHttpNet object created via httpCreateNet
eventEvent object describing the I/O event.
API Stability:
Stable.
See Also:
HttpNet, httpConnectNet, httpCreateNet, httpDestroyNet, httpEnableNetEvents, httpGetAsync, httpGetProtocol, httpIOEvent, httpNetError, httpNetTimeout, httpServiceNetQueues, httpSetAsync, httpSetIOCallback, httpSetNetContext
typedef void(* HttpNetCallback) (struct HttpNet *net, int event).
typedef ssize(* HttpFillProc) (struct HttpQueue *q, struct HttpPacket *packet, MprOff pos, ssize size).

Callback procedure to fill a packet with data.

Parameters:
qQueue owning the packet.
packetThe packet to fill.
posOffset in the packet to fill with data.
sizeSize of packet from the offset to fill.
Returns:
The number of bytes copied into the packet.
API Stability:
Stable.
See Also:
HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpClonePacket, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket
typedef void(* HttpParseCallback) (struct HttpRoute *route, cchar *key, MprJson *child).
typedef void(* HttpRouteSetProc) (HttpRoute *route, cchar *name).
typedef void(* HttpRequestCallback) (struct HttpStream *stream).
typedef void(* HttpEnvCallback) (struct HttpStream *stream).
typedef void(* HttpEventProc) (struct HttpStream *stream, void *data).
typedef int(* HttpHeadersCallback) (void *arg).
typedef int(* HttpListenCallback) (struct HttpEndpoint *endpoint).
typedef void(* HttpNotifier) (struct HttpStream *stream, int event, int arg).

HttpStream state change notification callback.

Description:
The notifier callback is invoked for state changes and I/O events. A user notifier function can respond to these events with any desired custom code. There are four valid event types:
  • HTTP_EVENT_STATE. The stream object has changed state. See stream->state.
  • HTTP_EVENT_READABLE. The input queue has I/O to read. See stream->readq. Use httpRead to read the data. For WebSockets, use httpGetPacket.
  • HTTP_EVENT_WRITABLE. The output queue is now writable.
  • HTTP_EVENT_ERROR. The stream has an error.
  • HTTP_EVENT_DESTROY. The stream is being destroyed. NOTE: this is not the network / socket.
Parameters:
streamHttpStream stream object created via httpCreateStream
eventHttp state.
argPer-event information.
API Stability:
Stable.
See Also:
HttpEnvCallback, HttpListenCallback, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpStream, HttpTx, httpClosePipeline, httpCreateRxPipeline, httpCreateStream, httpCreateTxPipeline, httpDestroyStream, httpDiscardData, httpEnableUpload, httpError, httpFinalizeConnector, httpGetChunkSize, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetStreamContext, httpGetStreamHost, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpSetChunkSize, httpSetCredentials, httpSetFileHandler, httpSetKeepAliveCount, httpSetNetProtocol, httpSetState, httpSetStreamContext, httpSetStreamHost, httpSetStreamNotifier, httpSetTimeout, httpSetTimestamp, httpStartPipeline, httpStreamTimeout
typedef cchar *(* HttpRedirectCallback) (struct HttpStream *stream, int *code, cchar *uri).
typedef void(* HttpTimeoutCallback) (struct HttpStream *stream).
typedef void(* HttpTraceFormatter) (struct HttpTrace *trace, cchar *event, cchar *type, int flags, cchar *data, ssize len, cchar *fmt, va_list args).

Trace formatter callback.

Parameters:
traceTrace object.
eventEvent to trace.
typeType of event to trace.
flagsFormatter flags.
dataData buffer.
fmtTrace string to format.
argsFormat args.
API Stability:
Stable.
typedef void(* HttpTraceLogger) (struct HttpTrace *trace, cchar *data, ssize len).

Trace logger callback.

Parameters:
traceTrace object.
dataData buffer to write.
lenLength of data. May be zero.
API Stability:
Stable.
HttpAddress

Per-IP address structure that holds the monitor counters.

API Stability:
Internal.
Fields:
cchar *banMsg Ban response message.
intbanStatus Ban response status.
MprTicksbanUntil Ban IP address until this time.
HttpCountercounters[1] Counters allocated here.
intdelay Delay per request.
MprTicksdelayUntil Delay (go-slow) servicing requests until this time
intncounters Number of counters in ncounters.
intseqno Unique client sequence number.
MprTicksupdated When the address counters were last updated.
HttpAuthStore

Password backend store.

API Stability:
Stable.
Fields:
char *name Authentication password store name: 'system', 'file'.
intnoSession Do not create a session after login.
HttpVerifyUserverifyUser Default user verification routine.
See Also:
HttpAskLogin, HttpParseAuth, HttpVerifyUser, httpCreateAuthStore, httpGetAuthStore, httpSetAuthStore, httpSetAuthStoreSessions, httpSetAuthStoreVerify, httpSetAuthStoreVerifyByName
HttpAuthType

Authentication Protocol.

API Stability:
Internal.
Fields:
HttpAskLoginaskLogin Callback to generate a client login response.
char *name Authentication protocol name: 'basic', 'digest', 'form'.
HttpParseAuthparseAuth Callback to parse request auth details.
HttpSetAuthsetAuth Callback to set the HTTP response authentication headers.
HttpCounter

Monitoring counter.

API Stability:
Internal.
Fields:
uint64value Current counter value.
HttpDefense

Monitor defense configuration.

API Stability:
Stable.
Fields:
MprHash *args Remedy arguments.
cchar *name Defense name.
cchar *remedy Remedy name to invoke.
MprHash *suppress Active defenses to suppress.
intsuppressed Number of remedies suppressed.
MprTickssuppressPeriod Period to suppress defense.
HttpHeaderTable

HTTP HPACK header table.

Fields:
MprList *list Header list.
HttpLang

Language definition record for routes.

API Stability:
Internal.
Fields:
intflags Control suffix position.
char *path Document directory for the language.
char *suffix Suffix to add to filenames.
HttpRole

Authorization Roles.

See Also:
HttpAuth
Fields:
MprHash *abilities Role's abilities.
char *name Role name.
API Stability:
Internal.
HttpRouteOp

Route operation record.

API Stability:
Internal.
Fields:
char *details General route operation details.
intflags Route flags to control freeing mdata.
void *mdata pcre_ data (unmanaged).
char *name Name of route operation.
char *value Value to assign to var.
char *var Var to set.
HttpUser

User Authorization.

See Also:
HttpAuth
Fields:
MprHash *abilities User abilities defined by roles.
void *data Unmanaged custom data.
char *name User name.
char *password User password for "internal" auth store - (actually the password hash.
MprHash *roles List of roles.
API Stability:
Internal.

© Embedthis Software. All rights reserved.