Embedthis Appweb 4.0.0
Home > Programmers Reference > Native APIs > HTTP

# See Also

## Quick Nav

- Components
- Typedefs
- Functions
- Defines

# HTTP - Http API Native API

# Components

Http | Http service object.
HttpAuth | Authorization.
HttpCache | Cache Control.
HttpConn | Http Connections.
HttpEndpoint | Listening endpoints.
HttpHost | Host Object.
HttpLimits | Http limits.
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.
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

HttpConn* | httpAcceptConn(HttpEndpoint *endpoint, MprEvent *event)
| Accept a new connection.
int | httpAddAuthStore(Http *http, cchar *name, HttpVerifyUser verifyUser)
| Add an authorization store for password validation.
int | httpAddAuthType(Http *http, cchar *name, HttpAskLogin askLogin, HttpParseAuth parse, HttpSetAuth setAuth)
| Add an authorization type.
void | httpAddCache(struct HttpRoute *route, cchar *methods, cchar *uris, cchar *extensions, cchar *types, MprTicks clientLifespan, MprTicks serverLifespan, int flags)
| Add caching for response content.
void | httpAddHeader(HttpConn *conn, cchar *key, cchar *fmt, ...)
| Add a header to the transmission using a format string.
void | httpAddHeaderString(HttpConn *conn, cchar *key, cchar *value)
| Add a header to the transmission.
void | httpAddHomeRoute(HttpRoute *parent)
| Add a route for the home page.
void | httpAddHostToEndpoint(HttpEndpoint *endpoint, struct HttpHost *host)
| Add a host to an endpoint.
void | httpAddOption(MprHash *options, cchar *field, cchar *value)
| Add an option to the options table.
void | httpAddParams(HttpConn *conn)
| Add query and form body data to params.
void | httpAddResource(HttpRoute *parent, cchar *resource)
| Add routes for a resource.
void | httpAddResourceGroup(HttpRoute *parent, cchar *resource)
| Add routes for a group of resources.
int | httpAddRole(HttpAuth *auth, cchar *role, cchar *abilities)
| Add a role.
int | httpAddRoute(HttpHost *host, HttpRoute *route)
| Add a route to a host.
int | httpAddRouteCondition(HttpRoute *route, cchar *name, cchar *details, int flags)
| Add a route condition.
void | httpAddRouteErrorDocument(HttpRoute *route, int status, cchar *uri)
| Add an error document.
int | httpAddRouteFilter(HttpRoute *route, cchar *name, cchar *extensions, int direction)
| Add a route filter.
int | httpAddRouteHandler(HttpRoute *route, cchar *name, cchar *extensions)
| Add a route handler.
void | httpAddRouteHeader(HttpRoute *route, cchar *header, cchar *value, int flags)
| Add a route header check.
void | httpAddRouteIndex(HttpRoute *route, cchar *path)
| Set the route index document.
int | httpAddRouteLanguageDir(HttpRoute *route, cchar *language, cchar *path)
| Add a route language directory.
int | httpAddRouteLanguageSuffix(HttpRoute *route, cchar *language, cchar *suffix, int flags)
| Add a route language suffix.
void | httpAddRouteParam(HttpRoute *route, cchar *field, cchar *value, int flags)
| Add a route param check.
void | httpAddRouteSet(HttpRoute *parent, cchar *set)
| Add a route set package.
int | httpAddRouteUpdate(HttpRoute *route, cchar *name, cchar *details, int flags)
| Add a route update rule.
void | httpAddStaticRoute(HttpRoute *parent)
| Add a route for static content under a "static" directory.
void | httpAddUploadFile(HttpConn *conn, cchar *id, HttpUploadFile *file)
| Add an Uploaded file.
int | httpAddUser(HttpAuth *auth, cchar *user, cchar *password, cchar *abilities)
| Add a user.
void | httpAdjustPacketEnd(HttpPacket *packet, MprOff size)
| Adjust the packet end position.
void | httpAdjustPacketStart(HttpPacket *packet, MprOff size)
| Adjust the packet starting position.
void | httpAfterEvent(HttpConn *conn)
| Do setup after an I/O event to receive future events.
HttpSession* | httpAllocSession(HttpConn *conn, cchar *id, MprTicks lifespan)
| Allocate a new session state object.
void | httpAppendHeader(HttpConn *conn, cchar *key, cchar *fmt, ...)
| Append a transmission header.
void | httpAppendHeaderString(HttpConn *conn, cchar *key, cchar *value)
| Append a transmission header string.
void | httpBackupRouteLog(HttpRoute *route)
| Backup the route log if required.
void | httpCallEvent(HttpConn *conn, int mask)
| Call httpEvent with the given event mask.
bool | httpCanUser(HttpConn *conn)
| Test if a user has the required abilities.
void | httpClearRouteStages(HttpRoute *route, int direction)
| Clear the pipeline stages for the route.
HttpHost* | httpCloneHost(HttpHost *parent)
| Clone a host.
HttpPacket* | httpClonePacket(HttpPacket *orig)
| Clone a packet.
HttpStage* | httpCloneStage(Http *http, HttpStage *stage)
| Create a clone of an existing state.
HttpUri* | httpCloneUri(HttpUri *base, int flags)
| Clone a URI.
void | httpCloseConn(HttpConn *conn)
| Close a connection.
HttpUri* | httpCompleteUri(HttpUri *uri, HttpUri *other)
| Complete the given URI.
void | httpComputeAllUserAbilities(HttpAuth *auth)
| Compute all the user abilities for a route using the given auth.
void | httpComputeUserAbilities(HttpAuth *auth, HttpUser *user)
| Compute the user abilities for a given user in a route using the given auth.
int | httpConfigureNamedVirtualEndpoints(Http *http, cchar *ip, int port)
| Configure endpoints with named virtual hosts.
void | httpConnTimeout(HttpConn *conn)
| Signal a connection timeout on a connection.
int | httpConnect(HttpConn *conn, cchar *method, cchar *uri, struct MprSsl *ssl)
| Connect to a server and issue Http client request.
bool | httpContentNotModified(HttpConn *conn)
| 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()
| Create an authentication object.
void | httpCreateCGIParams(HttpConn *conn)
| Create CGI parameters.
HttpEndpoint* | httpCreateConfiguredEndpoint(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.
HttpConn* | httpCreateConn(Http *http, struct HttpEndpoint *endpoint, MprDispatcher *dispatcher)
| Create a connection object.
HttpStage* | httpCreateConnector(Http *http, cchar *name, MprModule *module)
| Create a connector stage.
HttpPacket* | httpCreateDataPacket(ssize size)
| Create a data packet.
HttpRoute* | httpCreateDefaultRoute(struct HttpHost *host)
| Create a default route for a host.
HttpPacket* | httpCreateEndPacket()
| 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.
HttpStage* | httpCreateFilter(Http *http, cchar *name, MprModule *module)
| Create a filter stage.
HttpStage* | httpCreateHandler(Http *http, cchar *name, MprModule *module)
| Create a request handler stage.
HttpPacket* | httpCreateHeaderPacket()
| Create a response header packet.
HttpHost* | httpCreateHost()
| Create a host.
HttpRoute* | httpCreateInheritedRoute(HttpRoute *route)
| Create a route inherited from a parent route.
HttpLimits* | httpCreateLimits(int serverSide)
| Create a new limits object.
HttpPacket* | httpCreatePacket(ssize size)
| Create a data packet.
HttpRole* | httpCreateRole(HttpAuth *auth, cchar *name, cchar *abilities)
| Create a new role.
HttpRoute* | httpCreateRoute(struct HttpHost *host)
| Create a route for a host.
void | httpCreateRxPipeline(HttpConn *conn, struct HttpRoute *route)
| Create the receive request pipeline.
int | httpCreateSecret(Http *http)
| Create the Http secret data for crypto.
HttpSession* | httpCreateSession(HttpConn *conn)
| Create a session object.
HttpStage* | httpCreateStage(Http *http, cchar *name, int flags, MprModule *module)
| Create a connector stage.
HttpTx* | httpCreateTx(HttpConn *conn, MprHash *headers)
| Create the tx object.
void | httpCreateTxPipeline(HttpConn *conn, 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.
HttpUser* | httpCreateUser(HttpAuth *auth, cchar *name, cchar *password, cchar *abilities)
| Create a new user.
void | httpDefaultOutgoingServiceStage(HttpQueue *q)
| Default outgoing data handling.
void | httpDefineAction(cchar *uri, HttpAction fun)
| Define a function procedure to invoke when the specified URI is requested.
HttpRoute* | httpDefineRoute(HttpRoute *parent, cchar *name, cchar *methods, cchar *pattern, cchar *target, cchar *source)
| Define a route.
void | httpDefineRouteCondition(cchar *name, HttpRouteProc *proc)
| Define a route condition rule.
void | httpDefineRouteTarget(cchar *name, HttpRouteProc *proc)
| Define a route target rule.
void | httpDefineRouteUpdate(cchar *name, HttpRouteProc *proc)
| Define a route update rule.
void | httpDestroy(Http *http)
| Destroy the Http service object.
void | httpDestroyConn(HttpConn *conn)
| Destroy the connection object.
void | httpDestroyEndpoint(HttpEndpoint *endpoint)
| Destroy the endpoint.
void | httpDestroyPipeline(HttpConn *conn)
| Destroy the request pipeline.
void | httpDestroySession(HttpConn *conn)
| Destroy a session state object.
void | httpDestroyTx(HttpTx *tx)
| Destroy the tx object.
void | httpDisableQueue(HttpQueue *q)
| Disable a queue.
void | httpDiscardData(HttpConn *conn, int dir)
| Discard buffered transmit pipeline data.
void | httpDiscardQueueData(HttpQueue *q, bool removePackets)
| Discard all data from the queue.
void | httpDisconnect(HttpConn *conn)
| Disconnect the connection's socket.
void | httpEaseLimits(HttpLimits *limits)
| Ease the limits.
void | httpEnableConnEvents(HttpConn *conn)
| Enable connection events.
void | httpEnablePutMethod(HttpRoute *route, bool on)
| Enable use of the DELETE and PUT methods.
void | httpEnableQueue(HttpQueue *q)
| Enable a queue after it has been disabled.
void | httpEnableTraceMethod(HttpRoute *route, bool on)
| Enable use of the TRACE Http method.
void | httpEnableUpload(HttpConn *conn)
| Enable Multipart-Mime File Upload for this request.
void | httpError(HttpConn *conn, int status, cchar *fmt, ...)
| Error handling for the connection.
void | httpEvent(struct HttpConn *conn, MprEvent *event)
| Http I/O event handler.
cchar* | httpExpandRouteVars(HttpRoute *route, cchar *str)
| Expand route variables in a string.
void | httpFinalize(HttpConn *conn)
| Indicate the request is finalized.
void | httpFinalizeConnector(HttpConn *conn)
| Finalize connector output sending the response.
void | httpFinalizeOutput(HttpConn *conn)
| Finalize transmission of the http response.
void | httpFinalizeRoute(HttpRoute *route)
| Finalize a route.
void | httpFlush(HttpConn *conn)
| Flush tx data.
bool | httpFlushQueue(HttpQueue *q, bool block)
| Flush queue data.
void | httpFollowRedirects(HttpConn *conn, bool follow)
| Follow redirctions.
void | httpFormatError(HttpConn *conn, int status, cchar *fmt, ...)
| Format an error transmission.
ssize | httpFormatResponse(HttpConn *conn, cchar *fmt, ...)
| Format an alternate response.
ssize | httpFormatResponseBody(HttpConn *conn, cchar *title, cchar *fmt, ...)
| Format a response body.
ssize | httpFormatResponsev(HttpConn *conn, cchar *fmt, va_list args)
| Format an alternate response.
char* | httpFormatUri(cchar *scheme, cchar *host, int port, cchar *path, cchar *ref, cchar *query, int flags)
| Format a URI.
int | httpGetAsync(HttpConn *conn)
| Get the async mode value for the connection.
ssize | httpGetChunkSize(HttpConn *conn)
| Get the preferred chunked size for transfer chunk encoding.
void* | httpGetConnContext(HttpConn *conn)
| Get the connection context object.
void* | httpGetConnHost(HttpConn *conn)
| Get the connection host object.
MprOff | httpGetContentLength(HttpConn *conn)
| Get the receive body content length.
void* | httpGetContext(Http *http)
| Get the http context object.
cchar* | httpGetCookies(HttpConn *conn)
| Get the request cookies.
char* | httpGetDateString(MprPath *sbuf)
| Get the time as an ISO date string.
HttpHost* | httpGetDefaultHost()
| Get the default host defined via httpSetDefaultHost.
HttpRoute* | httpGetDefaultRoute(HttpHost *host)
| Get the default route for a host.
void* | httpGetEndpointContext(HttpEndpoint *endpoint)
| Get the endpoint context object.
cchar* | httpGetError(HttpConn *conn)
| Get the error message associated with the last request.
char* | httpGetExt(HttpConn *conn)
| Get a URI extension.
cchar* | httpGetHeader(HttpConn *conn, cchar *key)
| Get an rx http header.
MprHash* | httpGetHeaderHash(HttpConn *conn)
| Get the hash table of rx Http headers.
char* | httpGetHeaders(HttpConn *conn)
| 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.
int | httpGetIntParam(HttpConn *conn, cchar *var, int defaultValue)
| Get a form variable as an integer.
int | httpGetKeepAliveCount(HttpConn *conn)
| Get the count of Keep-Alive requests that will be used for this connection object.
HttpLang* | httpGetLanguage(HttpConn *conn, MprHash *spoken, cchar *defaultLang)
| Get the language to use for the request.
bool | httpGetMoreOutput(HttpConn *conn)
| Get more output data by invoking the writable callback.
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.
ssize | httpGetPacketLength(HttpPacket *packet)
| Get the length of the packet data contents.
cchar* | httpGetParam(HttpConn *conn, cchar *var, cchar *defaultValue)
| Get a request param.
MprHash* | httpGetParams(HttpConn *conn)
| Get the request params table.
char* | httpGetParamsString(HttpConn *conn)
| Get the request params table as a string.
char* | httpGetPathExt(cchar *path)
| Get a path extension.
cchar* | httpGetQueryString(HttpConn *conn)
| Get the request query string.
void* | httpGetQueueData(HttpConn *conn)
| Get the queue data for the connection.
ssize | httpGetQueueRoom(HttpQueue *q)
| Get the room in the queue.
ssize | httpGetReadCount(HttpConn *conn)
| 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* | httpGetRouteDir(HttpRoute *route)
| Get the route directory.
cchar* | httpGetRouteMethods(HttpRoute *route)
| Get the route method list.
cchar* | httpGetRouteVar(HttpRoute *route, cchar *key)
| Get a path token variable.
HttpSession* | httpGetSession(HttpConn *conn, int create)
| Get a session state object.
char* | httpGetSessionID(HttpConn *conn)
| Get the session ID.
MprHash* | httpGetSessionObj(HttpConn *conn, cchar *key)
| Get an object from the session state store.
cchar* | httpGetSessionVar(HttpConn *conn, cchar *name, cchar *defaultValue)
| Get a session state variable.
cvoid* | httpGetStageData(struct HttpConn *conn, cchar *key)
| Get stage data.
void | httpGetStats(HttpStats *sp)
| Get the Http performance statistics.
int | httpGetStatus(HttpConn *conn)
| Get the response status.
char* | httpGetStatusMessage(HttpConn *conn)
| Get the Http response status message.
char* | httpGetWebSocketCloseReason(HttpConn *conn)
| Get the close reason supplied by the peer.
ssize | httpGetWebSocketMessageLength(HttpConn *conn)
| Get the message length for the current message.
char* | httpGetWebSocketProtocol(HttpConn *conn)
| Get the selected web socket protocol selected by the server.
ssize | httpGetWebSocketState(HttpConn *conn)
| Get the WebSocket state.
ssize | httpGetWriteQueueCount(HttpConn *conn)
| Get the count of bytes buffered on the write queue.
HttpLimits* | httpGraduateLimits(HttpRoute *route, HttpLimits *limits)
| Graduate the limits from the parent route.
void | httpHandleOptionsTrace(struct HttpConn *conn, cchar *methods)
| Handle a Http Trace or Options method request.
bool | httpHasNamedVirtualHosts(HttpEndpoint *endpoint)
| Test if an endpoint has named virtual hosts.
void | httpInitLimits(HttpLimits *limits, bool serverSide)
| Initialize a limits object with default values.
void | httpInsertOption(MprHash *options, cchar *field, cchar *value)
| Add an option to the options table.
bool | httpIsAuthenticated(HttpConn *conn)
| Test if the user is authenticated.
int | httpIsChunked(HttpConn *conn)
| Return whether transfer chunked encoding will be used on this request.
int | httpIsEndpointAsync(HttpEndpoint *endpoint)
| Get if the endpoint is running in asynchronous mode.
bool | httpIsEof(struct HttpConn *conn)
| Test if the connection has received all incoming content.
int | httpIsFinalized(HttpConn *conn)
| Test if request has been finalized.
bool | httpIsLastPacket(HttpPacket *packet)
| Test if the packet is the last in a logical message.
int | httpIsOutputFinalized(HttpConn *conn)
| Test if request response has been fully generated.
bool | httpIsPacketTooBig(struct HttpQueue *q, HttpPacket *packet)
| Test if a packet is too big.
bool | httpIsQueueEmpty(HttpQueue *q)
| Determine if the queue is empty.
bool | httpIsQueueSuspended(HttpQueue *q)
| Test if a queue is suspended.
int | httpJoinPacket(HttpPacket *packet, HttpPacket *other)
| Join two packets.
void | httpJoinPacketForService(struct HttpQueue *q, HttpPacket *packet, bool serviceQ)
| Join a packet onto the service queue.
void | httpJoinPackets(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.
char* | httpLink(HttpConn *conn, cchar *target, MprHash *options)
| Create a URI link.
void | httpLogRoutes(HttpHost *host, bool full)
| Show the current route table to the error log.
bool | httpLogin(HttpConn *conn, cchar *username, cchar *password)
| Log the user in.
struct HttpEndpoint* | httpLookupEndpoint(Http *http, cchar *ip, int port)
| Lookup a listening endpoint.
struct HttpHost* | httpLookupHost(Http *http, 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.
HttpRoute* | httpLookupRoute(HttpHost *host, cchar *name)
| Lookup a route by name.
cchar* | httpLookupRouteErrorDocument(HttpRoute *route, int status)
| Lookup an error document by HTTP status code.
struct HttpStage* | httpLookupStage(Http *http, cchar *name)
| Lookup a stage by name.
void* | httpLookupStageData(Http *http, cchar *name)
| Lookup stage data.
cchar* | httpLookupStatus(Http *http, int status)
| Lookup a Http status code.
char* | httpMakePath(HttpRoute *route, cchar *path)
| Make a filename path.
HttpUri* | httpMakeUriLocal(HttpUri *uri)
| Make a URI local.
void | httpMapFile(HttpConn *conn, HttpRoute *route)
| Map the request URI and route target to a filename.
void | httpMatchHost(HttpConn *conn)
| Match the HttpHost object that should serve this request.
bool | httpMatchParam(HttpConn *conn, cchar *var, cchar *expected)
| Match a form variable with an expected value.
int | httpMatchRoute(HttpConn *conn, HttpRoute *route)
| Match a route against the current request.
void | httpMemoryError(HttpConn *conn)
| Signal a memory allocation error.
bool | httpNeedRetry(HttpConn *conn, char **url)
| Determine if the transmission needs a transparent retry to implement authentication or redirection.
void | httpNormalizeUri(HttpUri *uri)
| Normalize a URI.
char* | httpNormalizeUriPath(cchar *uri)
| Normalize a URI.
void | httpNotify(HttpConn *conn, int event, int arg)
| Inform notifiers of a connection event or state change.
void | httpOmitBody(HttpConn *conn)
| Tell the tx to omit sending any body.
bool | httpOption(MprHash *options, cchar *field, cchar *value, int useDefault)
| Test a field value from an option string.
void | httpPrepClientConn(HttpConn *conn, bool keepHeaders)
| Prepare a client connection for a new request.
bool | httpPumpRequest(HttpConn *conn, HttpPacket *packet)
| Pump the Http engine for a request.
void | httpPutBackPacket(struct HttpQueue *q, HttpPacket *packet)
| Put a packet back onto a queue.
void | httpPutForService(struct HttpQueue *q, HttpPacket *packet, bool serviceQ)
| Put a packet into the service queue for deferred processing.
void | httpPutPacket(struct HttpQueue *q, HttpPacket *packet)
| Put a packet to the queue.
void | httpPutPacketToNext(struct HttpQueue *q, HttpPacket *packet)
| Put a packet to the next queue downstream.
ssize | httpRead(HttpConn *conn, char *buffer, ssize size)
| Read rx body data.
char* | httpReadString(HttpConn *conn)
| Read response data as a string.
void | httpReadyHandler(HttpConn *conn)
| Run the handler ready callback.
void | httpRedirect(HttpConn *conn, int status, cchar *uri)
| Redirect the client.
void | httpRemoveAllUploadedFiles(HttpConn *conn)
| Remove all uploaded files.
int | httpRemoveHeader(HttpConn *conn, cchar *key)
| Remove a header from the transmission.
void | httpRemoveOption(MprHash *options, cchar *field)
| Remove an option.
void | httpRemoveQueue(HttpQueue *q)
| Remove a queue.
int | httpRemoveRole(HttpAuth *auth, cchar *role)
| Remove a role.
int | httpRemoveSessionVar(HttpConn *conn, cchar *name)
| Remove a session state variable.
void | httpRemoveUploadFile(HttpConn *conn, cchar *id)
| Remove an uploaded file.
int | httpRemoveUser(HttpAuth *auth, cchar *user)
| Remove a user.
void | httpResetCredentials(HttpConn *conn)
| Reset the current security credentials.
void | httpResetRoutePipeline(HttpRoute *route)
| Reset the route pipeline.
void | httpResetRoutes(HttpHost *host)
| Reset the list of routes for the host.
int | httpResizePacket(struct HttpQueue *q, HttpPacket *packet, ssize size)
| Resize a packet.
HttpUri* | httpResolveUri(HttpUri *base, int argc, HttpUri **others, bool local)
| Resolve URIs relative to a base.
void | httpResumeQueue(HttpQueue *q)
| Resume a queue.
void | httpRouteRequest(HttpConn *conn)
| Route the request and select that matching route and handle to process the request.
void | httpScheduleQueue(HttpQueue *q)
| Schedule a queue.
int | httpSecureEndpoint(HttpEndpoint *endpoint, struct MprSsl *ssl)
| Secure an endpoint.
int | httpSecureEndpointByName(cchar *name, struct MprSsl *ssl)
| Secure an endpoint by name.
ssize | httpSend(HttpConn *conn, cchar *fmt, ...)
| Send a UTF-8 text message to the web socket peer.
ssize | httpSendBlock(HttpConn *conn, int type, cchar *buf, ssize len, int flags)
| Send a message of a given type to the web socket peer.
void | httpSendClose(HttpConn *conn, int status, cchar *reason)
| Send a close message to the web socket peer.
void | httpServiceQueue(HttpQueue *q)
| Service a queue.
bool | httpServiceQueues(HttpConn *conn)
| Service pipeline queues to flow data.
void | httpSetAsync(HttpConn *conn, int enable)
| Set the async mode value for the connection.
void | httpSetAuthAllow(HttpAuth *auth, cchar *ip)
| Allow access by a client IP IP address.
void | httpSetAuthAnyValidUser(HttpAuth *auth)
| Allow access by any valid user.
void | httpSetAuthAutoLogin(HttpAuth *auth, bool on)
| Enable auto login.
void | httpSetAuthDeny(HttpAuth *auth, cchar *ip)
| Deny access by a client IP address.
void | httpSetAuthForm(struct HttpRoute *parent, cchar *loginPage, cchar *loginService, cchar *logoutService, cchar *loggedIn)
| Define the callbabcks for the 'post' authentication type.
void | httpSetAuthOrder(HttpAuth *auth, int order)
| Set the auth allow/deny order.
void | httpSetAuthPermittedUsers(HttpAuth *auth, cchar *users)
| Define the set of permitted users.
void | httpSetAuthQop(HttpAuth *auth, cchar *qop)
| Set the required quality of service for digest authentication.
void | httpSetAuthRealm(HttpAuth *auth, cchar *realm)
| Set the required realm for basic or digest authentication.
void | httpSetAuthRequiredAbilities(HttpAuth *auth, cchar *abilities)
| Set the required abilities for access.
int | httpSetAuthStore(HttpAuth *auth, cchar *store)
| Set the authentication password store to use.
int | httpSetAuthType(HttpAuth *auth, cchar *proto, cchar *details)
| Set the authentication protocol to use.
void | httpSetChunkSize(HttpConn *conn, ssize size)
| Set the chunk size for transfer chunked encoding.
void | httpSetConnContext(HttpConn *conn, void *context)
| Set the connection context object.
void | httpSetConnHost(HttpConn *conn, void *host)
| Set the connection host object.
void | httpSetConnNotifier(HttpConn *conn, HttpNotifier notifier)
| Define a notifier callback for this connection.
void | httpSetContentLength(HttpConn *conn, MprOff length)
| Define a content length header in the transmission.
void | httpSetContentType(HttpConn *conn, cchar *mimeType)
| Set the transmission (response) content mime type.
void | httpSetContext(Http *http, void *context)
| Set the http context object.
void | httpSetCookie(HttpConn *conn, cchar *name, cchar *value, cchar *path, cchar *domain, MprTicks lifespan, int flags)
| Set a transmission cookie.
void | httpSetCredentials(HttpConn *conn, cchar *user, cchar *password, cchar *authType)
| Set the Http credentials.
void | httpSetDefaultClientHost(Http *http, cchar *host)
| Define a default client host.
void | httpSetDefaultClientPort(Http *http, int port)
| Define a default client port.
void | httpSetDefaultHost(HttpHost *host)
| Set the default host for all servers.
void | httpSetEndpointAddress(HttpEndpoint *endpoint, cchar *ip, int port)
| Set the endpoint IP address.
void | httpSetEndpointAsync(HttpEndpoint *endpoint, int enable)
| Control if the endpoint is running in asynchronous mode.
void | httpSetEndpointContext(HttpEndpoint *endpoint, void *context)
| Set the endpoint context object.
void | httpSetEndpointNotifier(HttpEndpoint *endpoint, HttpNotifier fn)
| Define a notifier callback for this endpoint.
void | httpSetEntityLength(HttpConn *conn, MprOff len)
| Define the length of the transmission content.
void | httpSetForkCallback(struct Http *http, MprForkCallback proc, void *arg)
| Set the fork callback.
void | httpSetHasNamedVirtualHosts(HttpEndpoint *endpoint, bool on)
| Control whether the endpoint has named virtual hosts.
void | httpSetHeader(HttpConn *conn, cchar *key, cchar *fmt, ...)
| Set a transmission header.
void | httpSetHeaderString(HttpConn *conn, cchar *key, cchar *value)
| Set a simple key/value transmission header.
void | httpSetHeadersCallback(struct HttpConn *conn, HttpHeadersCallback fn, void *arg)
| Define a headers callback.
void | httpSetHostDefaultEndpoint(HttpHost *host, HttpEndpoint *endpoint)
| Set the default endpoint for a host.
void | httpSetHostDefaultRoute(HttpHost *host, HttpRoute *route)
| Set the default route for a host.
void | httpSetHostIpAddr(HttpHost *host, cchar *ip, int port)
| Set the host internet address.
void | httpSetHostName(HttpHost *host, cchar *name)
| Set the host name.
void | httpSetHostProtocol(HttpHost *host, cchar *protocol)
| Set the host HTTP protocol version.
void | httpSetHostRoot(HttpHost *host, cchar *root)
| Set the server root for a host.
void | httpSetHostSecureEndpoint(HttpHost *host, HttpEndpoint *endpoint)
| Set the default secure endpoint for a host.
void | httpSetIOCallback(struct HttpConn *conn, HttpIOCallback fn)
| Define an I/O callback for connections.
void | httpSetIntParam(HttpConn *conn, cchar *var, int value)
| Set an integer request param value.
void | httpSetKeepAliveCount(HttpConn *conn, int count)
| Control Http Keep-Alive for the connection.
void | httpSetMethod(HttpConn *conn, cchar *method)
| Set a new HTTP method for processing.
void | httpSetOption(MprHash *options, cchar *field, cchar *value)
| Set an option.
void | httpSetParam(HttpConn *conn, cchar *var, cchar *value)
| Set a request param value.
void | httpSetProtocol(HttpConn *conn, cchar *protocol)
| Set the Http protocol variant for this connection.
void | httpSetProxy(Http *http, cchar *host, int port)
| Define a Http proxy host to use for all client connect requests.
void | httpSetQueueLimits(HttpQueue *q, ssize low, ssize max)
| Set a queue's flow control low and high water marks.
void | httpSetResponded(HttpConn *conn)
| Set the responded flag for the request.
void | httpSetRetries(HttpConn *conn, int retries)
| Set the Http retry count.
void | httpSetRouteAuth(HttpRoute *route, HttpAuth *auth)
| Set the route authentication.
void | httpSetRouteAutoDelete(HttpRoute *route, bool on)
| Control file upload auto delete.
void | httpSetRouteCompression(HttpRoute *route, int flags)
| Contol content compression for the route.
int | httpSetRouteConnector(HttpRoute *route, cchar *name)
| Set the connector to use for a route.
void | httpSetRouteData(HttpRoute *route, cchar *key, void *data)
| Set route data.
void | httpSetRouteDefaultLanguage(HttpRoute *route, cchar *language)
| Set the default language for the route.
void | httpSetRouteDir(HttpRoute *route, cchar *dir)
| Set the route directory.
void | httpSetRouteFlags(HttpRoute *route, int flags)
| Update the route flags.
int | httpSetRouteHandler(HttpRoute *route, cchar *name)
| Set the handler to use for a route.
void | httpSetRouteHome(HttpRoute *route, cchar *home)
| Set the route directory for configuration files.
int | httpSetRouteLog(HttpRoute *route, cchar *path, ssize size, int backup, cchar *format, int flags)
| Configure the route access log.
void | httpSetRouteMethods(HttpRoute *route, cchar *methods)
| Define the methods for the route.
void | httpSetRouteName(HttpRoute *route, cchar *name)
| Set the route name.
void | httpSetRoutePattern(HttpRoute *route, cchar *pattern, int flags)
| Set the route pattern.
void | httpSetRoutePrefix(HttpRoute *route, cchar *prefix)
| Set the route prefix.
void | httpSetRouteScript(HttpRoute *route, cchar *script, cchar *scriptPath)
| Set the script to service the route.
void | httpSetRouteSource(HttpRoute *route, cchar *source)
| Set the source code module for the route.
int | httpSetRouteTarget(HttpRoute *route, cchar *name, cchar *details)
| Set a route target.
void | httpSetRouteTemplate(HttpRoute *route, cchar *tplate)
| Set the route template.
void | httpSetRouteTraceFilter(HttpRoute *route, int dir, int levels[HTTP_TRACE_MAX_ITEM], ssize len, cchar *include, cchar *exclude)
| Set the route trace filter.
void | httpSetRouteVar(HttpRoute *route, cchar *token, cchar *value)
| Define a path token variable.
void | httpSetRouteWorkers(HttpRoute *route, int workers)
| Define the maximum number of workers for a route.
void | httpSetSendConnector(HttpConn *conn, cchar *path)
| Set the "Send" connector to process the request.
int | httpSetSessionObj(HttpConn *conn, cchar *key, MprHash *value)
| Set an object into the session state store.
int | httpSetSessionVar(HttpConn *conn, cchar *name, cchar *value)
| Set a session variable.
void | httpSetSoftware(Http *http, cchar *description)
| Set the software description.
void | httpSetStageData(struct HttpConn *conn, cchar *key, cvoid *data)
| Set stage data.
void | httpSetState(HttpConn *conn, int state)
| Set the connection state and invoke notifiers.
void | httpSetStatus(HttpConn *conn, int status)
| Set a Http response status.
void | httpSetTimeout(HttpConn *conn, MprTicks requestTimeout, MprTicks inactivityTimeout)
| Set the Http inactivity timeout.
void | httpSetTimestamp(MprTicks period)
| Define a timestamp in the MPR log file.
int | httpSetUri(HttpConn *conn, cchar *uri)
| Set a new URI for processing.
void | httpSetWebSocketProtocols(HttpConn *conn, cchar *protocols)
| Set a list of application-level protocols supported by the client.
void | httpSetupWaitHandler(HttpConn *conn, int eventMask)
| Setup a wait handler for the connection to wait for desired events.
int | httpShouldTrace(HttpConn *conn, int dir, int item, cchar *ext)
| Test if the item should be traced.
void | httpSocketBlocked(HttpConn *conn)
| Indicate that the transmission socket is blocked.
HttpPacket* | httpSplitPacket(HttpPacket *packet, ssize offset)
| Split a data packet.
int | httpStartEndpoint(HttpEndpoint *endpoint)
| Start listening for client connections.
void | httpStartPipeline(HttpConn *conn)
| Start the pipeline.
char* | httpStatsReport(int flags)
| Get an Http performance report.
MprSocket* | httpStealConn(HttpConn *conn)
| Steal a connection from Appweb.
void | httpStopEndpoint(HttpEndpoint *endpoint)
| Stop the server listening for client connections.
void | httpSuspendQueue(HttpQueue *q)
| Suspend a queue.
char* | httpTemplate(HttpConn *conn, cchar *tplate, MprHash *options)
| Expand a template string using given options.
int | httpTestParam(HttpConn *conn, cchar *var)
| Test if a request param is defined.
bool | httpTokenize(HttpRoute *route, cchar *str, cchar *fmt, ...)
| Tokenize a string based on route data.
bool | httpTokenizev(HttpRoute *route, cchar *str, cchar *fmt, va_list args)
| Tokenize a string based on route data.
void | httpTrimExtraPath(HttpConn *conn)
| Trim extra path from the URI.
ssize | httpUpdateCache(HttpConn *conn, cchar *uri, cchar *data, MprTicks lifespan)
| Update the cached content for a URI.
int | httpUpgradeWebSocket(HttpConn *conn)
| Upgrade a client HTTP connection connection to use WebSockets.
char* | httpUriToString(HttpUri *uri, int flags)
| Convert a Uri to a string.
bool | httpValidateLimits(HttpEndpoint *endpoint, int event, HttpConn *conn)
| Validate the request against defined resource limits.
bool | httpVerifyWebSocketsHandshake(HttpConn *conn)
| Verify the server handshake.
int | httpWait(HttpConn *conn, int state, MprTicks timeout)
| Wait for the connection to achieve the requested state.
bool | httpWebSocketOrderlyClosed(HttpConn *conn)
| Test if web socket connection was orderly closed by sending an acknowledged close message.
bool | httpWillNextQueueAcceptPacket(HttpQueue *q, HttpPacket *packet)
| Determine if the downstream queue will accept this packet.
bool | httpWillNextQueueAcceptSize(HttpQueue *q, ssize size)
| Determine if the downstream queue will accept a certain amount of data.
bool | httpWillQueueAcceptPacket(HttpQueue *q, HttpPacket *packet, bool split)
| Determine if the given queue will accept this packet.
ssize | httpWrite(HttpQueue *q, cchar *fmt, ...)
| Write a formatted string.
ssize | httpWriteBlock(HttpQueue *q, cchar *buf, ssize size, int flags)
| Write a block of data to the queue.
ssize | httpWriteCached(HttpConn *conn)
| Write the cached content for a URI to the client.
void | httpWriteHeaders(HttpQueue *q, HttpPacket *packet)
| Write the transmission headers into the given packet.
void | httpWriteRouteLog(HttpRoute *route, cchar *buf, ssize len)
| Write data to the route access log.
ssize | httpWriteString(HttpQueue *q, cchar *s)
| Write a string of data to the queue.
ssize | httpWriteUploadData(HttpConn *conn, MprList *formData, MprList *fileData)
| Write Http upload body data.

# Typedefs

HttpAskLogin | AuthType callback to generate a response requesting the user login This should call httpError if such a response cannot be generated.
HttpAuthStore | Password backend store.
HttpAuthType | Authentication Protocol.
HttpEnvCallback | Set environment vars callback.
HttpFillProc | Callback procedure to fill a packet with data.
HttpHeadersCallback | Callback to fill headers.
HttpIOCallback | I/O callback for connections.
HttpLang | Language definition record for routes.
HttpListenCallback | Listen callback.
HttpNotifier | Connection Http state change notification callback.
HttpParseAuth | AuthType callback to parse the HTTP 'Authorize' (client) and 'www-authenticate' (server) headers.
HttpRedirectCallback | Define an callback for IO events on this connection.
HttpRole | Authorization Roles.
HttpRouteOp | Route operation record.
HttpRouteProc | General route procedure.
HttpSetAuth | AuthType callback to set the necessary HTTP authorization headers for a client request.
HttpTimeoutCallback | Timeout callback.
HttpUser | User Authorization.
HttpVerifyUser | AuthStore callback Verify the user credentials.

# Defines

#define | BIT_HTTP_SOFTWARE "Embedthis-http"
| Default Http protocol name used in Http Server header.
#define | BIT_MAX_CACHE_DURATION (86400 * 1000)
| Default cache lifespan to 1 day.
#define | BIT_MAX_CACHE_ITEM (256 * 1024)
| Maximum cachable item size.
#define | BIT_MAX_CHUNK (8 * 1024)
| Maximum chunk size for transfer chunk encoding.
#define | BIT_MAX_CLIENTS 32
| Maximum concurrent client endpoints.
#define | BIT_MAX_CLIENTS_HASH 131
| Hash table for client IP addresses.
#define | BIT_MAX_HEADERS 8192
| Maximum size of the headers.
#define | BIT_MAX_INACTIVITY_DURATION (60 * 1000)
| Default keep connection alive between requests timeout.
#define | BIT_MAX_IOVEC 16
| Number of fragments in a single socket write.
#define | BIT_MAX_KEEP_ALIVE 200
| Maximum requests per connection.
#define | BIT_MAX_NUM_HEADERS 30
| Maximum number of header lines.
#define | BIT_MAX_PARSE_DURATION (30 * 1000)
| Default request parse header timeout.
#define | BIT_MAX_PING_DURATION (30 * 1000)
| WSS ping defeat Keep-Alive timeouts (30 sec).
#define | BIT_MAX_QBUFFER (32 * 1024)
| Maximum buffer for any pipeline queue.
#define | BIT_MAX_RECEIVE_BODY (128 * 1024 * 1024)
| Maximum incoming body size.
#define | BIT_MAX_RECEIVE_FORM (1024 * 1024)
| Maximum incoming form size.
#define | BIT_MAX_REQUEST_DURATION MAXINT
| Default request timeout (unlimited).
#define | BIT_MAX_REQUESTS 50
| Maximum concurrent requests.
#define | BIT_MAX_REQUESTS_PER_CLIENT 20
| Maximum concurrent requests.
#define | BIT_MAX_REWRITE 20
| Maximum URI rewrites.
#define | BIT_MAX_ROUTE_MATCHES 32
| Maximum number of submatches in routes.
#define | BIT_MAX_SESSION_DURATION (3600 * 1000)
| Default session timeout (one hour).
#define | BIT_MAX_SESSIONS 100
| Maximum concurrent sessions.
#define | BIT_MAX_TX_BODY (INT_MAX)
| Maximum buffer for response data.
#define | BIT_MAX_URI 1024
| Reasonable URI size.
#define | BIT_MAX_WSS_FRAME (4 * 1024)
| Default max WebSockets message frame size.
#define | BIT_MAX_WSS_PACKET (8 * 1024)
| Default size to provide to application in one packet.
#define | BIT_MAX_WSS_SOCKETS 200
| Default max WebSockets.
#define | HTTP_ADDED_FORM_PARAMS 0x800
| Form body data added to params.
#define | HTTP_ADDED_QUERY_PARAMS 0x400
| Query added to params.
#define | HTTP_ALLOW_DENY 0x1
| Run allow checks before deny checks.
#define | HTTP_AUTH_CHECKED 0x4000
| User authentication has been checked.
#define | HTTP_AUTO_LOGIN 0x4
| Auto login for debug.
#define | HTTP_BLOCK 0x2
| Flag for httpSendBlock and httpWriteBlock to indicate blocking operation.
#define | HTTP_BUFFER 0x1
| Flag for httpSendBlock and httpWriteBlock to always absorb the data without blocking.
#define | HTTP_CACHE_ALL 0x10
| Cache the same pathInfo together regardless of the request params.
#define | HTTP_CACHE_CLIENT 0x1
| Cache on the client side.
#define | HTTP_CACHE_MANUAL 0x4
| Cache manually.
#define | HTTP_CACHE_ONLY 0x20
| Cache exactly the specified URI with params.
#define | HTTP_CACHE_RESET 0x8
| Don't inherit cache config from outer routes.
#define | HTTP_CACHE_SERVER 0x2
| Cache on the server side.
#define | HTTP_CACHE_UNIQUE 0x40
| Uniquely cache request with different params.
#define | HTTP_CHUNK_DATA 2
| Start of chunk data.
#define | HTTP_CHUNK_EOF 3
| End of last chunk.
#define | HTTP_CHUNK_START 1
| Start of a new chunk.
#define | HTTP_CHUNK_UNCHUNKED 0
| Data is not transfer-chunk encoded.
#define | HTTP_CHUNKED 0x200
| Content is chunk encoded.
#define | HTTP_CLIENT_SIDE 0x1
| Initialize the client-side support.
#define | HTTP_CODE_ACCEPTED 202
| The request has been accepted and processing is continuing.
#define | HTTP_CODE_BAD_GATEWAY 502
| The server cannot act as a gateway for the given request.
#define | HTTP_CODE_BAD_HANDSHAKE 551
| The server handsake response is unacceptable.
#define | HTTP_CODE_BAD_METHOD 405
| The request HTTP method was not supported by the resource.
#define | HTTP_CODE_BAD_REQUEST 400
| The request is malformed.
#define | HTTP_CODE_BAD_VERSION 505
| The server does not support the HTTP protocol version.
#define | HTTP_CODE_COMMS_ERROR 550
| The server had a communicationss error responding to the client.
#define | HTTP_CODE_CONFLICT 409
| The request had a conflict in the request headers and URI.
#define | HTTP_CODE_CONTINUE 100
| Continue with request, only partial content transmitted.
#define | HTTP_CODE_CREATED 201
| The request has completed and a new resource was created.
#define | HTTP_CODE_EXPECTATION_FAILED 417
| The server cannot satisfy the Expect header requirements.
#define | HTTP_CODE_FORBIDDEN 403
| The request was legal, but the server refuses to process.
#define | HTTP_CODE_GATEWAY_TIMEOUT 504
| The server gateway timed out waiting for the upstream server.
#define | HTTP_CODE_GONE 410
| The requested resource is no longer available.
#define | HTTP_CODE_INSUFFICIENT_STORAGE 507
| The server has insufficient storage to complete the request.
#define | HTTP_CODE_INTERNAL_SERVER_ERROR 500
| Server processing or configuration error.
#define | HTTP_CODE_LENGTH_REQUIRED 411
| The request did not specify a required content length.
#define | HTTP_CODE_MOVED_PERMANENTLY 301
| The requested URI has moved permanently to a new location.
#define | HTTP_CODE_MOVED_TEMPORARILY 302
| The URI has moved temporarily to a new location.
#define | HTTP_CODE_NO_CONTENT 204
| The request has completed and there is no response to send.
#define | HTTP_CODE_NO_RESPONSE 444
| The connection was closed with no response to the client.
#define | HTTP_CODE_NOT_ACCEPTABLE 406
| The requested resource cannot generate the required content.
#define | HTTP_CODE_NOT_AUTHORITATIVE 203
| The request has completed but content may be from another source.
#define | HTTP_CODE_NOT_FOUND 404
| The requested resource was not found.
#define | HTTP_CODE_NOT_IMPLEMENTED 501
| The server does not recognize the request or method.
#define | HTTP_CODE_NOT_MODIFIED 304
| The requested resource has changed since the last request.
#define | HTTP_CODE_OK 200
| The request completed successfully.
#define | HTTP_CODE_PARTIAL 206
| The request has completed and is returning partial content.
#define | HTTP_CODE_PAYMENT_REQUIRED 402
| Reserved for future use.
#define | HTTP_CODE_PRECOND_FAILED 412
| The server cannot satisfy one of the request preconditions.
#define | HTTP_CODE_RANGE_NOT_SATISFIABLE 416
| The request content range does not exist for the resource.
#define | HTTP_CODE_REQUEST_TIMEOUT 408
| The server timed out waiting for the request to complete.
#define | HTTP_CODE_REQUEST_TOO_LARGE 413
| The request is too large for the server to process.
#define | HTTP_CODE_REQUEST_URL_TOO_LARGE 414
| The request URI is too long for the server to process.
#define | HTTP_CODE_RESET 205
| The request has completed with no content.
#define | HTTP_CODE_SEE_OTHER 303
| The requested URI can be found at another URI location.
#define | HTTP_CODE_SERVICE_UNAVAILABLE 503
| The server is currently unavailable or overloaded.
#define | HTTP_CODE_SWITCHING 101
| Switching protocols.
#define | HTTP_CODE_TEMPORARY_REDIRECT 307
| The request should be repeated at another URI location.
#define | HTTP_CODE_UNAUTHORIZED 401
| Authentication for the request has failed.
#define | HTTP_CODE_UNSUPPORTED_MEDIA_TYPE 415
| The request media type is not supported by the server or resource.
#define | HTTP_CODE_USE_PROXY 305
| The requested resource must be accessed via the location proxy.
#define | HTTP_COMPLETE_URI 0x1
| Complete all missing URI fields.
#define | HTTP_COMPLETE_URI_PATH 0x2
| Complete missing URI path.
#define | HTTP_COOKIE_HTTP 0x2
| Flag for httpSetCookie for http cookies (http only).
#define | HTTP_COOKIE_SECURE 0x1
| Flag for httpSetCookie for secure cookies (https only).
#define | HTTP_CREATE_ENV 0x80
| Must create env for this request.
#define | HTTP_DELAY_SERVICE 0
| Delay servicing the queue.
#define | HTTP_DELETE 0x1
| DELETE method.
#define | HTTP_DENY_ALLOW 0x2
| Run deny checks before allow checks.
#define | HTTP_EVENT_APP_CLOSE 7
| The request is now closed.
#define | HTTP_EVENT_APP_OPEN 6
| The request is now open.
#define | HTTP_EVENT_DESTROY 5
| The connection is being closed and destroyed.
#define | HTTP_EVENT_ERROR 4
| The request has an error.
#define | HTTP_EVENT_READABLE 2
| The request has data available for reading.
#define | HTTP_EVENT_STATE 1
| Notifier events.
#define | HTTP_EVENT_WRITABLE 3
| The request is now writable (post / put data).
#define | HTTP_EXPECT_CONTINUE 0x2000
| Client expects an HTTP 100 Continue response.
#define | HTTP_GET 0x2
| GET method.
#define | HTTP_HEAD 0x4
| HEAD method.
#define | HTTP_HOST_NAMED_VHOST 0x2
| Host flag for a named virtual host.
#define | HTTP_HOST_NO_TRACE 0x10
| Host flag to disable the of TRACE HTTP method.
#define | HTTP_HOST_VHOST 0x1
| Host flag to signify host is a virtual host.
#define | HTTP_IF_MODIFIED 0x100
| If-[un]modified-since supplied.
#define | HTTP_LANG_AFTER 0x2
| Insert suffix after extension.
#define | HTTP_LANG_BEFORE 0x1
| Insert suffix before extension.
#define | HTTP_LIMITS_OPENED 0x1000
| Request limits opened.
#define | HTTP_MAX_QUEUE 2
| Number of queue types.
#define | HTTP_MAX_SECRET 16
| Size of secret data for auth.
#define | HTTP_MAX_WSS_MESSAGE (2147483647)
| Default max WebSockets message size (2GB).
#define | HTTP_MORE 0x1000
| Flag for httpSendBlock to indicate there are more frames for this message.
#define | HTTP_NAMED_VHOST 0x1
| Using named virtual hosting.
#define | HTTP_NEW_DISPATCHER 0x2
| New dispatcher for each connection.
#define | HTTP_NON_BLOCK 0x4
| Flag for httpSendBlock and httpWriteBlock to indicate non-blocking operation.
#define | HTTP_OPTIONS 0x8
| OPTIONS method.
#define | HTTP_PACKET_DATA 0x4
| Packet contains actual content data.
#define | HTTP_PACKET_END 0x8
| End of stream packet.
#define | HTTP_PACKET_HEADER 0x1
| Packet contains HTTP headers.
#define | HTTP_PACKET_RANGE 0x2
| Packet is a range boundary packet.
#define | HTTP_PACKET_SOLO 0x10
| Don't join this packet.
#define | HTTP_POST 0x10
| Post method.
#define | HTTP_PUT 0x20
| PUT method.
#define | HTTP_QUEUE_ALL 0x10
| Queue has all the data there is and will be.
#define | HTTP_QUEUE_EOF 0x40
| Queue at end of data.
#define | HTTP_QUEUE_OPEN 0x1
| Queue's open routine has been called.
#define | HTTP_QUEUE_READY 0x100
| Handler stage ready routine called.
#define | HTTP_QUEUE_RESERVICE 0x200
| Queue requires reservicing.
#define | HTTP_QUEUE_RX 1
| Receive (read from client) queue.
#define | HTTP_QUEUE_SERVICED 0x20
| Queue has been serviced at least once.
#define | HTTP_QUEUE_STARTED 0x80
| Handler stage start routine called.
#define | HTTP_QUEUE_SUSPENDED 0x2
| Queue's service routine is suspended due to flow control.
#define | HTTP_QUEUE_TX 0
| Send (transmit to client) queue.
#define | HTTP_RETRIES 3
| Default number of retries for client requests.
#define | HTTP_ROUTE_FREE 0x2
| Free Route.mdata back to malloc when route is freed.
#define | HTTP_ROUTE_FREE_PATTERN 0x4
| Free Route.patternCompiled back to malloc when route is freed.
#define | HTTP_ROUTE_GZIP 0x1000
| Support gzipped content on this route.
#define | HTTP_ROUTE_NOT 0x1
| Negate the route pattern test result.
#define | HTTP_ROUTE_OK 0
| The route matches the request.
#define | HTTP_ROUTE_PUT_DELETE_METHODS 0x4000
| Support PUT|DELETE on this route.
#define | HTTP_ROUTE_RAW 0x8
| Don't html encode the write data.
#define | HTTP_ROUTE_REJECT 1
| The route does not match the request.
#define | HTTP_ROUTE_REROUTE 2
| Request has been modified and must be re-routed.
#define | HTTP_ROUTE_STARTED 0x2000
| Route initialized.
#define | HTTP_ROUTE_TRACE_METHOD 0x8000
| Enable the trace method for handlers supporting it.
#define | HTTP_SCHEDULE_QUEUE 1
| Schedule the queue for service.
#define | HTTP_SERVER_SIDE 0x2
| Initialize the server-side support.
#define | HTTP_SESSION_AUTHVER "_:VERSION:_"
| Auth version number.
#define | HTTP_SESSION_COOKIE "-http-session-"
| Session cookie name.
#define | HTTP_SESSION_USERNAME "_:USERNAME:_"
| Username variable.
#define | HTTP_STAGE_AUTO_DIR 0x10000
| Want auto directory redirection.
#define | HTTP_STAGE_CONNECTOR 0x1000
| Stage is a connector.
#define | HTTP_STAGE_FILTER 0x4000
| Stage is a filter.
#define | HTTP_STAGE_HANDLER 0x2000
| Stage is a handler.
#define | HTTP_STAGE_MODULE 0x8000
| Stage is a filter.
#define | HTTP_STAGE_RX 0x40000
| Stage to be used in the Rx direction.
#define | HTTP_STAGE_TX 0x80000
| Stage to be used in the Tx direction.
#define | HTTP_STAGE_UNLOADED 0x20000
| Stage module library has been unloaded.
#define | HTTP_STATE_BEGIN 1
| Ready for a new request.
#define | HTTP_STATE_COMPLETE 9
| Request complete.
#define | HTTP_STATE_CONNECTED 2
| Connection received or made.
#define | HTTP_STATE_CONTENT 5
| Reading posted content.
#define | HTTP_STATE_FINALIZED 8
| Input received, request processed and response transmitted.
#define | HTTP_STATE_FIRST 3
| First request line has been parsed.
#define | HTTP_STATE_PARSED 4
| Headers have been parsed, handler can start.
#define | HTTP_STATE_READY 6
| Handler ready - all body data received.
#define | HTTP_STATE_RUNNING 7
| Handler running.
#define | HTTP_TIMER_PERIOD 1000
| HttpTimer checks ever 1 second.
#define | HTTP_TRACE 0x40
| TRACE method.
#define | HTTP_TRACE_BODY 3
| Body content.
#define | HTTP_TRACE_CONN 0
| New connections.
#define | HTTP_TRACE_FIRST 1
| First line of header only.
#define | HTTP_TRACE_HEADER 2
| Header.
#define | HTTP_TRACE_LIMITS 4
| Request and connection count limits.
#define | HTTP_TRACE_MAX_DIR 2
| Trace transmission.
#define | HTTP_TRACE_RX 0
| Trace reception.
#define | HTTP_TRACE_TIME 5
| Instrument http pipeline.
#define | HTTP_TRACE_TX 1
| Trace transmission.
#define | HTTP_TX_HEADERS_CREATED 0x2
| Response headers have been created.
#define | HTTP_TX_MATCHED 0x20
| Handler match routine run.
#define | HTTP_TX_NO_BODY 0x1
| No transmission body, only send headers.
#define | HTTP_TX_NO_LENGTH 0x10
| Don't emit a content length (used for TRACE).
#define | HTTP_TX_SENDFILE 0x4
| Relay output via Send connector.
#define | HTTP_TX_USE_OWN_HEADERS 0x8
| Skip adding default headers.
#define | HTTP_UTILITY 0x4
| Http engine for utilities (esp).
#define | HTTP_VALIDATE_CLOSE_CONN 2
| Close a connection.
#define | HTTP_VALIDATE_CLOSE_PROCESS 6
| Close a CGI process.
#define | HTTP_VALIDATE_CLOSE_REQUEST 4
| Close a request.
#define | HTTP_VALIDATE_OPEN_CONN 1
| Open a new connection.
#define | HTTP_VALIDATE_OPEN_PROCESS 5
| Open a new CGI process.
#define | HTTP_VALIDATE_OPEN_REQUEST 3
| Open a new request.
#define | WS_MSG_BINARY 0x2
| httpSendBlock type for binary messages.
#define | WS_MSG_CLOSE 0x8
| httpSendBlock type for close message.
#define | WS_MSG_CONT 0x0
| Continuation of WebSocket message.
#define | WS_MSG_CONTROL 0x8
| Start of control messages.
#define | WS_MSG_MAX 0xB
| Max message type for httpSendBlock.
#define | WS_MSG_PING 0x9
| httpSendBlock type for ping messages.
#define | WS_MSG_PONG 0xA
| httpSendBlock type for pong messages.
#define | WS_MSG_TEXT 0x1
| httpSendBlock type for text messages.
#define | WS_STATE_CLOSED 3
| WebSocket is closed.
#define | WS_STATE_CLOSING 2
| WebSocket is closing.
#define | WS_STATE_CONNECTING 0
| WebSocket connection is being established.
#define | WS_STATE_OPEN 1
| WebSocket handsake is complete and ready for communications.
#define | WS_STATUS_COMMS_ERROR 1006
| TCP/IP communications error.
#define | WS_STATUS_FRAME_TOO_LARGE 1004
| Message frame is too large.
#define | WS_STATUS_GOING_AWAY 1001
| Endpoint is going away.
#define | WS_STATUS_INTERNAL_ERROR 1011
| Server terminating due to an internal error.
#define | WS_STATUS_INVALID_UTF8 1007
| Text message has invalid UTF-8.
#define | WS_STATUS_MAX 5000
| Maximum error status (less one).
#define | WS_STATUS_MESSAGE_TOO_LARGE 1009
| Message is too large.
#define | WS_STATUS_MISSING_EXTENSION 1010
| Unsupported WebSockets extension.
#define | WS_STATUS_NO_STATUS 1005
| No status was received from the peer in closing.
#define | WS_STATUS_OK 1000
| Normal closure.
#define | WS_STATUS_POLICY_VIOLATION 1008
| Application level policy violation.
#define | WS_STATUS_PROTOCOL_ERROR 1002
| WebSockets protocol error.
#define | WS_STATUS_TLS_ERROR 1015
| TLS handshake error.
#define | WS_STATUS_UNSUPPORTED_TYPE 1003
| Unsupported message data type.

# Http

Http

Http service object.

Description:
  The Http service is managed by a single service object.

See Also:
  HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

API Stability:
  Internal.

Fields:

  struct HttpStage * |  | actionHandler | Action handler.
  int |  | activeProcesses | Count of active external processes.
  int |  | activeSessions | Count of active sessions.
  int |  | activeVMs | Number of ejs VMs.
  MprHash * |  | authStores | Available password stores.
  MprHash * |  | authTypes | Available authentication protocol types.
  MprTime |  | booted | 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 HttpStage * |  | clientHandler | Client-side handler (dummy).
  struct HttpLimits * |  | clientLimits | Client resource limits.
  struct HttpRoute * |  | clientRoute | Default route for clients.
  MprList * |  | connections | Currently open connection requests.
  void * |  | context | Embedding context.
  char * |  | currentDate | Date string for HTTP response headers.
  MprTicks |  | currentTime | When currentDate was last calculated (ticks).
  char * |  | defaultClientHost | Default ip address.
  int |  | defaultClientPort | Default port.
  struct HttpStage * |  | dirHandler | Directory listing handler.
  struct HttpStage * |  | egiHandler | Embedded Gateway Interface (EGI) handler.
  struct HttpStage * |  | ejsHandler | Ejscript Web Framework handler.
  MprList * |  | endpoints | Currently configured listening endpoints.
  HttpEnvCallback |  | envCallback | SetEnv callback.
  struct HttpStage * |  | espHandler | ESP Web Framework handler.
  struct HttpStage * |  | fileHandler | Static file handler.
  int |  | flags | Open flags.
  MprForkCallback |  | forkCallback | Callback in child after fork().
  MprList * |  | hosts | List of host objects.
  HttpListenCallback |  | listenCallback | Invoked when creating listeners.
  struct HttpStage * |  | netConnector | Default network connector.
  int |  | nextAuth | Auth object version vector.
  MprTicks |  | now | When was the currentDate last computed.
  struct HttpStage * |  | passHandler | Pass through handler.
  struct HttpStage * |  | phpHandler | PHP through handler.
  char * |  | protocol | HTTP/1.0 or HTTP/1.1.
  char * |  | proxyHost | Proxy ip address.
  int |  | proxyPort | Proxy port.
  struct HttpStage * |  | rangeFilter | Ranged requests filter.
  HttpRedirectCallback |  | redirectCallback | Redirect callback.
  MprHash * |  | routeConditions | Http route condition functions.
  MprHash * |  | routeTargets | Http route target functions.
  MprHash * |  | routeUpdates | Http route update functions.
  char * |  | secret | Random bytes for authentication.
  struct HttpStage * |  | sendConnector | Optimized sendfile connector.
  struct HttpLimits * |  | serverLimits | Server resource limits.
  MprCache * |  | sessionCache | Session state cache.
  char * |  | software | Software name and version.
  MprHash * |  | stages | Possible stages in connection pipelines.
  MprHash * |  | statusCodes | Http status codes.
  MprEvent * |  | timer | Admin service timer.
  MprEvent * |  | timestamp | Timestamp timer.
  uint64 |  | totalConnections | Total connections accepted.
  uint64 |  | totalRequests | Total requests served.
  int |  | underAttack | Under DOS attack.
  struct HttpStage * |  | uploadFilter | Upload filter.
  struct HttpStage * |  | webSocketFilter | WebSocket filter.

void httpAddOption (MprHash *options, cchar *field, cchar *value)

Add an option to the options table.

Parameters:

  options | Option table returned from httpGetOptions.
  field | Field key name.
  value | Value to use for the field.

API Stability:
  Evolving.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, 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:

  flags | Set to zero to initialize bo Initialize the client-side support only.

Returns:
  The http service object.

API Stability:
  Stable.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreateSecret, httpDestroy, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

int httpCreateSecret (Http *http)

Create the Http secret data for crypto.

Description:
  Create http secret data that is used to seed SSL-based communications.

Parameters:

  http | Http service object.

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpDestroy, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

void httpDestroy (Http *http)

Destroy the Http service object.

Parameters:

  http | Http service object.

API Stability:
  Stable.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

void * httpGetContext (Http *http)

Get the http context object.

Parameters:

  http | Http service object.

Returns:
  The http context object defined via httpSetContext.

API Stability:
  Stable.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

char * httpGetDateString (MprPath *sbuf)

Get the time as an ISO date string.

Parameters:

  sbuf | Optional 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, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, 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:

  options | Option string of the form: "field='value' field='value'...".
  field | Field key name.
  defaultValue | Value to use if "field" is not found in options.

Returns:
  Option value.

API Stability:
  Evolving.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, 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:

  options | Options object to examine.
  field | Property to return.

Returns:
  An MprHash instance for the given field. This will contain option sub-properties.

API Stability:
  Evolving.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

MprHash * httpGetOptions (cchar *options)

Convert an options string into an options table.

Parameters:

  options | Option 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:
  Evolving.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, 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:

  options | Option table returned from httpGetOptions.
  field | Field key name.
  value | Value to use for the field.

API Stability:
  Evolving.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

struct HttpEndpoint * HttpEndpoint* httpLookupEndpoint (Http *http, cchar *ip, int port)

Lookup a listening endpoint.

Parameters:

  http | Http object created via httpCreate
  ip | Listening IP address to look for.
  port | Listening port number.

Returns:
  HttpEndpoint object.

API Stability:
  Stable.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, httpGetContext, httpGetDateString, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

struct HttpHost * HttpHost* httpLookupHost (Http *http, cchar *name)

Lookup a host by name.

Parameters:

  http | Http object created via httpCreate
  name | The name of the host to find.

Returns:
  The corresponding host object.

API Stability:
  Stable.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

cchar * httpLookupStatus (Http *http, int status)

Lookup a Http status code.

Description:
  Lookup the code and return the corresponding text message briefly expaining the status.

Parameters:

  http | Http object created via httpCreate
  status | Http status code.

Returns:
  Text message corresponding to the status code.

API Stability:
  Stable.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, 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:

  options | Option string of the form: "field='value' field='value'...".
  field | Field key name.
  value | Test if the field is set to this value.
  useDefault | If true and "field" is not found in options, return true.

Returns:
  Allocated value string.

API Stability:
  Evolving.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, 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:

  options | Options table returned from httpGetOptions.
  field | Property field to remove.

API Stability:
  Evolving.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, 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:

  options | Options table returned from httpGetOptions.
  field | Property field to set.
  value | Property value to use.

API Stability:
  Evolving.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy, httpSetSoftware

void httpSetProxy (Http *http, 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:

  http | Http object created via httpCreate
  host | Proxy host name or IP address.
  port | Proxy host port number.

API Stability:
  Stable.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetSoftware

void httpSetSoftware (Http *http, cchar *description)

Set the software description.

Parameters:

  http | Http object created via httpCreate
  description | String describing the Http software. By default, this is set to HTTP_NAME.

API Stability:
  Stable.

See Also:
  Http, HttpConn, HttpEndpoint, httpCreate, httpCreateSecret, httpDestroy, httpGetContext, httpGetDateString, httpLookupEndpoint, httpLookupStatus, httpSetContext, httpSetDefaultClientHost, httpSetDefaultClientPort, httpSetForkCallback, httpSetProxy

# 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, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

API Stability:
  Internal.

Fields:

  MprHash * |  | allow | Clients to allow.
  MprHash * |  | deny | Clients to deny.
  int |  | flags | Authorization flags.
  char * |  | loggedIn | Target URI after logging in.
  char * |  | loginPage | Web page for user login for 'post' type.
  struct HttpAuth * |  | parent | Parent auth.
  MprHash * |  | permittedUsers | User name for access.
  char * |  | qop | Quality of service.
  char * |  | realm | Realm of access.
  MprHash * |  | requiredAbilities | Set of required abilities (all are required).
  MprHash * |  | roles | Hash of roles.
  HttpAuthStore * |  | store | Authorization password backend (system|file|custom).
  HttpAuthType * |  | type | Authorization protocol type (basic|digest|form|custom).
  MprHash * |  | users | Hash of users.
  int |  | version | Inherited from parent and incremented on changes.

int httpAddAuthStore (Http *http, cchar *name, HttpVerifyUser verifyUser)

Add an authorization store for password validation.

The pre-supplied types are 'system' and 'file'

Description:
  This creates an AuthType object with the defined name and callbacks.

Parameters:

  http | Http service object.
  name | Unique authorization type name.
  verifyUser | Callback to verify the username and password contained in the HttpConn object passed to the callback.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

int httpAddAuthType (Http *http, cchar *name, HttpAskLogin askLogin, HttpParseAuth parse, HttpSetAuth setAuth)

Add an authorization type.

The pre-supplied types are 'basic', 'digest' and 'post'

Description:
  This creates an AuthType object with the defined name and callbacks.

Parameters:

  http | Http service object.
  name | Unique authorization type name.
  askLogin | Callback to generate a client login response.
  parse | Callback to parse the HTTP authentication headers.
  setAuth | Callback to set the HTTP response authentication headers.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

int httpAddRole (HttpAuth *auth, cchar *role, cchar *abilities)

Add a role.

Description:
  This creates the role with given abilities. Ability words can also be other roles.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  role | Role name to add.
  abilities | Space separated list of abilities.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

int httpAddUser (HttpAuth *auth, cchar *user, cchar *password, cchar *abilities)

Add a user.

Description:
  This creates the user and adds the user to the authentication database.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  user | User name to add.
  password | User password. The password should not be encrypted. The backend will encrypt as required.
  abilities | Space separated list of abilities.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

bool httpCanUser (HttpConn *conn)

Test if a user has the required abilities.

Parameters:

  conn | HttpConn connection object created via httpCreateConn object.

Returns:
  True if the user has all the required abilities.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpComputeAllUserAbilities (HttpAuth *auth)

Compute all the user abilities for a route using the given auth.

Parameters:

  auth | Auth object allocated by httpCreateAuth

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpComputeUserAbilities (HttpAuth *auth, HttpUser *user)

Compute the user abilities for a given user in a route using the given auth.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  user | User object.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

HttpAuth * httpCreateAuth ()

Create an authentication object.

Returns:
  An empty authentiction object.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

HttpRole * httpCreateRole (HttpAuth *auth, cchar *name, cchar *abilities)

Create a new role.

Description:
  The role is not added to the authentication database.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  name | Role name.
  abilities | Space separated list of abilities.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

HttpUser * httpCreateUser (HttpAuth *auth, cchar *name, cchar *password, cchar *abilities)

Create a new user.

Description:
  The user is not added to the authentication database.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  name | User name.
  password | User password. The password should not be encrypted. The backend will encrypt as required.
  abilities | Space separated list of abilities.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

bool httpIsAuthenticated (HttpConn *conn)

Test if the user is authenticated.

Parameters:

  conn | HttpConn connection object.

Returns:
  True if the username and password have been authenticated and the user has the abilities required to access the requested resource document.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

bool httpLogin (HttpConn *conn, 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:

  conn | HttpConn connection object.
  username | User name to authenticate.
  password | Password for the user.

Returns:
  True if the username and password have been authenticated.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

int httpRemoveRole (HttpAuth *auth, cchar *role)

Remove a role.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  role | Role name to remove.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

int httpRemoveUser (HttpAuth *auth, cchar *user)

Remove a user.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  user | User name to remove.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpSetAuthAllow (HttpAuth *auth, cchar *ip)

Allow access by a client IP IP address.

Parameters:

  auth | Authorization object allocated by httpCreateAuth
  ip | Client IP address to allow.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpSetAuthAnyValidUser (HttpAuth *auth)

Allow access by any valid user.

Description:
  This configures the basic or digest authentication for the authorization object.

Parameters:

  auth | Authorization object allocated by httpCreateAuth

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpSetAuthAutoLogin (HttpAuth *auth, bool on)

Enable auto login.

Description:
  If auto-login is enabled, access will be granted to all resources.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  on | Set to true to enable auto login.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpSetAuthDeny (HttpAuth *auth, cchar *ip)

Deny access by a client IP address.

Parameters:

  auth | Authorization object allocated by httpCreateAuth
  ip | Client IP address to deny. This must be an IP address string.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpSetAuthForm (struct HttpRoute *parent, cchar *loginPage, cchar *loginService, cchar *logoutService, cchar *loggedIn)

Define the callbabcks for the 'post' authentication type.

Description:
  This creates a new route for the login page.

Parameters:

  parent | Parent route from which to inherit when creating a route for the login page.
  loginPage | Web page URI for the user to enter username and password.
  loginService | URI to use for the internal login service. To use your own login URI, set to this the empty string.
  logoutService | URI to use to log the user out. To use your won logout URI, set this to the empty string.
  loggedIn | The 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:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpSetAuthOrder (HttpAuth *auth, int order)

Set the auth allow/deny order.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  order | Set to HTTP_ALLOW_DENY to run allow checks before deny checks. Set to HTTP_DENY_ALLOW to run deny checks before allow.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpSetAuthPermittedUsers (HttpAuth *auth, cchar *users)

Define the set of permitted users.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  users | Space separated list of acceptable users.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

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:

  auth | Auth object allocated by httpCreateAuth
  qop | Quality of service description.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

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:

  auth | Auth object allocated by httpCreateAuth
  realm | Authentication realm.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

void httpSetAuthRequiredAbilities (HttpAuth *auth, cchar *abilities)

Set the required abilities for access.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  abilities | Spaces separated list of all the required abilities.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthStore, httpSetAuthType

int httpSetAuthStore (HttpAuth *auth, cchar *store)

Set the authentication password store to use.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  store | Password store to use. Select from: 'system', 'file'.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthType

int httpSetAuthType (HttpAuth *auth, cchar *proto, cchar *details)

Set the authentication protocol to use.

Parameters:

  auth | Auth object allocated by httpCreateAuth
  proto | Protocol name to use. Select from: 'basic', 'digest', 'form'.
  details | Extra protocol details.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore

# HttpCache

HttpCache

Cache Control.

See Also:
  httpAddCache, httpUpdateCache

API Stability:
  Internal.

Fields:

  MprTicks |  | clientLifespan | Lifespan for client cached content.
  MprHash * |  | extensions | Extensions to cache.
  int |  | flags | Cache control flags.
  MprHash * |  | methods | Methods to cache.
  MprTicks |  | serverLifespan | 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:

  route | HttpRoute object.
  methods | List 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".
  uris | Set 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}.
  extensions | List 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".
  types | List 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".
  clientLifespan | Lifespan of client cache items in milliseconds. If not set to positive integer, the lifespan will default to the route lifespan.
  serverLifespan | Lifespan of server cache items in milliseconds. If not set to positive integer, the lifespan will default to the route lifespan.

  flags

  Cache 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_ALL, HTTP_CACHE_ONLY or HTTP_CACHE_UNIQUE to define the server-side caching mode. Only one of these three mode flags should be specified.
  If the HTTP_CACHE_ALL flag is set, the request params (query, post data, and route parameters) will be ignored and all requests for a given URI path will cache to the same cache record.
  Select HTTP_CACHE_UNIQUE to uniquely cache requests with different request parameters. The URIs specified in uris should not contain any request parameters.
  Select HTTP_CACHE_ONLY to cache only the exact URI with parameters specified in uris. The parameters must be in sorted www-urlencoded format. For example: /example.esp?hobby=sailing&name=john.

Returns:
  A count of the bytes actually written.

API Stability:
  Evolving.

See Also:
  HttpCache, httpUpdateCache

ssize httpUpdateCache (HttpConn *conn, cchar *uri, cchar *data, MprTicks lifespan)

Update the cached content for a URI.

Parameters:

  conn | HttpConn connection object.
  uri | The request URI for which to update the cache. If using the HTTP_CACHE_ONLY flag when configuring the cached item, then the URI should contain the request parameters in sorted www-urlencoded format.
  data | Data 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. For example: "Content-Type: text/plain\n\nHello World\n".
  lifespan | Lifespan in milliseconds for the cached content.

API Stability:
  Evolving.

See Also:
  HttpCache, httpAddCache

ssize httpWriteCached (HttpConn *conn)

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:

  conn | HttpConn connection object.

API Stability:
  Evolving.

See Also:
  HttpCache, httpAddCache, httpUpdateCache

# HttpConn

HttpConn

Http Connections.

Description:
  The HttpConn object represents a TCP/IP connection to the client. A connection object is created for each socket connection initiated by the client. One HttpConn object may service many Http requests due to HTTP/1.1 keep-alive.

See Also:
  HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

API Stability:
  Internal.

Description:
  The Action Handler provides a simple mechanism to bind "C" callback functions with URIs.

API Stability:
  Evolving.

Fields:

  int |  | async | Connection is in async mode (non-blocking).
  void * |  | authData | Authorization state data.
  int |  | authRequested | 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.
  HttpQueue * |  | connectorq | Connector write queue.
  int |  | connError | A connection error has occurred.
  void * |  | context | Embedding context (EjsRequest).
  struct HttpQueue * |  | currentq | Current queue being serviced (just for GC).
  void * |  | data | Custom data for request - must be a managed reference.
  MprDispatcher * |  | dispatcher | Event dispatcher.
  void * |  | ejs | Embedding VM.
  int |  | encoded | True if the password is MD5(username:realm:password).
  struct HttpEndpoint * |  | endpoint | Endpoint object (if set - indicates server-side).
  int |  | error | A request error has occurred.
  char * |  | errorMsg | Error message for the last request (if any).
  int |  | followRedirects | Follow redirects for client requests.
  void * |  | grid | Current request database grid for MVC apps.
  HttpHeadersCallback |  | headersCallback | Callback to fill headers.
  void * |  | headersCallbackArg | Arg to fillHeaders.
  struct HttpHost * |  | host | Host object (if relevant).
  Http * |  | http | Http service object.
  int |  | http10 | Using legacy HTTP/1.0.
  HttpPacket * |  | input | Header packet.
  HttpIOCallback |  | ioCallback | I/O event callback.
  char * |  | ip | Remote client IP address.
  int |  | keepAliveCount | Count of remaining Keep-Alive requests for this connection.
  MprTicks |  | lastActivity | Last activity on the connection.
  HttpLimits * |  | limits | Service limits.
  void * |  | mark | Reference for GC marking.
  ssize |  | newData | Length of new data last read into the input packet.
  MprDispatcher * |  | newDispatcher | New dispatcher if using a worker thread.
  HttpNotifier |  | notifier | Connection Http state change notification callback.
  MprDispatcher * |  | oldDispatcher | Original dispatcher if using a worker thread.
  char * |  | password | Supplied password (may be encrypted depending on auth protocol).
  void * |  | pool | Pool of VMs.
  int |  | port | Remote port.
  char * |  | protocol | HTTP protocol.
  char * |  | protocols | Supported web socket protocols (clients).
  int |  | pumping | Rre-entrancy prevention for httpPumpRequest()
  HttpQueue * |  | readq | End of the read pipeline.
  void * |  | record | Current request database record for MVC apps.
  int |  | retries | Client request retries.
  struct HttpRx * |  | rx | Rx object.
  int |  | secure | Using https.
  int |  | seqno | Unique connection sequence number.
  struct HttpQueue * |  | serviceq | List of queues that require service for request pipeline.
  MprSocket * |  | sock | Underlying socket handle.
  MprTicks |  | started | When the connection started (ticks).
  uint64 |  | startMark | High resolution tick time of request.
  int |  | state | Connection state.
  void * |  | staticData | Custom data for request - must be an - unmanaged reference.
  HttpTimeoutCallback |  | timeoutCallback | Request and inactivity timeout callback.
  MprEvent * |  | timeoutEvent | Connection or request timeout event.
  HttpTrace |  | trace[2] | Tracing for [rx|tx].
  struct HttpTx * |  | tx | Tx object.
  int |  | upgraded | Request protocol upgraded.
  struct HttpUser * |  | user | Authorized User record for access checking.
  char * |  | username | Supplied user name.
  int |  | worker | Use worker.
  MprEvent * |  | workerEvent | Event for running connection via a worker thread.
  HttpQueue * |  | writeq | Start of the write pipeline.

void httpAfterEvent (HttpConn *conn)

Do setup after an I/O event to receive future events.

Parameters:

  conn | HttpConn object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpCallEvent (HttpConn *conn, int mask)

Call httpEvent with the given event mask.

Parameters:

  conn | HttpConn object created via httpCreateConn
  mask | Mask of events. MPR_READABLE | MPR_WRITABLE.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpCloseConn (HttpConn *conn)

Close a connection.

Parameters:

  conn | HttpConn object created via httpCreateConn

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpConnTimeout (HttpConn *conn)

Signal a connection timeout on a connection.

Description:
  This call cancels a connections 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. This call should not be made on another thread, but should be scheduled to run on the connection's dispatcher to avoid thread races.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

HttpConn * httpCreateConn (Http *http, struct HttpEndpoint *endpoint, MprDispatcher *dispatcher)

Create a connection object.

Description:
  Most interactions with the Http library are via a connection object. It is used for server-side communications when responding to client requests and it is used to initiate outbound client requests.

Parameters:

  http | Http object created via httpCreate
  endpoint | Endpoint object owning the connection.
  dispatcher | Disptacher to use for I/O events on the connection.

Returns:
  A new connection object.

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpCreateRxPipeline (HttpConn *conn, struct HttpRoute *route)

Create the receive request pipeline.

Parameters:

  conn | HttpConn object created via httpCreateConn
  route | Route object controlling how the pipeline is configured for the request.

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpCreateTxPipeline (HttpConn *conn, struct HttpRoute *route)

Create the transmit request pipeline.

Parameters:

  conn | HttpConn object created via httpCreateConn
  route | Route object controlling how the pipeline is configured for the request.

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpDestroyConn (HttpConn *conn)

Destroy the connection object.

Parameters:

  conn | HttpConn object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpDestroyPipeline (HttpConn *conn)

Destroy the request pipeline.

Description:
  This is called at the conclusion of a request.

Parameters:

  conn | HttpConn object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpDiscardData (HttpConn *conn, int dir)

Discard buffered transmit pipeline data.

Parameters:

  conn | HttpConn object created via httpCreateConn
  dir | Queue direction. Either HTTP_QUEUE_TX or HTTP_QUEUE_RX.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpDisconnect (HttpConn *conn)

Disconnect the connection's socket.

Description:
  This call will close the socket and signal a connection error. Subsequent use of the connection socket will not be possible. This call should not be made on another thread, but should be scheduled to run on the connection's dispatcher to avoid thread races.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpEnableConnEvents (HttpConn *conn)

Enable connection events.

Description:
  Connection events are automatically disabled upon receipt of an I/O event on a connection. This permits a connection 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 connection should be re-enabled via httpEnableConnEvents. This call is made for requests in httpEvent

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpEnableUpload (HttpConn *conn)

Enable Multipart-Mime File Upload for this request.

This will define a "Content-Type: multipart/form-data..." header and will create a mime content boundary for use to delimit the various upload content files and fields

Parameters:

  conn | HttpConn connection object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpError (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  status | Http 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.
  fmt | Printf style formatted string.
  ... | Arguments for fmt.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpEvent (struct HttpConn *conn, MprEvent *event)

Http I/O event handler.

Invoke when there is an I/O event on the connection. This is normally invoked automatically when I/O events are received

Parameters:

  conn | HttpConn object created via httpCreateConn
  event | Event structure.

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpFinalizeConnector (HttpConn *conn)

Finalize connector output sending the response.

Parameters:

  conn | HttpConn object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

int httpGetAsync (HttpConn *conn)

Get the async mode value for the connection.

Parameters:

  conn | HttpConn object created via httpCreateConn

Returns:
  True if the connection is in async mode.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

ssize httpGetChunkSize (HttpConn *conn)

Get the preferred chunked size for transfer chunk encoding.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  Chunk size. Returns "zero" if not yet defined.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void * httpGetConnContext (HttpConn *conn)

Get the connection context object.

Parameters:

  conn | HttpConn object created via httpCreateConn

Returns:
  The connection context object defined via httpSetConnContext.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void * httpGetConnHost (HttpConn *conn)

Get the connection host object.

Parameters:

  conn | HttpConn object created via httpCreateConn

Returns:
  The connection host object defined via httpSetConnHost.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

cchar * httpGetError (HttpConn *conn)

Get the error message associated with the last request.

Description:
  Error messages may be generated for internal or client side errors.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  A error string. The caller must not free this reference.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

char * httpGetExt (HttpConn *conn)

Get a URI extension.

Description:
  If the URI has no extension and the response content filename (HttpTx.filename) has been calculated, it will be tested for an extension.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  The URI extension without the leading period.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

int httpGetKeepAliveCount (HttpConn *conn)

Get the count of Keep-Alive requests that will be used for this connection 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:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  The maximum count of Keep-Alive requests.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

bool httpGetMoreOutput (HttpConn *conn)

Get more output data by invoking the writable callback.

Description:
  This optional handler callback is invoked when the service queue has room for more data.

Parameters:

  conn | HttpConn object created via httpCreateConn

Returns:
  True if the handler writable callback exists and can be invoked.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

ssize httpGetWriteQueueCount (HttpConn *conn)

Get the count of bytes buffered on the write queue.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  The number of bytes buffered.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpMatchHost (HttpConn *conn)

Match the HttpHost object that should serve this request.

Description:
  This sets the conn->host field to the appropriate host. If no suitable host can be found, httpError will be called and conn->error will be set.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpMemoryError (HttpConn *conn)

Signal a memory allocation error.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpNotify (HttpConn *conn, int event, int arg)

Inform notifiers of a connection event or state change.

Description:
  This is an internal API and should not be called by handler or user code.

Parameters:

  conn | HttpConn object created via httpCreateConn
  event | Event to issue.
  arg | Argument to event.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpPrepClientConn (HttpConn *conn, bool keepHeaders)

Prepare a client connection for a new request.

Parameters:

  conn | HttpConn object created via httpCreateConn
  keepHeaders | If true, keep the headers already defined on the connection object.

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpReadyHandler (HttpConn *conn)

Run the handler ready callback.

Description:
  This will be called when all incoming data for the request has been fully received.

Parameters:

  conn | HttpConn object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpResetCredentials (HttpConn *conn)

Reset the current security credentials.

Description:
  Remove any existing security credentials.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpRouteRequest (HttpConn *conn)

Route the request and select that matching route and handle to process the request.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

bool httpServiceQueues (HttpConn *conn)

Service pipeline queues to flow data.

Parameters:

  conn | HttpConn object created via httpCreateConn

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetAsync (HttpConn *conn, int enable)

Set the async mode value for the connection.

Parameters:

  conn | HttpConn object created via httpCreateConn
  enable | Set to 1 to enable async mode.

Returns:
  True if the connection is in async mode.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetChunkSize (HttpConn *conn, ssize size)

Set the chunk size for transfer chunked encoding.

When set, a "Transfer-Encoding: Chunked" header will be added to the request, and all write data will be broken into chunks of the requested size

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  size | Requested chunk size.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetConnContext (HttpConn *conn, void *context)

Set the connection context object.

Parameters:

  conn | HttpConn object created via httpCreateConn
  context | New context object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetConnHost (HttpConn *conn, void *host)

Set the connection host object.

Parameters:

  conn | HttpConn object created via httpCreateConn
  host | New context host.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetConnNotifier (HttpConn *conn, 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 supported events are:
  - HTTP_EVENT_STATE <mdash/> 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 <mdash/> There is data available to read
  - HTTP_EVENT_WRITABLE <mdash/> The outgoing pipeline can absorb more data
  - HTTP_EVENT_ERROR <mdash/> The request has encountered an error
  - HTTP_EVENT_DESTROY <mdash/> The connection structure is about to be destoyed
  - HTTP_EVENT_OPEN <mdash/> The application layer is now open
  - HTTP_EVENT_CLOSE <mdash/> The application layer is now closed

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  notifier | Notifier function.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetContext (Http *http, void *context)

Set the http context object.

Parameters:

  http | Http object created via httpCreate
  context | New context object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetCredentials (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  user | String user.
  password | Decrypted password string.
  authType | Authentication type. Set to basic or digest. Defaults to nothing.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetDefaultClientHost (Http *http, 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:

  http | Http object created via httpCreateConn
  host | Host or IP address.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetDefaultClientPort (Http *http, 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:

  http | Http object created via httpCreateConn
  port | Integer port number.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetForkCallback (struct Http *http, MprForkCallback proc, void *arg)

Set the fork callback.

Parameters:

  http | Http service object.
  proc | Fork callback procedure.
  arg | Argument to supply when the callback is invoked.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetHeadersCallback (struct HttpConn *conn, HttpHeadersCallback fn, void *arg)

Define a headers callback.

Description:
  The headers callback will run before the standard response headers are generated. This gives an opportunity to pre-populate the response headers.

Parameters:

  conn | HttpConn object created via httpCreateConn
  fn | Callback function to invoke.
  arg | Argument to provide when invoking the headers callback.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetIOCallback (struct HttpConn *conn, HttpIOCallback fn)

Define an I/O callback for connections.

Description:
  The I/O callback is invoked when I/O events are detected on the connection. The default I/O callback is httpEvent

Parameters:

  conn | HttpConn object created via httpCreateConn
  fn | Callback function to invoke.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetKeepAliveCount (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  count | Count of Keep-Alive transactions to use before closing the connection. Set to zero to disable keep-alive.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetProtocol (HttpConn *conn, cchar *protocol)

Set the Http protocol variant for this connection.

Description:
  Set the Http protocol variant to use.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  protocol | String representing the protocol variant. Valid values are: "HTTP/1.0", "HTTP/1.1". This parameter must be persistent. Use HTTP/1.1 wherever possible.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetRetries (HttpConn *conn, int retries)

Set the Http retry count.

Description:
  Define the number of retries before failing a request. It is normative for network errors to require that requests be sometimes retried. The default retries is set to (2).

Parameters:

  conn | HttpConn object created via httpCreateConn
  retries | Count of retries.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetSendConnector (HttpConn *conn, cchar *path)

Set the "Send" connector to process the request.

Description:
  If the net connection has been selected, but the response content is a file, the pipeline connector can be upgraded to use the "Send" connector.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  path | File name to send as a response.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetState (HttpConn *conn, 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:

  conn | HttpConn object created via httpCreateConn
  state | New state to enter.

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetTimeout (HttpConn *conn, MprTicks requestTimeout, MprTicks inactivityTimeout)

Set the Http inactivity timeout.

Description:
  Define an inactivity timeout after which the Http connection will be closed.

Parameters:

  conn | HttpConn object created via httpCreateConn
  requestTimeout | Request timeout in msec. This is the total time for the request. Set to -1 to preserve the existing value.
  inactivityTimeout | Inactivity timeout in msec. This is maximum connection idle time. Set to -1 to preserve the existing value.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimestamp, httpShouldTrace, httpStartPipeline

void httpSetTimestamp (MprTicks period)

Define a timestamp in the MPR log file.

Description:
  This routine initiates the writing of a timestamp in the MPR log file.

Parameters:

  period | Time in milliseconds between timestamps.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpShouldTrace, httpStartPipeline

void httpSetupWaitHandler (HttpConn *conn, int eventMask)

Setup a wait handler for the connection to wait for desired events.

Parameters:

  conn | HttpConn object created via httpCreateConn
  eventMask | Mask of events. MPR_READABLE | MPR_WRITABLE.

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

int httpShouldTrace (HttpConn *conn, int dir, int item, cchar *ext)

Test if the item should be traced.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  dir | Direction of data flow. Set to HTTP_TRACE_RX or HTTP_TRACE_TX.
  item | Item to trace. Set to HTTP_TRACE_CONN, HTTP_TRACE_FIRST, HTTP_TRACE_HEADER, HTTP_TRACE_BODY, or HTTP_TRACE_TIME.
  ext | URI resource extension (without ".").

Returns:
  The level at which tracing should be done. Returns -1 if tracing should not be done for this item.

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpStartPipeline

void httpStartPipeline (HttpConn *conn)

Start the pipeline.

This starts the request handler

Parameters:

  conn | HttpConn object created via httpCreateConn

API Stability:
  Internal.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace

MprSocket * httpStealConn (HttpConn *conn)

Steal a connection from Appweb.

Description:
  Steal a connection from Appweb and assume total responsibility for the connection. This removes the connection from active management by Appweb. After calling, request and inactivity timeouts will not be enforced. It is the callers responsibility to call mprCloseSocket.

Parameters:

  conn | HttpConn object created via httpCreateConn

Returns:
  The connection socket object.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

bool httpVerifyWebSocketsHandshake (HttpConn *conn)

Verify the server handshake.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  True if the handshake is valid.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

ssize httpWriteUploadData (HttpConn *conn, 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 even if a callback is defined.

Parameters:

  conn | Http connection object created via httpCreateConn
  fileData | List of string file names to upload.
  formData | List 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:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

# HttpEndpoint

HttpEndpoint

Listening endpoints.

See Also:
  httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

API Stability:
  Internal.

Fields:

  int |  | activeClients | Count of current active clients.
  int |  | activeRequests | Count of current active requests.
  int |  | async | Listening is in async mode (non-blocking).
  MprHash * |  | clientLoad | Table of active client IPs and connection counts.
  void * |  | context | Embedding context.
  MprDispatcher * |  | dispatcher | Event dispatcher.
  int |  | flags | 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.
  MprMutex * |  | mutex | Multithread sync.
  HttpNotifier |  | notifier | Default connection notifier callback.
  int |  | port | Listen port.
  MprSocket * |  | sock | Listening socket.
  struct MprSsl * |  | ssl | Endpoint SSL configuration.

HttpConn * httpAcceptConn (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:

  endpoint | The endpoint on which the server was listening.
  event | Mpr event object.

Returns:
  A HttpConn object representing the new connection.

API Stability:
  Internal.

See Also:
  HttpEndpoint, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

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:

  endpoint | Endpoint to which the host will be added.
  host | HttpHost object to add.

Returns:
  "Zero" if the host can be added.

API Stability:
  Internal.

See Also:
  HttpEndpoint, httpAcceptConn, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

int httpConfigureNamedVirtualEndpoints (Http *http, cchar *ip, int port)

Configure endpoints with named virtual hosts.

Parameters:

  http | Http service object.
  ip | IP address for the named virtual host.
  port | address for the named virtual host.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

HttpEndpoint * httpCreateConfiguredEndpoint (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. An endpoint is created with a default host and default route.

Parameters:

  home | Home directory for configuration files for the endpoint.
  documents | Directory containing the.
  ip | IP address to use for the endpoint. Set to null to listen on all interfaces.
  port | Listening port number to use for the endpoint.

Returns:
  A configured HttpEndpoint object instance.

API Stability:
  Internal.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

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:

  ip | IP address on which to listen.
  port | IP port number.
  dispatcher | Dispatcher to use. Can be null.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

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:

  endpoint | HttpEndpoint object returned from httpCreateEndpoint

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

void * httpGetEndpointContext (HttpEndpoint *endpoint)

Get the endpoint context object.

Parameters:

  endpoint | HttpEndpoint object created via httpCreateEndpoint

Returns:
  The endpoint context object defined via httpSetEndpointContext.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

bool httpHasNamedVirtualHosts (HttpEndpoint *endpoint)

Test if an endpoint has named virtual hosts.

Parameters:

  endpoint | Endpoint object to examine.

Returns:
  True if the endpoint has named virutal hosts.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

int httpIsEndpointAsync (HttpEndpoint *endpoint)

Get if the endpoint is running in asynchronous mode.

Parameters:

  endpoint | HttpEndpoint object created via httpCreateEndpoint

Returns:
  True if the endpoint is in async mode.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

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:

  endpoint | HttpEndpoint object created via httpCreateEndpoint
  name | Host name to search for.

Returns:
  An HttpHost object instance or null if the host cannot be found.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

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:

  endpoint | HttpEndpoint object created via httpCreateEndpoint
  ssl | MprSsl object.

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

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:

  name | Endpoint name. The endpoint name is comprised of the IP and port. For example: "127.0.0.1:7777".
  ssl | MprSsl object.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

void 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:

  endpoint | HttpEndpoint object created via httpCreateEndpoint
  ip | IP address to use for the endpoint. Set to null to listen on all interfaces.
  port | Listening port number to use for the endpoint.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

void httpSetEndpointAsync (HttpEndpoint *endpoint, int enable)

Control if the endpoint is running in asynchronous mode.

Parameters:

  endpoint | HttpEndpoint object created via httpCreateEndpoint
  enable | Set to 1 to enable async mode.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

void httpSetEndpointContext (HttpEndpoint *endpoint, void *context)

Set the endpoint context object.

Parameters:

  endpoint | HttpEndpoint object created via httpCreateEndpoint
  context | New context object.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

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:

  endpoint | HttpEndpoint object created via httpCreateEndpoint
  fn | Notifier function.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

void httpSetHasNamedVirtualHosts (HttpEndpoint *endpoint, bool on)

Control whether the endpoint has named virtual hosts.

Parameters:

  endpoint | Endpoint object to examine.
  on | Set to true to enable named virtual hosts.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpStartEndpoint, httpStopEndpoint, httpValidateLimits

int httpStartEndpoint (HttpEndpoint *endpoint)

Start listening for client connections.

Description:
  Opens the endpoint socket and starts listening for connections.

Parameters:

  endpoint | HttpEndpoint object created via httpCreateEndpoint

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStopEndpoint, httpValidateLimits

void httpStopEndpoint (HttpEndpoint *endpoint)

Stop the server listening for client connections.

Description:
  Closes the socket endpoint.

Parameters:

  endpoint | HttpEndpoint object created via httpCreateEndpoint

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpValidateLimits

bool httpValidateLimits (HttpEndpoint *endpoint, int event, HttpConn *conn)

Validate the request against defined resource limits.

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:

  endpoint | The endpoint on which the server was listening.
  event | Processing event. The supported events are: HTTP_VALIDATE_OPEN_CONN, HTTP_VALIDATE_CLOSE_CONN, HTTP_VALIDATE_OPEN_REQUEST and HTTP_VALIDATE_CLOSE_REQUEST.
  conn | HttpConn connection object.

Returns:
  True if the request can be successfully validated against the endpoint limits.

API Stability:
  Stable.

See Also:
  HttpEndpoint, httpAcceptConn, httpAddHostToEndpoint, httpCreateConfiguredEndpoint, httpCreateEndpoint, httpDestroyEndpoint, httpGetEndpointContext, httpHasNamedVirtualHosts, httpIsEndpointAsync, httpLookupHostOnEndpoint, httpSecureEndpoint, httpSecureEndpointByName, httpSetEndpointAddress, httpSetEndpointAsync, httpSetEndpointContext, httpSetEndpointNotifier, httpSetHasNamedVirtualHosts, httpStartEndpoint, httpStopEndpoint

# 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, httpSetHostIpAddr, httpSetHostName, httpSetHostProtocol

API Stability:
  Internal.

Fields:

  HttpEndpoint * |  | defaultEndpoint | Default endpoint for host.
  HttpRoute * |  | defaultRoute | Default route for the host.
  int |  | flags | Host flags.
  char * |  | ip | Hostname/ip portion parsed from name.
  MprMutex * |  | mutex | Multithread sync.
  char * |  | name | Host name.
  struct HttpHost * |  | parent | Parent host to inherit aliases, dirs, routes.
  int |  | port | Port address portion parsed from name.
  char * |  | protocol | Defaults to "HTTP/1.1".
  MprCache * |  | responseCache | Response content caching store.
  char * |  | root | Home for this host.
  MprList * |  | routes | List of Route defintions.
  HttpEndpoint * |  | secureEndpoint | Secure endpoint for host.

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:

  host | HttpHost object.
  route | Route to add.

Returns:
  "Zero" if the route can be added.

API Stability:
  Stable.

See Also:
  HttpHost, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, 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:

  parent | Parent HttpHost object to clone.

Returns:
  The new HttpHost object.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, httpSetHostName, httpSetHostProtocol

HttpHost * httpCreateHost ()

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, httpSetHostIpAddr, httpSetHostName, httpSetHostProtocol

HttpHost * httpGetDefaultHost ()

Get the default host defined via httpSetDefaultHost.

Returns:
  The defaul thost object.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, httpSetHostName, httpSetHostProtocol

void httpResetRoutes (HttpHost *host)

Reset the list of routes for the host.

Parameters:

  host | HttpHost object.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpSetHostIpAddr, httpSetHostName, httpSetHostProtocol

void httpSetDefaultHost (HttpHost *host)

Set the default host for all servers.

Parameters:

  host | Host to define as the default host.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, 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:

  host | Host to examine.
  endpoint | Secure endpoint to use as the default.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, 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:

  host | Host to examine.
  route | Route to define as the default.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, httpSetHostName, httpSetHostProtocol

void httpSetHostIpAddr (HttpHost *host, cchar *ip, int port)

Set the host internet address.

Description:
  Set the host IP and port address.

Parameters:

  host | HttpHost object.
  ip | Internet address. This can be an IP address or a symbolic domain and host name.
  port | Port number.

Returns:
  "Zero" if the route can be added.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostName, httpSetHostProtocol

void httpSetHostName (HttpHost *host, cchar *name)

Set the host name.

Description:
  The host name is used when matching virtual hosts with the Http Host header. The host name is also used for some redirections. in order, so it is important to define routes in the order in which you wish to match them.

Parameters:

  host | HttpHost object.
  name | Host name to use.

Returns:
  Zero if the route can be added.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, 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:

  host | HttpHost object.
  protocol | Set to either HTTP/1.0 or HTTP/1.1.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, 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:

  host | HttpHost object.
  root | Directory path for the host server root.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, 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:

  host | Host to examine.
  endpoint | Secure endpoint to use as the default.

API Stability:
  Stable.

See Also:
  HttpHost, httpAddRoute, httpCloneHost, httpCreateHost, httpResetRoutes, httpSetHostIpAddr, httpSetHostName, httpSetHostProtocol

# HttpLimits

HttpLimits

Http limits.

See Also:
  httpCreateLimits, httpEaseLimits, httpInitLimits

API Stability:
  Internal.

Fields:

  ssize |  | bufferSize | Maximum buffering by any pipeline stage.
  ssize |  | cacheItemSize | Maximum size of a cachable item.
  ssize |  | chunkSize | Maximum chunk size for transfer encoding.
  int |  | clientMax | Maximum number of simultaneous clients endpoints.
  int |  | headerMax | Maximum number of header lines.
  ssize |  | headerSize | Maximum size of the total header.
  MprTicks |  | inactivityTimeout | Timeout for keep-alive and idle requests (msec).
  int |  | keepAliveMax | Maximum number of Keep-Alive requests to perform per socket.
  int |  | processMax | Maximum number of processes (CGI).
  MprOff |  | receiveBodySize | Maximum size of receive body data.
  MprOff |  | receiveFormSize | Maximum size of form data.
  int |  | requestMax | Maximum number of simultaneous concurrent requests.
  MprTicks |  | requestParseTimeout | Time a request can take to parse the request headers (msec).
  int |  | requestsPerClientMax | Maximum number of requests per client IP.
  MprTicks |  | requestTimeout | Time a request can take (msec).
  int |  | sessionMax | Maximum number of sessions.
  MprTicks |  | sessionTimeout | Time a session can persist (msec).
  MprOff |  | transmissionBodySize | Maximum size of transmission body content.
  MprOff |  | uploadSize | Maximum size of an uploaded file.
  ssize |  | uriSize | Maximum size of a uri.
  ssize |  | webSocketsFrameSize | Maximum size of a WebSocket frame on the wire.
  int |  | webSocketsMax | Maximum number of WebSockets.
  ssize |  | webSocketsMessageSize | Maximum total size of a WebSocket message including all frames.
  ssize |  | webSocketsPacketSize | Maximum size of a WebSocket packet exchanged with the user.
  MprTicks |  | webSocketsPing | Time between pings.

HttpLimits * httpCreateLimits (int serverSide)

Create a new limits object.

Description:
  Create and initialize a new limits object with default values.

Parameters:

  serverSide | Set to "true" for server side limits. Set to "false" for client side default limits.

Returns:
  The allocated limits object.

API Stability:
  Evolving.

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.

Parameters:

  limits | Limits object. This can be either HttpHost.limits HttpConn.limits or HttpEndpoint.limits.

API Stability:
  Evolving.

See Also:
  HttpLimits, httpCreateLimits, httpInitLimits

void httpEnablePutMethod (HttpRoute *route, bool on)

Enable use of the DELETE and PUT methods.

Parameters:

  route | Route to modify.
  on | Set to true to enable the DELETE and PUT Http methods.

API Stability:
  Evolving.

See Also:
  HttpLimits, httpCreateLimits, httpEaseLimits, httpInitLimits

void httpEnableTraceMethod (HttpRoute *route, bool on)

Enable use of the TRACE Http method.

Parameters:

  route | Route to modify.
  on | Set to true to enable the trace method.

API Stability:
  Evolving.

See Also:
  HttpLimits, httpCreateLimits, httpEaseLimits, httpInitLimits

void httpInitLimits (HttpLimits *limits, bool serverSide)

Initialize a limits object with default values.

Parameters:

  limits | Limits object to modify.
  serverSide | Set to "true" for server side limits. Set to "false" for client side default limits.

API Stability:
  Evolving.

See Also:
  HttpLimits, httpCreateLimits, httpEaseLimits

# 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.
  MprOff |  | epos | Data position in entity (file).
  MprOff |  | esize | Data size in entity (file).
  HttpFillProc |  | fill | Callback to fill packet with data.
  uint |  | flags | Packet flags.
  uint |  | last | Last packet in a message.
  struct HttpPacket * |  | next | Next packet in chain.
  MprBuf * |  | prefix | Prefix message to be emitted before the content.
  uint |  | type | 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:

  packet | Packet to modify.
  size | Size 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:

  packet | Packet to modify.
  size | Size 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)

Clone a packet.

Parameters:

  orig | Original packet to clone.

Returns:
  A new packet equivalent to the original.

API Stability:
  Stable.

See Also:
  HttpFillProc, HttpPacket, HttpQueue, httpAdjustPacketEnd, httpAdjustPacketStart, httpCreateDataPacket, httpCreateEndPacket, httpCreateEntityPacket, httpCreateHeaderPacket, httpCreatePacket, httpGetPacket, httpGetPacketLength, httpIsLastPacket, httpJoinPacket, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpSplitPacket

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:

  size | Size 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 ()

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:

  pos | Position within the entity for packet data.
  size | Size of the entity data.
  fill | HttpFillProc 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 ()

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:

  size | Size 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 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 <ndash/> just the pure buffered data contents.

Parameters:

  packet | Packet 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

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:

  packet | Packet 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:

  packet | Destination packet.
  other | Other 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.

Parameters:

  packet | Packet to split.
  offset | Route in the original packet at which to split.

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:
  HttpConn, HttpPacket, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

API Stability:
  Internal.

Fields:

  HttpQueueClose |  | close | Close the queue.
  struct HttpConn * |  | conn | Connection owning this queue.
  ssize |  | count | Bytes in queue (Does not include virt packet data).
  int |  | direction | Flow direction.
  HttpPacket * |  | first | First packet in queue (singly linked).
  int |  | flags | Queue flags.
  MprOff |  | ioCount | Count of bytes in iovec including file I/O.
  int |  | ioFile | Sending a file.
  int |  | ioIndex | Next index into iovec.
  MprOff |  | ioPos | Position in file for sendfile.
  HttpPacket * |  | last | Last packet in queue (tail pointer).
  ssize |  | low | Low water mark for flow control.
  ssize |  | max | Advisory maxiumum queue size.
  cchar * |  | name | Queue name for debugging.
  struct HttpQueue * |  | nextQ | Downstream queue for next stage.
  HttpQueueOpen |  | open | Open the queue.
  ssize |  | packetSize | Maximum acceptable packet size.
  struct HttpQueue * |  | pair | Queue for the same stage in the opposite direction.
  struct HttpQueue * |  | prevQ | Upstream queue for prior stage.
  HttpQueueData |  | put | 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.
  HttpQueueService |  | service | Service the queue.
  int |  | servicing | Currently being serviced.
  struct HttpStage * |  | stage | Stage owning this queue.
  HttpQueueStart |  | start | Start the queue.
  void * |  | staticData | Stage instance data - must be an unmanaged reference.

void httpDisableQueue (HttpQueue *q)

Disable a queue.

Description:
  Disable a queue so that it will not be scheduled for service. The queue will remain disabled until httpEnableQueue is called.

Parameters:

  q | Queue reference.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

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:

  q | Queue reference.
  removePackets | If "true", the data packets will be removed from the queue.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

void httpEnableQueue (HttpQueue *q)

Enable a queue after it has been disabled.

Description:
  Enable a queue for service and schedule it to run. This will cause the service routine to run as soon as possible.

Parameters:

  q | Queue reference.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

bool httpFlushQueue (HttpQueue *q, bool block)

Flush queue data.

Description:
  This initiates writing buffered queue data (flushes) by scheduling the queue and servicing all scheduled queues. If blocking is requested, the call will block until the queue count falls below the queue maximum. WARNING: Be very careful when using blocking == true. Should only be used by end applications and not by middleware.

Parameters:

  q | Queue to flush.
  block | If set to "true", this call will block until the data has drained below the queue maximum.

Returns:
  "True" if there is room for more data in the queue after flushing.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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:

  q | Queue reference.

Returns:
  The packet removed from the queue.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

ssize httpGetQueueRoom (HttpQueue *q)

Get the room in the queue.

Description:
  Get the amount of data the queue can accept before being full.

Parameters:

  q | Queue reference.

Returns:
  A count of bytes that can be written to the queue.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

bool httpIsEof (struct HttpConn *conn)

Test if the connection has received all incoming content.

Description:
  This tests if the connection is at an "End of File condition.

Parameters:

  conn | HttpConn object created via httpCreateConn

Returns:
  "True" if all Receive content has been received.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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 <ndash/> then this routine will return "true".

Parameters:

  q | Queue reference.
  packet | Packet to test.

Returns:
  "True" if the packet is too big for the downstream queue.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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:

  q | Queue reference.

Returns:
  "True" if there are no packets queued.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

bool httpIsQueueSuspended (HttpQueue *q)

Test if a queue is suspended.

Parameters:

  q | Queue reference.

Returns:
  True if the queue is suspended.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

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:

  q | Queue reference.
  packet | Packet to join to the queue.
  serviceQ | If true, schedule the queue for service.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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:

  q | Queue to examine.
  size | The 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:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

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:

  q | Queue reference.
  packet | Packet to put back.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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:

  q | Queue reference.
  packet | Packet to join to the queue.
  serviceQ | If true, schedule the queue for service.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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:

  q | Queue reference.
  packet | Packet to put.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

void httpPutPacketToNext (struct HttpQueue *q, 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:

  q | Queue reference.
  q | Queue reference. The packet will not be queued on this queue, but rather on the queue downstream.
  packet | Packet to put.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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:

  q | Queue reference.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

int 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:

  q | Queue reference.
  packet | Packet to put.
  size | If size is > 0, then also ensure the packet is not larger than this size.

Returns:
  "Zero" if successful, otherwise a negative Mpr error code.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

void httpResumeQueue (HttpQueue *q)

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:

  q | Queue reference.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

void httpScheduleQueue (HttpQueue *q)

Schedule a queue.

Description:
  Schedule a queue by adding it to the schedule queue. Queues are serviced FIFO.

Parameters:

  q | Queue reference.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

void httpServiceQueue (HttpQueue *q)

Service a queue.

Description:
  Service a queue by invoking its service() routine.

Parameters:

  q | Queue reference.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

void httpSetQueueLimits (HttpQueue *q, ssize low, ssize max)

Set a queue's flow control low and high water marks.

Parameters:

  q | Queue reference.
  low | The low water mark. Typically 5% of the max.
  max | The high water mark.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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:

  q | Queue reference.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteBlock, httpWriteString

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:

  q | Queue reference.
  packet | Packet to put.

Returns:
  "True" if the downstream queue will accept the packet. Use httpPutPacketToNext to send the packet downstream.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptSize, 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:

  q | Queue reference.
  size | Size of data to test for.

Returns:
  "True" if the downstream queue will accept the given sized data.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWrite, httpWriteBlock, httpWriteString

bool httpWillQueueAcceptPacket (HttpQueue *q, HttpPacket *packet, bool split)

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:

  q | Queue reference.
  packet | Packet to put.
  split | Set to true to split the packet if required to fit into the queue.

Returns:
  "True" if the queue will accept the packet.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, 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.

Parameters:

  q | Queue reference.
  fmt | Printf style formatted string.
  ... | Arguments for fmt.

Returns:
  A count of the bytes actually written.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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 an 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 block for up to the inactivity timeout specified in the conn->limits->inactivityTimeout value. 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. Data written after httpFinalize, httpFinalizeOutput or httpError is called will be ignored.

Parameters:

  q | Queue reference.
  buf | Buffer containing the write data.
  size | of the data in buf.
  flags | Set 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.

Returns:
  The size value if successful or a negative MPR error code.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, httpWrite, httpWriteString

ssize httpWriteString (HttpQueue *q, cchar *s)

Write a string of data to the queue.

Write a safe 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:

  q | Queue reference.
  s | String containing the data to write.

Returns:
  A count of the bytes actually written.

API Stability:
  Stable.

Description:
  This will escape any HTML sequences before writing the string 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:

  q | Queue reference.
  s | String containing the data to write.

Returns:
  A count of the bytes actually written.

API Stability:
  Stable.

See Also:
  HttpConn, HttpPacket, HttpQueue, httpDisableQueue, httpDiscardQueueData, httpEnableQueue, httpFlushQueue, httpGetQueueRoom, httpIsEof, httpIsPacketTooBig, httpIsQueueEmpty, httpIsQueueSuspended, httpJoinPacketForService, httpJoinPackets, httpPutBackPacket, httpPutForService, httpPutPacket, httpPutPacketToNext, httpRemoveQueue, httpResizePacket, httpResumeQueue, httpScheduleQueue, httpServiceQueue, httpSetQueueLimits, httpSuspendQueue, httpWillNextQueueAcceptPacket, httpWillNextQueueAcceptSize, 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:

  MprOff |  | end | End byte of range + 1.
  MprOff |  | len | Redundant range length.
  struct HttpRange * |  | next | Next range.
  MprOff |  | start | Start of range.

# HttpRoute

HttpRoute

Route Control.

See Also:
  httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

API Stability:
  Internal.

Fields:

  HttpAuth * |  | auth | Per route block authentication.
  int |  | autoDelete | Automatically delete uploaded files.
  MprList * |  | caching | Items to cache.
  MprList * |  | conditions | Route conditions.
  HttpStage * |  | connector | Network connector to use.
  void * |  | context | Hosting context (Appweb == EjsPool).
  MprHash * |  | data | Hash of extra data configuration.
  char * |  | defaultLanguage | Default language.
  char * |  | dir | Documents directory.
  void * |  | eroute | Extended route information for handler (only).
  MprHash * |  | errorDocuments | Set of error documents to use on errors.
  MprHash * |  | extensions | Hash of handlers by extensions.
  int |  | flags | Route flags.
  HttpStage * |  | handler | Fixed handler.
  MprList * |  | handlers | List of handlers for this route.
  MprList * |  | handlersByMatch | List of handlers that match solely by their match routine.
  MprList * |  | headers | Matching header values.
  char * |  | home | Home directory for configuration files.
  struct HttpHost * |  | host | Owning host.
  Http * |  | http | Http service object (copy of appweb->http).
  int |  | ignoreEncodingErrors | Ignore UTF8 encoding errors.
  MprList * |  | indicies | Directory index documents.
  MprList * |  | inputStages | Input stages.
  MprHash * |  | languages | Languages supported.
  MprTicks |  | lifespan | Default lifespan for all cache items in route.
  HttpLimits * |  | limits | Host resource limits.
  MprFile * |  | log | File object for access logging.
  int |  | logBackup | Number of log backups.
  int |  | logFlags | Log control flags (append|anew).
  char * |  | logFormat | Access log format.
  char * |  | logPath | Access log filename.
  ssize |  | logSize | Max log size.
  MprHash * |  | methods | Matching HTTP methods.
  char * |  | methodSpec | Supported HTTP methods.
  MprHash * |  | mimeTypes | Hash table of mime types (key is extension).
  MprMutex * |  | mutex | Multithread sync.
  char * |  | name | Route name.
  int |  | nextGroup | 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.
  ssize |  | prefixLen | Prefix length.
  int |  | responseStatus | Response status code.
  char * |  | script | Startup script for handlers serving this route.
  char * |  | scriptPath | Startup script path for handlers serving this route.
  char * |  | sourceName | Source name for route target.
  struct MprSsl * |  | ssl | SSL configuration.
  char * |  | startSegment | Starting literal segment of pattern (includes prefix).
  ssize |  | startSegmentLen | Prefix length.
  char * |  | startWith | Starting literal segment of pattern (includes prefix).
  ssize |  | startWithLen | 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[2] | Default route request tracing.
  int |  | traceMask | Request/response trace mask.
  MprList * |  | updates | Route and request updates.
  char * |  | uploadDir | Upload directory.
  MprHash * |  | vars | Route variables. Used to expand Path ${token} refrerences.
  MprTicks |  | webSocketsPingPeriod | Time between pings (msec).
  char * |  | webSocketsProtocol | WebSockets sub-protocol.
  int |  | workers | Number of workers to use for this route.

void httpAddHomeRoute (HttpRoute *parent)

Add a route for the home page.

Description:
  This will add a home page to route ESP applications. This will add the following route:

  </row>
  Name | Method | Pattern | Target
  </row>
  home | GET,POST,PUT | ^/$ | index.esp

Parameters:

  parent | Parent route from which to inherit configuration.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, 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:

  </row>
  Name | Method | Pattern | Action
  </row>
  init | GET | /NAME/init$ | init
  </row>
  create | POST | /NAME(/)*$ | create
  </row>
  edit | GET | /NAME/edit$ | edit
  </row>
  show | GET | /NAME$ | show
  </row>
  update | PUT | /NAME$ | update
  </row>
  destroy | DELETE | /NAME$ | destroy
  </row>
  default | * | /NAME/{action}$ | cmd-${action}

Parameters:

  parent | Parent route from which to inherit configuration.
  resource | Resource name. This should be a lower case, single word, alphabetic resource name.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, 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:

  </row>
  Name | Method | Pattern | Action
  </row>
  list | GET | /NAME(/)*$ | list
  </row>
  init | GET | /NAME/init$ | init
  </row>
  create | POST | /NAME(/)*$ | create
  </row>
  edit | GET | /NAME/{id=[0-9]+}/edit$ | edit
  </row>
  show | GET | /NAME/{id=[0-9]+}$ | show
  </row>
  update | PUT | /NAME/{id=[0-9]+}$ | update
  </row>
  destroy | DELETE | /NAME/{id=[0-9]+}$ | destroy
  </row>
  custom | POST | /NAME/{action}/{id=[0-9]+}$ | ${action}
  </row>
  default | * | /NAME/{action}$ | cmd-${action}

Parameters:

  parent | Parent route from which to inherit configuration.
  resource | Resource name. This should be a lower case, single word, alphabetic resource name.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, 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:

  route | Route to modify.

  name

  Condition 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}".

  details | Condition parameters. See httpSetRouteTarget for a list of the token values that can be included in the condition rule details.
  flags | Set to HTTP_ROUTE_NOT to negate the condition test.

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpAddRouteErrorDocument (HttpRoute *route, int status, cchar *uri)

Add an error document.

Description:
  This defines an error document to be used when the requested document cannot be found. This definition is used by some handlers for error processing.

Parameters:

  route | Route to modify.
  status | The HTTP status code to use with the error document.
  uri | URL describing the error document.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

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:

  route | Route to modify.
  name | Filter name to add.
  extensions | Request extensions for which the filter will be run. A request extension may come from the URI if present or from the corresponding filename.
  direction | Set 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:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, 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:

  route | Route to modify.
  name | Filter name to add.
  extensions | Request 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:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpAddRouteHeader (HttpRoute *route, cchar *header, cchar *value, int flags)

Add a route header check.

Description:
  This configures the route to match a request only if the specified header field matches a specific value.

Parameters:

  route | Route to modify.
  header | Header field to interrogate.
  value | Header value that will match.
  flags | Set to HTTP_ROUTE_NOT to negate the header test.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpAddRouteIndex (HttpRoute *route, cchar *path)

Set the route index document.

Description:
  Set the name of the index document to serve. Index documents may be served when the request corresponds to a directory on the file system.

Parameters:

  route | Route to modify.
  path | Path name to the index document. If the path is a relative path, it may be joined to the route directory to create an absolute path.

Returns:
  A reference to the route data. Otherwise return null if the route data for the given key was not found.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

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:

  route | Route to modify.
  language | Language symbolic name. For example: "en" for english.
  path | File system directory to contain content for matching requests.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, 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:

  route | Route to modify.
  language | Language symbolic name. For example: "en" for english.
  suffix | Extension suffix to add when creating filenames for the request. For example: "fr" to add to "index.html" could produce: "index.fr.html".
  flags | Set 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:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpAddRouteParam (HttpRoute *route, cchar *field, cchar *value, int flags)

Add a route param check.

Description:
  This configures the route to match a request only if the specified param field matches a specific value.

Parameters:

  route | Route to modify.
  field | Param field to interrogate.
  value | Header value that will match.
  flags | Set to HTTP_ROUTE_NOT to negate the query test.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpAddRouteSet (HttpRoute *parent, cchar *set)

Add a route set package.

Description:
  This will add a set of routes suitable for some application paradigms.

  </row>
  Name | Method | Pattern | Target
  </row>
  home | GET,POST,PUT | ^/$ | index.esp
  </row>
  static | GET | ^/static(/(.)*$ | $1

Parameters:

  parent | Parent route from which to inherit configuration.

  set

  Route set to select. Use "simple", "mvc", "restful" or "none".
  The "simple" pack will invoke httpAddHomeRoute and httpAddStaticRoute to add "home", and "static" routes.
  The "mvc" selection will add the default routes and then add the route:

  </row>
  Name | Method | Pattern | Target
  </row>
  default | * | ^/{controller}(~/{action}~)$ | ${controller}-${action}

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

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:

  route | Route to modify.

  name

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

  details | Update rule parameters.
  flags | Reserved.

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpAddStaticRoute (HttpRoute *parent)

Add a route for static content under a "static" directory.

This can be used for ESP applications. Use the EspDir appweb configuration file directive to modify the "static" directory

Description:
  This will add a route for static content. This will add the following route:

  </row>
  Name | Method | Pattern | Target
  </row>
  static | GET | ^/static(/(.)*$ | $1

Parameters:

  parent | Parent route from which to inherit configuration.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpBackupRouteLog (HttpRoute *route)

Backup the route log if required.

Description:
  If the log file is greater than the maximum configured, or MPR_ANEW was set via httpSetRouteLog, then archive the log.

Parameters:

  route | Route to modify.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpClearRouteStages (HttpRoute *route, int direction)

Clear the pipeline stages for the route.

Description:
  This resets the configured pipeline stages for the route.

Parameters:

  route | Route to modify.
  direction | Set to HTTP_STAGE_TX for transmit direction and HTTP_STAGE_RX for receive data flow.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpRoute * httpCreateActionRoute (HttpRoute *parent, cchar *pattern, HttpAction action)

Create a route for use with the Action Handler.

Description:
  This call creates a route inheriting from a parent route. The new route is configured for use with the actionHandler and the given callback procedure.

Parameters:

  parent | Parent route from which to inherit.
  pattern | Pattern to match URIs.
  action | Action to invoke.

Returns:
  Newly created route.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

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:

  parent | Parent route to inherit from.
  pattern | Pattern to match URIs.
  path | File system directory containing documents for this route.
  status | Http redirect status for matching requests. Set to zero if not using redirects.

Returns:
  Allocated HttpRoute object.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpRoute * httpCreateConfiguredRoute (struct HttpHost *host, int serverSide)

Create a configured route.

Description:
  This creates a route and configures the request pipeline with range, chunk and upload filters.

Parameters:

  host | HttpHost object owning the route.
  serverSide | Set to "true" if this is a server side route. Set to "false" for client side.

Returns:
  Allocated HttpRoute object.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpRoute * httpCreateDefaultRoute (struct HttpHost *host)

Create a default route for a host.

Description:
  When the route is fully configured, it should be finalized which will add it to its owning host.

Parameters:

  host | HttpHost object owning the route.

Returns:
  Allocated HttpRoute object.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpRoute * httpCreateInheritedRoute (HttpRoute *route)

Create a route inherited from a parent route.

Description:
  When the route is fully configured, it should be finalized which will add it to its owning host.

Parameters:

  route | Parent route from which to inherit.

Returns:
  Allocated HttpRoute object.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpRoute * httpCreateRoute (struct HttpHost *host)

Create a route for a host.

Description:
  This call creates a bare route without inheriting from a parent route. When the route is fully configured, it should be finalized which will add it to its owning host.

Parameters:

  host | HttpHost object owning the route.

Returns:
  Allocated HttpRoute object.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpRoute * httpDefineRoute (HttpRoute *parent, cchar *name, 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:

  parent | Parent route from which to inherit configuration.
  name | Route name to define.
  methods | Http methods for which this route is active.
  pattern | Matching URI pattern for which this route will qualify.
  target | Route target string expression. This is used by handlers to determine the physical or virtual resource to serve.
  source | Source file pattern containing the resource to activate or serve.

Returns:
  Created route.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpDefineRouteCondition (cchar *name, HttpRouteProc *proc)

Define a route condition rule.

Description:
  This creates a new condition rule.

Parameters:

  name | Condition name.
  proc | Condition function to process the condition during route matching.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpDefineRouteTarget (cchar *name, HttpRouteProc *proc)

Define a route target rule.

Description:
  This creates a new target rule.

Parameters:

  name | Target name.
  proc | Target function to process the target during route matching.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpDefineRouteUpdate (cchar *name, HttpRouteProc *proc)

Define a route update rule.

Description:
  This creates a new update rule.

Parameters:

  name | Update name.
  proc | Update function to process the update during route matching.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

cchar * httpExpandRouteVars (HttpRoute *route, cchar *str)

Expand route variables in a string.

Parameters:

  route | Route to modify.
  str | String to expand.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpFinalizeRoute (HttpRoute *route)

Finalize a route.

Description:
  A route must be finalized to add it to its owning hosts list of routes.

Parameters:

  route | Route to modify.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpRoute * httpGetDefaultRoute (HttpHost *host)

Get the default route for a host.

Parameters:

  host | Host object.

Returns:
  The default route for the host.

API Stability:
  Stable.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpRoute * httpGetHostDefaultRoute (HttpHost *host)

Return 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:

  host | Host to examine.

Returns:
  Default route object.

API Stability:
  Stable.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

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:

  route | Route to modify.
  key | Unique 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:
  Evolving.

cchar * httpGetRouteDir (HttpRoute *route)

Get the route directory.

Description:
  Routes can define a default directory for documents to serve. This value may be used by target rules to calculate the response filename.

Parameters:

  route | Route to modify.

Returns:
  The route documents directory pathname.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

cchar * httpGetRouteMethods (HttpRoute *route)

Get the route method list.

Parameters:

  route | Route to examine.

Returns:
  The the list of support methods. Return NULL if not method list is defined.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

cchar * httpGetRouteVar (HttpRoute *route, cchar *key)

Get a path token variable.

Parameters:

  route | Route to get.
  key | Token key value.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpLimits * httpGraduateLimits (HttpRoute *route, HttpLimits *limits)

Graduate the limits from the parent route.

Description:
  This creates a unique limit structure for the route if it is currently inheriting its parents limits.

Parameters:

  route | Route to modify.
  limits | Limits to use if graduating.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

char * httpLink (HttpConn *conn, cchar *target, MprHash *options)

Create a URI link.

\par \b Description: Create a URI link by expansions tokens based on the current request and route state. The target parameter may contain partial or complete URI information. The missing parts are supplied using the current request and route tables. The resulting URI is a normalized, server-local URI (that begins with "/"). The URI will include any defined route prefix, but will not include scheme, host or port components

Parameters:

  conn | HttpConn connection object.

  target

  The 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 controller/action pair of the form "{AT}Controller/action". If the "controller/" portion is absent, the current controller is used. If the action component is missing, the "list" action is used. A bare "{AT}" refers to the "list" action of the current controller.
  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 controller/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 "?"
  - controller String Controller name if using a Controller-based route. This can also be specified via the action option.
  - action String Action to invoke. This can be a URI string or a Controller action of the form {AT}Controller/action.
  - route String Route name to use for the URI template

  options | Hash of option values for embedded tokens.

Returns:
  A normalized, server-local Uri string.

API Stability:
  Evolving.

Remarks:
  Examples:

          httpLink(conn, "http://example.com/index.html", 0);
          httpLink(conn, "/path/to/index.html", 0);
          httpLink(conn, "../images/splash.png", 0);
          httpLink(conn, "~/static/images/splash.png", 0);
          httpLink(conn, "${app}/static/images/splash.png", 0);
          httpLink(conn, "@controller/checkout", 0);
          httpLink(conn, "@controller/")                //  Controller = Controller, action = index
          httpLink(conn, "@init")                       //  Current controller, action = init
          httpLink(conn, "@")                           //  Current controller, action = index
          httpLink(conn, "{ action: '@post/create' }", 0);
          httpLink(conn, "{ action: 'checkout' }", 0);
          httpLink(conn, "{ action: 'logout', controller: 'admin' }", 0);
          httpLink(conn, "{ action: 'admin/logout'", 0);
          httpLink(conn, "{ product: 'candy', quantity: '10', template: '/cart/${product}/${quantity}' }", 0);
          httpLink(conn, "{ route: '~/STAR/edit', action: 'checkout', id: '99' }", 0);
          httpLink(conn, "{ template: '~/static/images/${theme}/background.jpg', theme: 'blue' }", 0);

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpLogRoutes (HttpHost *host, bool full)

Show the current route table to the error log.

Description:
  This emits the currently defined route table for a host to the route table. If the "full" argument is true, a more-complete, multi-line output format will be used. Othewise, a one-line, abbreviated route description will be output.

Parameters:

  host | Host to examine.
  full | Set to true for a "fuller" output route description.

API Stability:
  Stable.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

HttpRoute * httpLookupRoute (HttpHost *host, cchar *name)

Lookup a route by name.

Parameters:

  host | HttpHost object owning the route table.
  name | Route name to find. If null or empty, look for "default".

API Stability:
  Stable.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

cchar * httpLookupRouteErrorDocument (HttpRoute *route, int status)

Lookup an error document by HTTP status code.

Description:
  This looks up error documents configured via httpAddRouteErrorDocument

Parameters:

  route | Route to modify.
  status | HTTP status code integer.

Returns:
  URI associated with the error document for the requested status.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

char * httpMakePath (HttpRoute *route, cchar *path)

Make a filename path.

Description:
  This makes a filename by expanding the tokens "${token}" and then normalizing the path and converting to an absolute path name. 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/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:

  route | Route to modify.
  path | Path name to examine.

Returns:
  An absolute file name.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpMapFile (HttpConn *conn, HttpRoute *route)

Map the request URI and route target to a filename.

Description:
  This sets the HttpTx filename, ext, etag and info fields.

Parameters:

  conn | HttpConn connection object.
  route | Route to modify.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

int httpMatchRoute (HttpConn *conn, HttpRoute *route)

Match a route against the current request.

Description:
  This tests if a route matches the current request on a connection. This call is automatically called by httpRouteRequest for incoming requests to a server.

Parameters:

  conn | HttpConn connection object.
  route | Route to modify.

Returns:
  HTTP_ROUTE_OK if the request matches. Return HTTP_ROUTE_REMATCH if the request has been modified and route matching must be restarted.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpResetRoutePipeline (HttpRoute *route)

Reset the route pipeline.

Description:
  This completely resets the pipeline and discards inherited pipeline configuration. This resets the error documents, expiry cache values, extensions, handlers, input and output stage configuration.

Parameters:

  route | Route to modify.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteAuth (HttpRoute *route, HttpAuth *auth)

Set the route authentication.

Description:
  This defines the authentication configuration for basic and digest authentication for the route.

Parameters:

  route | Route to modify.
  auth | Authentication object.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteAutoDelete (HttpRoute *route, bool on)

Control file upload auto delete.

Description:
  This controls whether files are auto-deleted after the handler runs to service a request.

Parameters:

  route | Route to modify.
  on | Set to true to enable auto-delete. Auto-delete is enabled by default.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteCompression (HttpRoute *route, int flags)

Contol content compression for the route.

Description:
  This configures content compression for the route. Some handlers observe the content compression status and will attempt to use or compress content before transmitting to the client. The fileHandler is currently the only handler that uses this capability.

Parameters:

  route | Route to modify.
  flags | Set to HTTP_ROUTE_GZIP to enable the fileHandler to serve eqivalent compressed content with a "gz" extension.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

int httpSetRouteConnector (HttpRoute *route, cchar *name)

Set the connector to use for a route.

Parameters:

  route | Route to modify.
  name | Connector name to use for this route.

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteData (HttpRoute *route, cchar *key, void *data)

Set 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:

  route | Route to modify.
  key | Unique string to identify the data.
  data | Data object. This must be allocated via mprAlloc.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteDefaultLanguage (HttpRoute *route, cchar *language)

Set the default language for the route.

Description:
  This call defines the default language to serve if the client does not provide an Accept HTTP header with language preference instructions.

Parameters:

  route | Route to modify.
  language | Language symbolic name. For example: "en" for english.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteDir (HttpRoute *route, cchar *dir)

Set the route directory.

Description:
  Routes can define a default directory for documents to serve. This value may be used by target rules to calculate the response filename.

Parameters:

  route | Route to modify.
  dir | Directory path name for the route content.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteFlags (HttpRoute *route, int flags)

Update the route flags.

Description:
  Low level routine to manipulate the route flags.

Parameters:

  route | Route to modify.
  flags | Flags mask.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

int httpSetRouteHandler (HttpRoute *route, cchar *name)

Set the handler to use for a route.

Description:
  This defines the stage handler to use in the request pipline for requests matching this route. Note that you can also use httpAddRouteHandler which configures a set of handlers that will match by extension.

Parameters:

  route | Route to modify.
  name | Handler name to define.

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteHome (HttpRoute *route, cchar *home)

Set the route directory for configuration files.

Description:
  Routes can define a default directory for configuration files.

Parameters:

  route | Route to modify.
  home | Directory path name for configuration files.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

int httpSetRouteLog (HttpRoute *route, cchar *path, ssize size, int backup, cchar *format, int flags)

Configure the route access log.

Parameters:

  route | Route to modify.
  path | Path for route access log file.
  size | Maximum size of the log file before archiving.
  backup | Set to true to create a backup of the log file if archiving.
  format | Log file format.
  flags | Set to MPR_LOG_ANEW to archive the log when the application reboots.

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteMethods (HttpRoute *route, cchar *methods)

Define the methods for the route.

Description:
  This defines the set of valid HTTP methods for requests to match this route.

Parameters:

  route | Route to modify.
  methods | Set to a comma or space separated list of methods. Can also set to "All" or "*" for all possible methods. Standard methods include: "DELETE, GET, OPTIONS, POST, PUT, TRACE".

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteName (HttpRoute *route, cchar *name)

Set the route name.

Description:
  Symbolic route names are used by httpLink and when displaying route tables.

Parameters:

  route | Route to modify.
  name | Unique symbolic name for the route. If a name is not defined, the route pattern will be used as the name.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

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 patter. 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:

  route | Route to modify.
  pattern | Route regular expression pattern.
  flags | Set to HTTP_ROUTE_NOT to negate the pattern match result.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRoutePrefix (HttpRoute *route, cchar *prefix)

Set the route prefix.

Description:
  Routes may have a prefix which will be stripped from the request URI if the request matches. The prefix is made available as the "${request:prefix}" token and also as the ScriptName via some handlers.

Parameters:

  route | Route to modify.
  prefix | URI prefix to define for the route.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteScript (HttpRoute *route, cchar *script, cchar *scriptPath)

Set the script to service the route.

Description:
  This is used by handlers to add a per-route script for processing. Ejscript uses this to specify the server script. Either a literal script or a path to a script filename can be provided.

Parameters:

  route | Route to modify.
  script | Literal script to execute.
  scriptPath | Pathname to the script file to execute.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteSource (HttpRoute *route, cchar *source)

Set the source code module for the route.

Description:
  Some handlers can dynamically load web applications and controllers to serve requests.

Parameters:

  route | Route to modify.
  source | Source path or description.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

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:

  route | Route to modify.

  name

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

  details | Update rule parameters.

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteTemplate (HttpRoute *route, cchar *tplate)

Set the route template.

Description:
  Set the route URI template uses when constructing URIs via httpLink.

Parameters:

  route | Route to modify.
  tplate | URI template to use. Templates may contain embedded tokens "{token}" where the token names correspond to the token names in the route pattern.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteTraceFilter (HttpRoute *route, int dir, int levels, ssize len, cchar *include, cchar *exclude)

Set the route trace filter.

Description:
  Trace filters include or exclude trace items based on the request filename extension.

Parameters:

  route | HttpRoute object.
  dir | Trace direction. Set to HTTP_TRACE_TX or HTTP_TRACE_RX.
  levels | Trace class levels. Indicies are: HTTP_TRACE_CONN, HTTP_TRACE_FIRST, HTTP_TRACE_HEADER, HTTP_TRACE_BODY, HTTP_TRACE_LIMITS, HTTP_TRACE_TIME.
  len | Maximum content length eligible for tracing.
  include | Comma or space separated list of extensions to include in tracing.
  exclude | Comma or space separated list of extensions to exclude from tracing.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteVar (HttpRoute *route, cchar *token, cchar *value)

Define a path token variable.

Description:
  The httpMakePath routine and route conditions, updates, headers, fields and targets will expand tokenized expressions "${token}". Additional tokens can be defined via this API.

Parameters:

  route | Route to modify.
  token | Name of the token to define.
  value | Value of the token.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

void httpSetRouteWorkers (HttpRoute *route, int workers)

Define the maximum number of workers for a route.

Parameters:

  route | Route to modify.
  workers | Maximum number of workers for this route.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpTemplate, httpTokenize, httpTokenizev

void httpSetStageData (struct HttpConn *conn, cchar *key, cvoid *data)

Set stage data.

Description:
  Stages can store extra configuration information indexed by key. This is used by handlers, filters, connectors and and handlers.

Parameters:

  conn | HttpConn connection object.
  key | Key index into the stage data.
  data | Reference to custom data allocated via mprAlloc.

API Stability:
  Stable.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

char * httpTemplate (HttpConn *conn, cchar *tplate, MprHash *options)

Expand a template string using given options.

Description:
  This expands a string with embedded tokens of the form "${token}" using values from the given options.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  tplate | Template string to process.
  options | Hash of option values for embedded tokens.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTokenize, httpTokenizev

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:

  route | Route to modify.
  str | String to expand.
  fmt | Format string specifier.

Returns:
  True if the string can be successfully parsed.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenizev

bool httpTokenizev (HttpRoute *route, cchar *str, cchar *fmt, va_list args)

Tokenize a string based on route data.

Description:
  This is a utility routine to parse a string into tokens given a format specifier. This call is similar to httpTokenize but uses a va_list argument.

Parameters:

  route | Route to modify.
  str | String to expand.
  fmt | Format string specifier.
  args | Varargs argument list.

Returns:
  True if the string can be successfully parsed.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize

void httpWriteRouteLog (HttpRoute *route, cchar *buf, ssize len)

Write data to the route access log.

Description:
  Write data after archiving if required.

Parameters:

  route | Route to modify.
  buf | Data buffer to write.
  len | Size of the data buffer.

API Stability:
  Evolving.

See Also:
  HttpRoute, httpAddRouteCondition, httpAddRouteErrorDocument, httpAddRouteFilter, httpAddRouteHandler, httpAddRouteHeader, httpAddRouteLanguageDir, httpAddRouteLanguageSuffix, httpAddRouteUpdate, httpClearRouteStages, httpCreateAliasRoute, httpCreateDefaultRoute, httpCreateInheritedRoute, httpCreateRoute, httpDefineRoute, httpDefineRouteCondition, httpDefineRouteTarget, httpDefineRouteUpdate, httpFinalizeRoute, httpGetRouteData, httpGetRouteDir, httpLink, httpLookupRouteErrorDocument, httpMakePath, httpMatchRoute, httpResetRoutePipeline, httpSetRouteAuth, httpSetRouteAutoDelete, httpSetRouteCompression, httpSetRouteConnector, httpSetRouteData, httpSetRouteDefaultLanguage, httpSetRouteDir, httpSetRouteFlags, httpSetRouteHandler, httpSetRouteMethods, httpSetRouteName, httpSetRoutePattern, httpSetRoutePrefix, httpSetRouteScript, httpSetRouteSource, httpSetRouteTarget, httpSetRouteVar, httpSetRouteWorkers, httpTemplate, httpTokenize, httpTokenizev

# HttpRx

HttpRx

Http Rx.

Description:
  Most of the APIs in the rx group still take a HttpConn object as their first parameter. This is to make the API easier to remember - APIs take a connection object rather than a rx or tx object.

See Also:
  HttpConn, 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:

  char * |  | accept | Accept header.
  char * |  | acceptCharset | Accept-Charset header.
  char * |  | acceptEncoding | Accept-Encoding header.
  char * |  | acceptLanguage | Accept-Language header.
  char * |  | authDetails | Header details: authorization|www-authenticate provided by peer.
  int |  | authenticated | Request has been authenticated.
  int |  | autoDelete | Automatically delete uploaded files.
  MprOff |  | bytesRead | Length of content read by user.
  int |  | chunkState | Chunk encoding state.
  HttpConn * |  | conn | Connection object.
  char * |  | connection | Connection header.
  char * |  | contentLength | Content length string value.
  char * |  | cookie | Cookie header.
  int |  | eof | All read data has been received (eof).
  MprList * |  | etags | Document etag to uniquely identify the document version.
  char * |  | extraPath | Extra path information (CGI|PHP).
  MprHash * |  | files | Uploaded files. Managed by the upload filter.
  int |  | flags | Rx modifiers.
  int |  | form | Using mime-type application/x-www-form-urlencoded.
  HttpPacket * |  | headerPacket | HTTP headers.
  MprHash * |  | headers | Header variables.
  char * |  | hostHeader | Client supplied host name header.
  bool |  | ifMatch | If-Match processing requested.
  bool |  | ifModified | If-Modified processing requested.
  MprList * |  | inputPipeline | Input processing.
  HttpRange * |  | inputRange | Specified range for rx (post) data.
  HttpLang * |  | lang | Selected language.
  MprOff |  | length | Content length header value (ENV: CONTENT_LENGTH).
  char * |  | method | Request method.
  char * |  | mimeType | Mime type of the request payload (ENV: CONTENT_TYPE).
  int |  | needInputPipeline | Input pipeline required to process received data.
  char * |  | origin | Origin header (not used).
  char * |  | originalMethod | Original method from the client.
  char * |  | originalUri | Original URI passed by the client.
  int |  | ownParams | Do own parameter handling.
  MprHash * |  | params | Request params (Query and post data variables).
  char * |  | paramString | Cached param data as a string.
  HttpUri * |  | parsedUri | Parsed request uri.
  char * |  | passDigest | User password digest for authentication.
  char * |  | pathInfo | Path information after the scriptName (Decoded and normalized).
  char * |  | pragma | Pragma header.
  char * |  | redirect | Redirect route header.
  char * |  | referrer | Refering URL.
  MprOff |  | remainingContent | Remaining content data to read (in next chunk if chunked).
  MprHash * |  | requestData | General request data storage. Users must create hash table if required.
  HttpRoute * |  | route | Route for request.
  char * |  | scriptName | ScriptName portion of the uri (Decoded). May be empty or start with "/".
  char * |  | securityToken | Security form token.
  HttpSession * |  | session | Session for request.
  int |  | sessionProbed | Session has been resolved.
  MprTime |  | since | If-Modified date.
  int |  | status | HTTP response status.
  char * |  | statusMessage | HTTP Response status message.
  int |  | streaming | Stream incoming content. Forms typically buffer and dont stream.
  MprHash * |  | svars | Server variables.
  char * |  | target | Route target.
  int |  | traceLevel | General trace level for header level info.
  char * |  | upgrade | Protocol upgrade header.
  int |  | upload | Request is using file upload.
  char * |  | uploadDir | Upload directory.
  char * |  | uri | Current URI (not decoded, may be rewritten).
  char * |  | userAgent | User-Agent header.
  struct HttpWebSocket * |  | webSocket | WebSocket state.

void httpAddParams (HttpConn *conn)

Add query and form body data to params.

Description:
  This adds query data and posted body data to the request params.

Parameters:

  conn | HttpConn connection object.

API Stability:
  Internal.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath

bool httpContentNotModified (HttpConn *conn)

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:

  conn | HttpConn connection object.

Returns:
  True if the content is current and has not been modified.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn)

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:

  conn | HttpConn connection object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn)

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:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  A count of the response content data in bytes.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath

cchar * httpGetCookies (HttpConn *conn)

Get the request cookies.

Description:
  Get the cookies defined in the current requeset.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  Return a string containing the cookies sent in the Http header of the last request.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn, cchar *key)

Get an rx http header.

Description:
  Get a http response header for a given header key.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  key | Name of the header to retrieve. This should be a lower case header name. For example: "Connection".

Returns:
  Value associated with the header key or null if the key did not exist in the response.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn)

Get the hash table of rx Http headers.

Description:
  Get the internal hash table of rx headers.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  Hash table. See MprHash for how to access the hash table.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn)

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:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  String containing all the headers. The caller must free this returned string.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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)

Get a header string from the given hash.

Description:
  This returns a set of "key: value" lines in HTTP header format.

Parameters:

  hash | Hash table to examine.

API Stability:
  Internal.

See Also:
  HttpConn, HttpRx, 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 httpGetIntParam (HttpConn *conn, cchar *var, int defaultValue)

Get a form variable as an integer.

Description:
  Get the value of a named form variable as an integer. Form variables are define via www-urlencoded query or post data contained in the request.

Parameters:

  conn | HttpConn connection object.
  var | Name of the form variable to retrieve.
  defaultValue | Default value to return if the variable is not defined. Can be null.

Returns:
  Integer containing the form variable's value.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn, 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:

  conn | HttpConn connection object.
  spoken | Hash table of HttpLang records. This is typically route->languages.
  defaultLang | Default 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:
  HttpConn, HttpRx, 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 (HttpConn *conn, cchar *var, cchar *defaultValue)

Get a request param.

Description:
  Get the value of a named request param. Form variables are define via www-urlencoded query or post data contained in the request.

Parameters:

  conn | HttpConn connection object.
  var | Name of the request param to retrieve.
  defaultValue | Default value to return if the variable is not defined. Can be null.

Returns:
  String containing the request param's value. Caller should not free.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath

MprHash * httpGetParams (HttpConn *conn)

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:

  conn | HttpConn connection object.

Returns:
  MprHash instance containing the form vars.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath

char * httpGetParamsString (HttpConn *conn)

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:

  conn | HttpConn connection object.

Returns:
  A string representation in www-urlencoded format.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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)

Get a path extension.

Parameters:

  path | File pathname to examine.

Returns:
  The path extension sans ".".

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 * httpGetQueryString (HttpConn *conn)

Get the request query string.

Description:
  Get query string sent with the current request.

Parameters:

  conn | HttpConn connection object.

Returns:
  String containing the request query string. Caller should not free.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn)

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

Parameters:

  conn | HttpConn connection object.

Returns:
  The number of bytes available in the read queue for the connection.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 HttpConn *conn, 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:

  conn | HttpConn connection object.
  key | Key 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:
  HttpConn, HttpRx, 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 (HttpConn *conn)

Get the response status.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  An integer Http response code. Typically 200 is success.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath

char * httpGetStatusMessage (HttpConn *conn)

Get the Http response status message.

The Http status message is supplied on the first line of the Http response

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  A Http status message.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn, 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:

  conn | HttpConn connection object.
  var | Name of the form variable.
  expected | Expected value to match with.

Returns:
  True if the value matches.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath

bool httpPumpRequest (HttpConn *conn, HttpPacket *packet)

Pump the Http engine for a request.

Parameters:

  conn | HttpConn connection object.
  packet | Optional packet of input data. Set to NULL if calling from user handlers.

Returns:
  True if the request is completed successfully.

API Stability:
  Internal.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath

ssize httpRead (HttpConn *conn, char *buffer, ssize size)

Read rx body data.

This will read available body data. If in sync mode, this call may block. If in async mode, the call will not block and will return with whatever data is available

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  buffer | Buffer to receive read data.
  size | Size of buffer.

Returns:
  The number of bytes read.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpReadString, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath

char * httpReadString (HttpConn *conn)

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:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  A string containing the rx body. Caller should free.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpSetIntParam, httpSetParam, httpSetUri, httpTestParam, httpTrimExtraPath

void httpSetIntParam (HttpConn *conn, cchar *var, int value)

Set an integer request param value.

Description:
  Set the value of a named request param to an integer value. Form variables are define via www-urlencoded query or post data contained in the request.

Parameters:

  conn | HttpConn connection object.
  var | Name of the request param to retrieve.
  value | Default value to return if the variable is not defined. Can be null.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn, 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:

  conn | HttpConn connection object.
  method | New method to use.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn, cchar *var, cchar *value)

Set a request param value.

Description:
  Set the value of a named request param to a string value. Form variables are define via www-urlencoded query or post data contained in the request.

Parameters:

  conn | HttpConn connection object.
  var | Name of the request param to retrieve.
  value | Default value to return if the variable is not defined. Can be null.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpContentNotModified, httpCreateCGIParams, httpGetContentLength, httpGetCookies, httpGetHeader, httpGetHeaderHash, httpGetHeaders, httpGetIntParam, httpGetLanguage, httpGetParam, httpGetParams, httpGetQueryString, httpGetReadCount, httpGetStatus, httpGetStatusMessage, httpMatchParam, httpRead, httpReadString, httpSetIntParam, httpSetUri, httpTestParam, httpTrimExtraPath

int httpSetUri (HttpConn *conn, 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:

  conn | HttpConn connection object.

  uri

  New 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(conn, "/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:
  HttpConn, HttpRx, 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 (HttpConn *conn, cchar *var)

Test if a request param is defined.

Parameters:

  conn | HttpConn connection object.
  var | Name of the request param to retrieve.

Returns:
  True if the request param is defined.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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 (HttpConn *conn)

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:

  conn | HttpConn connection object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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.
  HttpConn * |  | conn | Owning connection.
  char * |  | id | Session ID key.
  MprTicks |  | lifespan | Session inactivity timeout (msecs).

HttpSession * httpAllocSession (HttpConn *conn, cchar *id, MprTicks lifespan)

Allocate a new session state object.

Parameters:

  conn | Http connection object.
  id | Unique session state ID.
  lifespan | Session lifespan in ticks.

Returns:
  A session state object.

API Stability:
  Internal.

See Also:
  httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar

HttpSession * httpCreateSession (HttpConn *conn)

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:

  conn | Http connection object.

Returns:
  A session state object.

API Stability:
  Internal.

See Also:
  httpAllocSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar

void httpDestroySession (HttpConn *conn)

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:

  conn | Http connection object.

API Stability:
  Internal.

See Also:
  httpAllocSession, httpCreateSession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar

HttpSession * httpGetSession (HttpConn *conn, 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:

  conn | Http connection object.
  create | Set to "true" to create a session state object if one does not already exist for this client.

Returns:
  A session state object.

API Stability:
  Evolving.

See Also:
  httpAllocSession, httpCreateSession, httpDestroySession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar

char * httpGetSessionID (HttpConn *conn)

Get the session ID.

Description:

Parameters:

  conn | Http connection object.

Returns:
  The session ID string.

API Stability:
  Evolving.

See Also:
  httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar

MprHash * httpGetSessionObj (HttpConn *conn, cchar *key)

Get an object from the session state store.

Description:
  Retrieve an object from the session state store by deserializing all properties.

Parameters:

  conn | Http connection object.
  key | Session state key.

API Stability:
  Evolving.

See Also:
  httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar

cchar * httpGetSessionVar (HttpConn *conn, cchar *name, cchar *defaultValue)

Get a session state variable.

Parameters:

  conn | Http connection object.
  name | Variable name to get.
  defaultValue | If the variable does not exist, return the defaultValue.

Returns:
  The variable value or defaultValue if it does not exist.

API Stability:
  Evolving.

See Also:
  httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj, httpSetSessionVar

int httpRemoveSessionVar (HttpConn *conn, cchar *name)

Remove a session state variable.

Parameters:

  conn | Http connection object.
  name | Variable name to remove.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpSetSessionObj, httpSetSessionVar

int httpSetSessionObj (HttpConn *conn, 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:

  conn | Http connection object.
  key | Session state key.
  value | Object to serialize.

API Stability:
  Evolving.

See Also:
  httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionVar

int httpSetSessionVar (HttpConn *conn, cchar *name, cchar *value)

Set a session variable.

Description:

Parameters:

  conn | Http connection object.
  name | Variable name to set.
  value | Variable value to use.

Returns:
  A session state object.

API Stability:
  Evolving.

See Also:
  httpAllocSession, httpCreateSession, httpDestroySession, httpGetSession, httpGetSessionID, httpGetSessionObj, httpRemoveSessionVar, httpSetSessionObj

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

See Also:
  HttpConn, HttpQueue, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultOutgoingServiceStage, httpGetStageData, httpHandleOptionsTrace, httpLookupStage, httpLookupStageData, httpSetStageData

API Stability:
  Internal.

Fields:

  void(* |  | close)(HttpQueue *q) | Close the stage. Description:Close the stage and cleanup any request resources. <parameteritem><parameternamelist><parametername>q</parametername></parameternamelist><parameterdescription>Queue instance object</parameterdescription></parameteritem>API Stability:Evolving
  MprHash * |  | extensions | Matching extensions for this filter.
  int |  | flags | 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. <parameteritem><parameternamelist><parametername>q</parametername></parameternamelist><parameterdescription>Queue instance object </parameterdescription></parameteritem><parameteritem><parameternamelist><parametername>packet</parametername></parameternamelist><parameterdescription>Packet of data</parameterdescription></parameteritem>API Stability:Evolving

  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. <parameteritem><parameternamelist><parametername>q</parametername></parameternamelist><parameterdescription>Queue instance object</parameterdescription></parameteritem>API Stability:Evolving

  int(*

  match)(struct HttpConn *conn, 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. <parameteritem><parameternamelist><parametername>conn</parametername></parameternamelist><parameterdescription>HttpConn connection object </parameterdescription></parameteritem><parameteritem><parameternamelist><parametername>route</parametername></parameternamelist><parameterdescription>Route object </parameterdescription></parameteritem><parameteritem><parameternamelist><parametername>dir</parametername></parameternamelist><parameterdescription>Queue direction. Set to HTTP_QUEUE_TX or HTTP_QUEUE_RX. Always set to HTTP_QUEUE_TX for handlers. </parameterdescription></parameteritem>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:Evolving

  MprModule * |  | module | Backing module.
  char * |  | name | Stage name.
  void(* |  | 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. <parameteritem><parameternamelist><parametername>q</parametername></parameternamelist><parameterdescription>Queue instance object</parameterdescription></parameteritem>API Stability:Evolving

  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. <parameteritem><parameternamelist><parametername>q</parametername></parameternamelist><parameterdescription>Queue instance object </parameterdescription></parameteritem><parameteritem><parameternamelist><parametername>packet</parametername></parameternamelist><parameterdescription>Packet of data</parameterdescription></parameteritem>API Stability:Evolving

  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. <parameteritem><parameternamelist><parametername>q</parametername></parameternamelist><parameterdescription>Queue instance object</parameterdescription></parameteritem>API Stability:Evolving

  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. <parameteritem><parameternamelist><parametername>q</parametername></parameternamelist><parameterdescription>Queue instance object</parameterdescription></parameteritem>API Stability:Evolving

  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 handler start callback should test the HTTP method in conn->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. <parameteritem><parameternamelist><parametername>q</parametername></parameternamelist><parameterdescription>Queue instance object</parameterdescription></parameteritem>API Stability:Evolving

  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. <parameteritem><parameternamelist><parametername>q</parametername></parameternamelist><parameterdescription>Queue instance object</parameterdescription></parameteritem>API Stability:Evolving

HttpStage * httpCloneStage (Http *http, HttpStage *stage)

Create a clone of an existing state.

This is used when creating filters configured to match certain extensions

Parameters:

  http | Http object returned from httpCreate
  stage | Stage object to clone.

Returns:
  A new stage object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpQueue, HttpStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultOutgoingServiceStage, httpGetStageData, httpHandleOptionsTrace, httpLookupStage, httpLookupStageData, httpSetStageData

HttpStage * httpCreateConnector (Http *http, 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:

  http | Http object returned from httpCreate
  name | Name of connector stage.
  module | Optional module object for loadable stages.

Returns:
  A new stage object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpQueue, HttpStage, httpCloneStage, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultOutgoingServiceStage, httpGetStageData, httpHandleOptionsTrace, httpLookupStage, httpLookupStageData, httpSetStageData

HttpStage * httpCreateFilter (Http *http, 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:

  http | Http object.
  name | Name of connector stage.
  module | Optional module object for loadable stages.

Returns:
  A new stage object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpQueue, HttpStage, httpCloneStage, httpCreateConnector, httpCreateHandler, httpCreateStage, httpDefaultOutgoingServiceStage, httpGetStageData, httpHandleOptionsTrace, httpLookupStage, httpLookupStageData, httpSetStageData

HttpStage * httpCreateHandler (Http *http, 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:

  http | Http object.
  name | Name of connector stage.
  module | Optional module object for loadable stages.

Returns:
  A new stage object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpQueue, HttpStage, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateStage, httpDefaultOutgoingServiceStage, httpGetStageData, httpHandleOptionsTrace, httpLookupStage, httpLookupStageData, httpSetStageData

HttpStage * httpCreateStage (Http *http, cchar *name, int flags, MprModule *module)

Create a connector stage.

Description:
  Create a new stage.

Parameters:

  http | Http object returned from httpCreate
  name | Name of connector stage.
  flags | Stage flags.
  module | Optional module object for loadable stages.

Returns:
  A new stage object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpQueue, HttpStage, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpDefaultOutgoingServiceStage, httpGetStageData, httpHandleOptionsTrace, httpLookupStage, httpLookupStageData, httpSetStageData

void httpDefaultOutgoingServiceStage (HttpQueue *q)

Default outgoing data handling.

Description:
  This routine provides default handling of outgoing data for stages. It simply sends all packets downstream.

Parameters:

  q | Queue object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpQueue, HttpStage, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpGetStageData, httpHandleOptionsTrace, httpLookupStage, httpLookupStageData, httpSetStageData

void httpHandleOptionsTrace (struct HttpConn *conn, cchar *methods)

Handle a Http Trace or Options method request.

Description:
  Convenience routine to respond to an OPTIONS or TRACE request.

Parameters:

  conn | HttpConn object created via httpCreateConn
  methods | Comma separated list of supported methods excluding OPTIONS and TRACE which are automatically added if the route supports these methods.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpQueue, HttpStage, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultOutgoingServiceStage, httpGetStageData, httpLookupStage, httpLookupStageData, httpSetStageData

struct HttpStage * HttpStage* httpLookupStage (Http *http, cchar *name)

Lookup a stage by name.

Parameters:

  http | Http object.
  name | Name of stage to locate.

Returns:
  Stage or NULL if not found.

API Stability:
  Stable.

See Also:
  HttpConn, HttpQueue, HttpStage, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultOutgoingServiceStage, httpGetStageData, httpHandleOptionsTrace, httpLookupStageData, httpSetStageData

void * httpLookupStageData (Http *http, cchar *name)

Lookup stage data.

Description:
  This looks up the stage by name and returns the private stage data.

Parameters:

  http | Http object.
  name | Name of the stage concerned.

Returns:
  Reference to the stage data block.

API Stability:
  Stable.

See Also:
  HttpConn, HttpQueue, HttpStage, httpCloneStage, httpCreateConnector, httpCreateFilter, httpCreateHandler, httpCreateStage, httpDefaultOutgoingServiceStage, httpGetStageData, httpHandleOptionsTrace, httpLookupStage, httpSetStageData

# HttpStats

HttpStats

HttpStats.

API Stability:
  Internal.

Fields:

  int |  | activeClients | Current active client IPs.
  int |  | activeConnections | Current active connections.
  int |  | activeProcesses | Current active processes.
  int |  | activeRequests | Current active requests.
  int |  | activeSessions | Current active sessions.
  int |  | activeVMs | Current ejs VMs.
  uint64 |  | heap | Current application heap memory.
  uint64 |  | heapFree | Current heap memory available.
  uint64 |  | heapUsed | Current heap memory in use.
  uint64 |  | mem | Current application memory.
  uint64 |  | memMax | Memory maximum permitted.
  uint64 |  | memRedline | Memory redline limit.
  int |  | pendingRequests | Pending requests waiting to be served.
  int |  | regions | Current memory region count.
  uint64 |  | totalConnections | Total connections accepted.
  uint64 |  | totalRequests | Total requests served.
  uint64 |  | totalSweeps | Total GC sweeps.
  int |  | workersBusy | Current busy worker threads.
  int |  | workersIdle | Current idle worker threads.
  int |  | workersMax | Maximum number of workers in the thread pool.
  int |  | workersYielded | Number of busy workers that are yielded for GC.

void httpGetStats (HttpStats *sp)

Get the Http performance statistics.

Parameters:

  sp | Reference to a HttpStats structure.

API Stability:
  Internal.

See Also:

char * httpStatsReport (int flags)

Get an Http performance report.

Parameters:

  flags | reserved.

Returns:
  String containing the report.

API Stability:
  Internal.

See Also:

# HttpTrace

HttpTrace

Trace management structure.

API Stability:
  Internal.

Fields:

  int |  | disable | If tracing is disabled for this request.
  MprHash * |  | exclude | Extensions to exclude from trace.
  MprHash * |  | include | Extensions to include in trace.
  int |  | levels[HTTP_TRACE_MAX_ITEM] | Level at which to trace this item.
  MprOff |  | size | Maximum size of content to trace.

# 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 HttpConn object as their first parameter. This is to make the API easier to remember - APIs take a connection object rather than a rx or transmission object.

See Also:
  HttpConn, HttpRx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

API Stability:
  Internal.

Fields:

  char * |  | altBody | Alternate transmission for errors.
  MprOff |  | bytesWritten | Bytes written including headers.
  HttpCache * |  | cache | Cache control entry (only set if this request is being cached).
  MprBuf * |  | cacheBuffer | Response caching buffer.
  ssize |  | cacheBufferLength | Current size of the cache buffer data.
  cchar * |  | cachedContent | Retrieved cached response to send.
  ssize |  | chunkSize | Chunk size to use when using transfer encoding. Zero for unchunked.
  struct HttpConn * |  | conn | Current connection object.
  HttpStage * |  | connector | Network connector to send / receive socket data.
  HttpRange * |  | currentRange | Current range being fullfilled.
  MprOff |  | entityLength | 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.
  MprPath |  | fileInfo | File information if there is a real file to serve.
  char * |  | filename | Name of a real file being served (typically pathInfo mapped).
  int |  | finalized | Request response generated and handler processing is complete.
  int |  | finalizedConnector | Connector has finished sending the response.
  int |  | finalizedOutput | Handler or surrogate has finished writing output response.
  int |  | flags | Response flags.
  HttpStage * |  | handler | Final handler serving the request.
  MprHash * |  | headers | Transmission headers.
  ssize |  | headerSize | Size of the header written.
  MprOff |  | length | Transmission content length.
  char * |  | method | Client request method GET, HEAD, POST, DELETE, OPTIONS, PUT, TRACE.
  MprList * |  | outputPipeline | Output processing.
  HttpRange * |  | outputRanges | Data ranges for tx data.
  HttpUri * |  | parsedUri | Client request uri.
  int |  | pendingFinalize | Call httpFinalize again once the Tx pipeline is created.
  HttpQueue * |  | queue[2] | Pipeline queue heads.
  char * |  | rangeBoundary | Inter-range boundary.
  MprOff |  | rangePos | Current range I/O position in response data.
  int |  | responded | The request has started to respond. Some output has been initiated.
  int |  | started | Handler has started.
  int |  | status | HTTP response status.
  int |  | traceMethods | Handler methods supported.
  char * |  | webSockKey | Sec-WebSocket-Key header.
  int |  | writeBlocked | Transmission writing is blocked.

void httpAddHeader (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  key | Http response header key.
  fmt | Printf style formatted string to use as the header key value.
  ... | Arguments for fmt.

Returns:
  "Zero" if successful, otherwise a negative MPR error code. Returns MPR_ERR_ALREADY_EXISTS if the header already exists.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpAddHeaderString (HttpConn *conn, cchar *key, cchar *value)

Add a header to the transmission.

Description:
  Add a header if it does not already exits.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  key | Http response header key.
  value | Value to set for the header.

Returns:
  Zero if successful, otherwise a negative MPR error code. Returns MPR_ERR_ALREADY_EXISTS if the header already exists.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpAppendHeader (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  key | Http response header key.
  fmt | Printf style formatted string to use as the header key value.
  ... | Arguments for fmt.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpAppendHeaderString (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  key | Http response header key.
  value | Value to set for the header.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

int httpConnect (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  method | Http method to use. Valid methods include: "GET", "POST", "PUT", "DELETE", "OPTIONS" and "TRACE".
  uri | URI to fetch.
  ssl | SSL 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:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

HttpTx * httpCreateTx (HttpConn *conn, MprHash *headers)

Create the tx object.

This is used internally by the http library

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  headers | Optional headers to use for the transmission.

Returns:
  A tx object.

API Stability:
  Internal.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpDestroyTx (HttpTx *tx)

Destroy the tx object.

Description:
  This is called when the garbage collector frees a connection. It should not be called manually.

Parameters:

  tx | Tx object.

API Stability:
  Internal.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpFinalize (HttpConn *conn)

Indicate the request is finalized.

Description:
  Calling this routine indicates that the handler has fully finished processing the request including 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.

Parameters:

  conn | HttpConn connection object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpFinalizeOutput (HttpConn *conn)

Finalize transmission of the http response.

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

Parameters:

  conn | HttpConn connection object.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpFlush (HttpConn *conn)

Flush tx data.

This writes any buffered data

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Evolving.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpFollowRedirects (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  follow | Set to true to enable transparent redirections.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpFormatError (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  status | Http response status code.
  fmt | Printf style formatted string. This string may contain HTML tags and is not HTML encoded before sending to the user. NOTE: Do not send user input back to the client using this method. Otherwise you open large security holes.
  ... | Arguments for fmt.

Returns:
  A count of the number of bytes in the transmission body.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

ssize httpFormatResponse (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  fmt | Printf style formatted string. This string may contain HTML tags and is not HTML encoded before sending to the user. NOTE: Do not send user input back to the client using this method. Otherwise you open large security holes.
  ... | Arguments for fmt.

Returns:
  A count of the number of bytes in the transmission body.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

ssize httpFormatResponseBody (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  title | Title string to format into the HTML transmission body.
  fmt | Printf style formatted string. This string may contain HTML tags and is not HTML encoded before sending to the user. NOTE: Do not send user input back to the client using this method. Otherwise you open large security holes.
  ... | Arguments for fmt.

Returns:
  A count of the number of bytes in the transmission body.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

ssize httpFormatResponsev (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  fmt | Printf style formatted string. This string may contain HTML tags and is not HTML encoded before sending to the user. NOTE: Do not send user input back to the client using this method. Otherwise you open large security holes.
  args | Varargs style list of arguments.

Returns:
  A count of the number of bytes in the transmission body.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

int httpIsChunked (HttpConn *conn)

Return whether transfer chunked encoding will be used on this request.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  True if chunk encoding will be used.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

int httpIsFinalized (HttpConn *conn)

Test if request has been finalized.

Description:
  This call tests if httpFinalize has been called.

Parameters:

  conn | HttpConn connection object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

int httpIsOutputFinalized (HttpConn *conn)

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:

  conn | HttpConn connection object.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

bool httpNeedRetry (HttpConn *conn, char **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:

  conn | HttpConn connection object created via httpCreateConn
  url | Reference 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:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpRedirect (HttpConn *conn, int status, cchar *uri)

Redirect the client.

Description:
  Redirect the client to a new uri.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  status | Http status code to send with the response.
  uri | New uri for the client.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

int httpRemoveHeader (HttpConn *conn, cchar *key)

Remove a header from the transmission.

Description:
  Remove a header if present.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  key | Http response header key.

Returns:
  "Zero" if successful, otherwise a negative MPR error code.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpSetContentLength (HttpConn *conn, MprOff length)

Define a content length header in the transmission.

This will define a "Content-Length: NNN" request header and set Tx.length

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  length | Numeric value for the content length header.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpSetContentType (HttpConn *conn, cchar *mimeType)

Set the transmission (response) content mime type.

Description:
  Set the mime type Http header in the transmission.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  mimeType | Mime type string.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpSetCookie (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  name | Cookie name.
  value | Cookie value.
  path | URI path to which the cookie applies.
  domain | Domain in which the cookie applies. Must have 2-3 dots.
  lifespan | Duration for the cookie to persist in msec.

  flags

  Cookie 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. See RFC 6265 for details about the 'Secure' and 'HttpOnly' cookie attributes.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpSetEntityLength (HttpConn *conn, MprOff len)

Define the length of the transmission content.

When static content is used for the transmission body, defining the entity length permits the request pipeline to know when all the data has been sent

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  len | Transmission body length in bytes.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, 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, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpSetHeader (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  key | Http response header key.
  fmt | Printf style formatted string to use as the header key value.
  ... | Arguments for fmt.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpSetHeaderString (HttpConn *conn, 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:

  conn | HttpConn connection object created via httpCreateConn
  key | Http response header key.
  value | String value for the key.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpSetResponded (HttpConn *conn)

Set the responded flag for the request.

Description:
  This call sets the requests responded status. Once status has been defined, headers generated or some output has been generated, the request is regarded as having "responded" in-part to the client.

Parameters:

  conn | HttpConn connection object.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetStatus, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpSetStatus (HttpConn *conn, int status)

Set a Http response status.

Description:
  Set the Http response status for the request. This defaults to 200 (OK).

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  status | Http status code.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSocketBlocked, httpWait, httpWriteHeaders, httpWriteUploadData

void httpSocketBlocked (HttpConn *conn)

Indicate that the transmission socket is blocked.

Parameters:

  conn | Http connection object created via httpCreateConn

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpWait, httpWriteHeaders, httpWriteUploadData

int httpWait (HttpConn *conn, int state, MprTicks timeout)

Wait for the connection to achieve the requested state.

Description:
  This call blocks until the connection reaches the desired state. It creates a wait handler and services any events while waiting. This is useful for blocking client requests.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  state | HTTP_STATE_XXX to wait for.
  timeout | Timeout in milliseconds to wait. Set to -1 to use the default inactivity timeout. Set to zero to wait for ever.

Returns:
  "Zero" if successful. Otherwise return a negative MPR error code. Specific returns include: MPR_ERR_TIMEOUT and MPR_ERR_BAD_STATE.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWriteHeaders, httpWriteUploadData

void httpWriteHeaders (HttpQueue *q, HttpPacket *packet)

Write the transmission headers into the given 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:

  q | Queue owning the packet.
  packet | Packet into which to place the headers.

API Stability:
  Stable.

See Also:
  HttpConn, HttpRx, HttpTx, httpAddHeader, httpAddHeaderString, httpAppendHeader, httpAppendHeaderString, httpConnect, httpCreateTx, httpDestroyTx, httpFinalize, httpFinalize, httpFlush, httpFollowRedirects, httpFormatError, httpFormatResponse, httpFormatResponseBody, httpFormatResponsev, httpIsChunked, httpIsOutputFinalized, httpNeedRetry, httpRedirect, httpRemoveHeader, httpSetContentLength, httpSetContentType, httpSetCookie, httpSetEntityLength, httpSetHeader, httpSetHeaderString, httpSetResponded, httpSetStatus, httpSocketBlocked, httpWait, httpWriteUploadData

# HttpUploadFile

HttpUploadFile

Upload File.

Description:
  Each uploaded file has an HttpUploadedFile entry. This is managed by the upload handler.

API Stability:
  Evolving.

See Also:
  httpAddUploadFile, httpRemoveAllUploadedFiles, httpRemoveUploadFile

API Stability:
  Internal.

Fields:

  cchar * |  | clientFilename | Client side name of the file.
  cchar * |  | contentType | Content type.
  cchar * |  | filename | Local (temp) name of the file.
  ssize |  | size | Uploaded file size.

void httpAddUploadFile (HttpConn *conn, cchar *id, HttpUploadFile *file)

Add an Uploaded file.

Description:
  Add an uploaded file to the Rx.files collection.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  id | Unique identifier for the file.
  file | Instance of HttpUploadFile.

API Stability:
  Internal.

See Also:
  httpRemoveAllUploadedFiles, httpRemoveUploadFile

void httpRemoveAllUploadedFiles (HttpConn *conn)

Remove all uploaded files.

Description:
  Remove all uploaded files from the temporary file store.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Internal.

See Also:
  httpAddUploadFile, httpRemoveUploadFile

void httpRemoveUploadFile (HttpConn *conn, cchar *id)

Remove an uploaded file.

Description:
  Remove an uploaded file from the temporary file store.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  id | Identifier used with httpAddUploadFile for the file.

API Stability:
  Internal.

See Also:
  httpAddUploadFile, httpRemoveAllUploadedFiles

# 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:
  HttpConn, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString

API Stability:
  Internal.

Fields:

  char * |  | ext | Document extension.
  char * |  | host | Host name.
  char * |  | path | Uri path (without scheme, host, query or fragements).
  int |  | port | Port number.
  char * |  | query | Query string.
  char * |  | reference | Reference fragment within the specified resource.
  char * |  | scheme | URI scheme (http|https|...).
  int |  | secure | Using https.
  char * |  | uri | Original URI (not decoded).
  int |  | webSockets | Using web sockets.

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:

  base | Base URI to copy.
  flags | Set 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:
  HttpConn, 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:

  uri | URI to complete.
  other | Other URI to supply the missing components.

Returns:
  The supplied URI.

API Stability:
  Stable.

See Also:
  HttpConn, 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:

  uri | Uri string to parse.
  flags | Set 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:
  HttpConn, 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:

  scheme | The URI scheme. This is typically "http" or "https".
  host | The URI host name portion. This can be a textual host and domain name or it can be an IP address.
  port | The URI port number. Set to zero to accept the default value for the selected scheme.
  path | The URI path to the requested document.
  reference | URI reference with an HTML document. This is the URI component after the "#" in the URI path.
  query | URI query component. This is the URI component after the "?" in the URI.
  flags | Set 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:
  HttpConn, 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:

  scheme | Protocol string for the uri. Example: "http".
  host | Host or IP address.
  port | TCP/IP port number.
  path | URL path.
  ref | URL reference fragment.
  query | Additiona query parameters.
  flags | Set 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:
  HttpConn, 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:
  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:

  base | The base URI considered to be the current URI. Think of this as the current directory.
  target | The destination URI for which a relative URI will be crafted to reach.
  clone | If 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:
  HttpConn, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri, httpUriToString

HttpUri * httpJoinUri (HttpUri *base, int argc, HttpUri **others)

Join URIs.

Parameters:

  base | Base URI to being with.
  argc | Count of URIs in others.
  others | Array of URIs to join to the base.

Returns:
  The resulting, joined URI.

API Stability:
  Stable.

See Also:
  HttpConn, 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:

  result | URI that will be modified with a joined path.
  base | URI supplying the base path.
  other | Other URI whose path is joined to the base.

Returns:
  The result URI.

API Stability:
  Stable.

See Also:
  HttpConn, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, 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:

  ext | Path or extension to examine.

Returns:
  Mime type. This is a static string.

API Stability:
  Stable.

See Also:
  HttpConn, 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:

  uri | URI to modify.

Returns:
  The given URI.

API Stability:
  Stable.

See Also:
  HttpConn, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpNormalizeUriPath, httpResolveUri, httpUriToString

void httpNormalizeUri (HttpUri *uri)

Normalize a URI.

Description:
  Validate and canonicalize a URI. This invokes httpNormalizeUriPath to normalize the URI path.

Parameters:

  uri | URI object to normalize.

API Stability:
  Stable.

See Also:
  HttpConn, 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 "./" sequences and simplifies "../dir" references.

Parameters:

  uri | Uri path string to normalize. This is the URI path portion without scheme, host and port components.

Returns:
  A new validated uri string.

API Stability:
  Stable.

See Also:
  HttpConn, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpResolveUri, httpUriToString

HttpUri * httpResolveUri (HttpUri *base, int argc, HttpUri **others, bool local)

Resolve URIs relative to a base.

Parameters:

  base | Base URI to begin with.
  argc | Count of URIs in the others array.
  others | Array of URIs that are sucessively resolved relative to the base.
  local | If true, the base scheme, host and port are ignored.

API Stability:
  Stable.

See Also:
  HttpConn, 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:

  uri | A Uri object created via httpCreateUri.
  flags | Set 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:
  HttpConn, httpCloneUri, httpCompleteUri, httpCreateUri, httpCreateUriFromParts, httpFormatUri, httpGetRelativeUri, httpJoinUri, httpJoinUriPath, httpLookupMimeType, httpMakeUriLocal, httpNormalizeUriPath, httpResolveUri

# 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, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed

API Stability:
  Internal.

Fields:

  char * |  | closeReason | Reason for closure.
  int |  | closeStatus | Close status provided by peer.
  int |  | closing | Started closing sequnce.
  HttpPacket * |  | currentFrame | Pending message frame.
  HttpPacket * |  | currentMessage | Pending message frame.
  uchar |  | dataMask[4] | Mask for data.
  ssize |  | frameLength | Length of the current frame.
  int |  | frameState | Message frame state.
  int |  | maskOffset | Offset in dataMask.
  ssize |  | messageLength | Length of the current message.
  MprEvent * |  | pingEvent | Ping timer event.
  int |  | state | State.
  char * |  | subProtocol | Application level sub-protocol.

char * httpGetWebSocketCloseReason (HttpConn *conn)

Get the close reason supplied by the peer.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  The reason string supplied by the peer when closing the web socket.

API Stability:
  Evolving.

See Also:
  httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed

ssize httpGetWebSocketMessageLength (HttpConn *conn)

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 valid when the last frame has been received. See httpIsLastPacket

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  The size of the message.

API Stability:
  Evolving.

See Also:
  httpGetWebSocketCloseReason, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed

char * httpGetWebSocketProtocol (HttpConn *conn)

Get the selected web socket protocol selected by the server.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  The web socket protocol string.

API Stability:
  Evolving.

See Also:
  httpGetWebSocketCloseReason, httpGetWebSocketMessageLength, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed

ssize httpGetWebSocketState (HttpConn *conn)

Get the WebSocket state.

Returns:
  The web socket state. Will be WS_STATE_CONNECTING, WS_STATE_OPEN, WS_STATE_CLOSING or WS_STATE_CLOSED.

API Stability:
  Evolving.

See Also:
  httpGetWebSocketCloseReason, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed

ssize httpSend (HttpConn *conn, cchar *fmt, ...)

Send a UTF-8 text message to the web socket peer.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  fmt | Printf style formatted string.
  ... | Arguments for the format.

Returns:
  Number of bytes written.

API Stability:
  Evolving.

See Also:
  httpGetWebSocketCloseReason, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSendBlock, httpSendClose, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed

ssize httpSendBlock (HttpConn *conn, int type, cchar *buf, ssize len, int flags)

Send a message of a given type to the web socket peer.

Description:
  This call operates in blocking mode by default unless the 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. The call may block for up to the inactivity timeout specified in the conn->limits->inactivityTimeout value.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  type | Web 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.
  buf | Data buffer to send.
  len | Length of buf.
  flags | Set 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.

Returns:
  Number of data message bytes written. Should equal len if successful, otherwise returns a negative MPR error code.

API Stability:
  Evolving.

See Also:
  httpGetWebSocketCloseReason, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendClose, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed

void httpSendClose (HttpConn *conn, int status, cchar *reason)

Send a close message to the web socket peer.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  status | Web socket status.
  reason | Optional 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:
  Evolving.

See Also:
  httpGetWebSocketCloseReason, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed

void httpSetWebSocketProtocols (HttpConn *conn, cchar *protocols)

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

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  protocols | Comma separated list of application-level protocols.

API Stability:
  Evolving.

See Also:
  httpGetWebSocketCloseReason, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpWebSocketOrderlyClosed

int httpUpgradeWebSocket (HttpConn *conn)

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:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  Return Zero if the connection upgrade can be requested.

API Stability:
  Evolving.

See Also:
  httpGetWebSocketCloseReason, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketProtocols, httpWebSocketOrderlyClosed

bool httpWebSocketOrderlyClosed (HttpConn *conn)

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

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  True if the web socket was orderly closed.

API Stability:
  Evolving.

See Also:
  httpGetWebSocketCloseReason, httpGetWebSocketMessageLength, httpGetWebSocketProtocol, httpGetWriteQueueCount, httpIsLastPacket, httpSend, httpSendBlock, httpSendClose, httpSetWebSocketProtocols

## Functions

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:

  uri | URI to bind with. When this URI is requested, the callback will be invoked if the procHandler is configured for the request route.
  fun | Callback function procedure.

API Stability:
  Evolving.

void * httpGetQueueData (HttpConn *conn)

Get the queue data for the connection.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

Returns:
  The private queue data object.

void httpOmitBody (HttpConn *conn)

Tell the tx to omit sending any body.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

## Typedefs

typedef int( HttpRouteProc)(HttpConn *conn, HttpRoute *route, HttpRouteOp *item).

General route procedure.

Used by targets, conditions and updates
typedef void(* HttpAskLogin)(HttpConn *conn).

AuthType callback to generate a response requesting the user login This should call httpError if such a response cannot be generated.

Parameters:

  conn | HttpConn connection object.

API Stability:
  Evolving.

See Also:
  HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

typedef int(* HttpParseAuth)(HttpConn *conn).

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

Parameters:

  conn | HttpConn connection object.

Returns:
  Zero if successful, otherwise a negative MPR error code.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpRole, HttpSetAuth, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

typedef bool(* HttpSetAuth)(HttpConn *conn).

AuthType callback to set the necessary HTTP authorization headers for a client request.

Parameters:

  conn | HttpConn connection object.

Returns:
  True if the authorization headers can be set.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpUser, HttpVerifyUser, HttpVerifyUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

typedef bool(* HttpVerifyUser)(HttpConn *conn).

AuthStore callback Verify the user credentials.

Parameters:

  conn | HttpConn connection object.

Returns:
  True if the user credentials can validate.

API Stability:
  Evolving.

See Also:
  HttpAskLogin, HttpAuth, HttpAuthStore, HttpAuthType, HttpParseAuth, HttpRole, HttpSetAuth, HttpUser, httpAddAuthStore, httpAddAuthType, httpAddRole, httpAddUser, httpCanUser, httpComputeAllUserAbilities, httpComputeUserAbilities, httpCreateAuth, httpCreateRole, httpCreateUser, httpIsAuthenticated, httpLogin, httpRemoveRole, httpRemoveUser, httpSetAuthAllow, httpSetAuthAnyValidUser, httpSetAuthAutoLogin, httpSetAuthDeny, httpSetAuthForm, httpSetAuthOrder, httpSetAuthPermittedUsers, httpSetAuthQop, httpSetAuthRealm, httpSetAuthRequiredAbilities, httpSetAuthStore, httpSetAuthType

typedef void(* HttpEnvCallback)(struct HttpConn *conn).

Set environment vars callback.

Invoked per request to permit custom form var definition

API Stability:
  Stable.

See Also:
  HttpConn, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

typedef int(* HttpHeadersCallback)(void *arg).

Callback to fill headers.

Description:
  If defined, the headers callback will run before the standard response headers are generated. This gives an opportunity to pre-populate the response headers.

Parameters:

  arg | Argument provided to httpSetHeadersCallback when the callback was established.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

typedef void(* HttpIOCallback)(struct HttpConn *conn, MprEvent *event).

I/O callback for connections.

Parameters:

  conn | HttpConn object created via httpCreateConn
  event | Event object describing the I/O event.

API Stability:
  Evolving.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

typedef int(* HttpListenCallback)(struct HttpEndpoint *endpoint).

Listen callback.

Invoked after listening on a socket endpoint

Returns:
  "Zero" if the listening endpoint can be opened for service. Otherwise, return a negative MPR error code.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

typedef void(* HttpNotifier)(struct HttpConn *conn, int event, int arg).

Connection Http 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 connection object has changed state. See conn->state.
  - HTTP_EVENT_READABLE. The input queue has I/O to read. See conn->readq. Use httpRead to read the data. For WebSockets, use httpGetPacket.
  - HTTP_EVENT_WRITABLE. The output queue is now writable.
  - HTTP_EVENT_ERROR. The connection or request has an error.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  event | Http state.
  arg | Per-event information.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

typedef cchar*(* HttpRedirectCallback)(struct HttpConn *conn, int *code, struct HttpUri *uri).

Define an callback for IO events on this connection.

Description:
  The event callback will be invoked in response to I/O events.

Parameters:

  conn | HttpConn connection object created via httpCreateConn
  fn | Callback function.
  arg | Data argument to provide to the callback function.

Returns:
  The redirected URI string to use.

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

typedef void(* HttpTimeoutCallback)(struct HttpConn *conn).

Timeout callback.

Description:
  The timeout callback for the request inactivity and duration timeouts.

Parameters:

  conn | HttpConn connection object created via httpCreateConn

API Stability:
  Stable.

See Also:
  HttpConn, HttpEnvCallback, HttpListenCallback, HttpNotifier, HttpQueue, HttpRedirectCallback, HttpRx, HttpStage, HttpTx, httpAfterEvent, httpCallEvent, httpCloseConn, httpConnTimeout, httpCreateConn, httpCreateRxPipeline, httpCreateTxPipeline, httpDestroyConn, httpDestroyPipeline, httpDiscardData, httpDisconnect, httpEnableUpload, httpError, httpEvent, httpFinalizeConnector, httpGetAsync, httpGetChunkSize, httpGetConnContext, httpGetConnHost, httpGetError, httpGetExt, httpGetKeepAliveCount, httpGetMoreOutput, httpGetWriteQueueCount, httpMatchHost, httpMemoryError, httpPrepClientConn, httpResetCredentials, httpRouteRequest, httpServiceQueues, httpSetAsync, httpSetChunkSize, httpSetConnContext, httpSetConnHost, httpSetConnNotifier, httpSetCredentials, httpSetKeepAliveCount, httpSetProtocol, httpSetRetries, httpSetSendConnector, httpSetState, httpSetTimeout, httpSetTimestamp, httpShouldTrace, httpStartPipeline

typedef ssize(* HttpFillProc)(struct HttpQueue *q, struct HttpPacket *packet, MprOff pos, ssize size).

Callback procedure to fill a packet with data.

Parameters:

  q | Queue owning the packet.
  packet | The packet to fill.
  off | Offset in the packet to fill with data.
  size | Size 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

HttpAuthStore

Password backend store.

API Stability:
  Internal.

Fields:

  char * |  | name | Authentication password store name: 'system', 'file'.

HttpAuthType

Authentication Protocol.

API Stability:
  Internal.

Fields:

  HttpAskLogin |  | askLogin | Callback to generate a client login response.
  char * |  | name | Authentication protocol name: 'basic', 'digest', 'post'.
  HttpParseAuth |  | parseAuth | Callback to parse the HTTP authentication headers.
  HttpSetAuth |  | setAuth | Callback to set the HTTP response authentication headers.

HttpLang

Language definition record for routes.

API Stability:
  Internal.

Fields:

  int |  | flags | 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.
  int |  | flags | Route flags to control freeing mdata.
  void * |  | mdata | pcre_ data managed by malloc().
  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.
  char * |  | name | User name.
  char * |  | password | User password.
  char * |  | roles | Original list of roles.

API Stability:
  Internal.

© Embedthis Software LLC, 2003-2013. All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.