Detailed Description

Collaboration diagram for HttpStack:

Modules
	HttpUpload
	HttpUpload is a collection of classes that makes it easy to implement a remote file manager.

Classes
struct	HttpAsynchReq
	Asynchronously receive data in a resource such as HttpDir or HttpPage. More...

struct	HttpAsynchReqResp
	Simultaneously receive and send a stream of data. More...

struct	HttpAsynchResp
	Send data asynchronously to a client. More...

struct	HttpRecData
	The HttpRecData class makes it easy to upload packets or large data chunks when using Barracuda in multithread mode. More...

struct	MultipartUpload
	Parser for multipart/form-data POST requests. More...

Macros
#define	HttpAsynchReq_getPacketSizeLeft(o) (o)->packetSizeLeft

#define	HttpAsynchReq_getBuffer(o) (o)->buffer

#define	HttpAsynchReq_getBufferSize(o) (o)->bufferSize

#define	HttpAsynchReq_isChunkEncoding(o) (o)->chunkEncoding

#define	HttpAsynchReq_getServer(o) HttpConnection_getServer((HttpConnection*)(o))

#define	HttpAsynchReqResp_destructor(o)
	Close the response and destroy receive state; free neither object nor buffers. More...

#define	HttpAsynchReqResp_getPacketSizeLeft(o) HttpAsynchReq_getPacketSizeLeft((HttpAsynchReq*)o)

#define	HttpAsynchReqResp_getBuffer(o) HttpAsynchReq_getBuffer((HttpAsynchReq*)o)

#define	HttpAsynchReqResp_getBufferSize(o) HttpAsynchReq_getBufferSize((HttpAsynchReq*)o)

#define	HttpAsynchReqResp_isChunkEncoding(o) HttpAsynchReq_isChunkEncoding((HttpAsynchReq*)o)

#define	HttpAsynchReqResp_calcPacketSize(req) HttpAsynchReq_calcPacketSize(req)
	Inspect the request's body framing without consuming it. More...

#define	HttpAsynchReqResp_getCon(o) ((o))->resp.con

#define	HttpAsynchReqResp_getMutex(o)

#define	HttpAsynchReqResp_getServer(o) HttpConnection_getServer(HttpAsynchReqResp_getCon(o))

#define	HttpAsynchReqResp_getResponse(o) (&(o)->resp)

#define	HttpAsynchResp_asynchThreadMode(o) ((o)->mutex=HttpAsynchResp_getMutex(o))
	Select worker-thread send behavior; see HttpAsynchResp::asynchThreadMode. More...

#define	HttpAsynchResp_destructor(o) HttpAsynchResp_close(o)
	Close the response; no status is returned. More...

#define	HttpAsynchResp_getMutex(o) SoDisp_getMutex(HttpConnection_getDispatcher((HttpConnection*)(o)))

#define	HttpAsynchResp_setConClose(o) HttpConnection_clearKeepAlive((HttpConnection*)(o))
	Disable persistent connection reuse before sending headers. More...

#define	HttpAsynchResp_setLingeringClose(o) (o)->doLingeringClose=TRUE
	Enable the lingering-close queue before sending headers. More...

#define	HttpAsynchResp_isAsynchThreadMode(o) ((o)->mutex ? TRUE : FALSE)

#define	MultipartUpload_getServer(o) HttpConnection_getServer((HttpConnection*)(o))
	Get the server supplied to the constructor. More...

Typedefs
typedef void(*	HttpAsynchReq_OnData) (struct HttpAsynchReq super, void data, S32 size)
	Receive data, completion, or an error. More...

typedef struct HttpAsynchReq	HttpAsynchReq
	Asynchronously receive data in a resource such as HttpDir or HttpPage. More...

typedef HttpAsynchReqResp	HttpAsynchReqResp
	Simultaneously receive and send a stream of data. More...

typedef HttpAsynchResp	HttpAsynchResp
	Send data asynchronously to a client. More...

typedef struct HttpRecData	HttpRecData
	The HttpRecData class makes it easy to upload packets or large data chunks when using Barracuda in multithread mode. More...

typedef void(*	MultipartUpload_EndOfReq) (struct MultipartUpload *o)
	Report the final multipart boundary. More...

typedef int(*	MultipartUpload_FormData) (struct MultipartUpload o, const char name, const char *value)
	Executed by MultipartUpload every time a form data element such as "text" is found in the multipart data stream. More...

typedef int(*	MultipartUpload_FileBegin) (struct MultipartUpload o, const char name, const char fileName, const char contentType, const char *contentTransferEncoding)
	Executed by MultipartUpload when a file is found in the multipart data stream. More...

typedef int(*	MultipartUpload_FileData) (struct MultipartUpload o, const U8 data, U16 len)
	Executed by MultipartUpload when a data chunk is available. More...

typedef void(*	MultipartUpload_Error) (struct MultipartUpload *o, MultipartUpload_ErrorType e)
	Executed by MultipartUpload if any errors are detected during parsing of the multipart data stream. More...

typedef struct MultipartUpload	MultipartUpload
	Parser for multipart/form-data POST requests. More...

Enumerations
enum	MultipartUpload_ErrorType
	Error codes used by the callback function MultipartUpload_Error in interface class MultipartUpload. More...

Functions
BA_API void	HttpAsynchReq_constructor (HttpAsynchReq o, HttpServer server, HttpAsynchReq_OnData data)
	Create an instance of HttpAsynchReq. More...

BA_API void	HttpAsynchReq_destructor (HttpAsynchReq *o)

BA_API SBaFileSize	HttpAsynchReq_calcPacketSize (HttpRequest *req)
	Inspect the request's body framing without consuming it. More...

BA_API int	HttpAsynchReq_start (HttpAsynchReq o, HttpRequest req, void *buffer, S32 bufferSize)
	Take over the request connection and start asynchronous reception. More...

BA_API void	HttpAsynchReq_stop (HttpAsynchReq *o)

BA_API HttpConnection *	HttpAsynchReq_getCon (HttpAsynchReq *o)
	Stop receiving and expose the embedded connection for handoff. More...

BA_API void	HttpAsynchReqResp_constructor (HttpAsynchReqResp o, HttpServer server, HttpAsynchReq_OnData data)
	Initialize combined receive/response state. More...

BA_API int	HttpAsynchReqResp_start (HttpAsynchReqResp o, HttpRequest req, void recBuf, S32 recBufSize, void sendBuf, S32 sendBufSize)
	Start the HttpAsynchReqResp object. More...

BA_API int	HttpAsynchReqResp_startResp (HttpAsynchReqResp o, HttpRequest req, void *sendBuf, S32 sendBufSize)
	Start response if you know that all data was received by the web-server. More...

BA_API void	HttpAsynchResp_constructor (HttpAsynchResp o, char buf, int size, HttpRequest *req)
	Initialize from a request and take over its connection. More...

BA_API void	HttpAsynchResp_constructor2 (HttpAsynchResp o, char buf, int size, HttpConnection *con)
	Initialize from a connection and take over its socket. More...

BA_API void	HttpAsynchResp_ReqRespInit (HttpAsynchResp o, char buf, int size, HttpConnection *con)
	Initialize the response half of a combined request/response object. More...

BA_API BaBool	HttpAsynchResp_isValid (HttpAsynchResp *o)
	Check the installed buffer and connection. More...

BA_API void	HttpAsynchResp_close (HttpAsynchResp *o)
	Flushes the response, if any, and checks the connection object: A valid and persistent HTTP 1.1 socket connection object is moved back into the Web-server's HTTP 1.1 HttpConnection pool such that the connection can be recycled. More...

BA_API int	HttpAsynchResp_setStatus (HttpAsynchResp o, int statusCode, const char protocol)
	Append the HTTP status line and standard Date/Server headers. More...

BA_API int	HttpAsynchResp_setHeader (HttpAsynchResp o, const char name, const char *value)
	Append a response header before starting the body. More...

BA_API int	HttpAsynchResp_sendData (HttpAsynchResp o, const void data, int pktSize, int chunkSize)
	Begin a fixed-length response body. More...

BA_API int	HttpAsynchResp_sendNextChunk (HttpAsynchResp o, const void data, int chunkSize)
	Continue the fixed-length body begun with sendData. More...

BA_API BufPrint *	HttpAsynchResp_getWriter (HttpAsynchResp *o)
	BufPrint is used when sending data of unknown length. More...

BA_API SBaFileSize	HttpRecData_valid (HttpRequest *req)
	This method validates the client HTTP request. More...

BA_API void	HttpRecData_constructor (HttpRecData o, HttpRequest req)
	The constructor is typically run by creating an object on the stack. More...

BA_API void	HttpRecData_destructor (HttpRecData *o)
	Finish reading, terminating the connection if unread body bytes remain. More...

BA_API S32	HttpRecData_read (HttpRecData o, void buf, S32 bufSize)
	Read data from socket. More...

void BA_API	MultipartUpload_constructor (MultipartUpload o, HttpServer server, MultipartUpload_EndOfReq endOfReq, MultipartUpload_FormData formData, MultipartUpload_FileBegin fileBegin, MultipartUpload_FileData fileData, MultipartUpload_Error onError, U32 bufferSize, AllocatorIntf *allocator)
	Construct a parser as described by MultipartUpload::MultipartUpload. More...

BA_API void	MultipartUpload_destructor (MultipartUpload *o)
	Detach from the dispatcher, free parsing storage, and close the embedded asynchronous connection if still owned. More...

BA_API int	MultipartUpload_start (MultipartUpload o, HttpRequest req)
	Start asynchronous multipart input, taking the request connection. More...

BA_API int	MultipartUpload_run (MultipartUpload o, HttpRequest req, BaBool setKeepAlive)
	Parse multipart input synchronously, blocking for additional bytes. More...

BA_API HttpConnection *	MultipartUpload_getCon (MultipartUpload *o)
	Detach and prepare an asynchronous connection handoff. More...

	HttpAsynchReq::HttpAsynchReq (HttpServer *server, HttpAsynchReq_OnData data)
	Create an instance of HttpAsynchReq. More...

	HttpAsynchReq::~HttpAsynchReq ()
	Stop dispatcher reception and destroy the owned connection. More...

SBaFileSize	HttpAsynchReq::getPacketSizeLeft ()
	Inspect receive progress after successful start. More...

void *	HttpAsynchReq::getBuffer ()
	Returns a pointer to the internal buffer where the received data is stored. More...

SBaFileSize	HttpAsynchReq::getBufferSize ()

bool	HttpAsynchReq::isChunkEncoding ()

static SBaFileSize	HttpAsynchReq::calcPacketSize (HttpRequest *req)
	Inspect the request's body framing without consuming it. More...

int	HttpAsynchReq::start (HttpRequest req, void buffer, S32 bufferSize)
	Take over the request connection and start asynchronous reception. More...

void	HttpAsynchReq::stop ()
	Remove active dispatcher reception, mark an active connection terminated, and clear receive-buffer state. More...

HttpConnection *	HttpAsynchReq::getCon (HttpAsynchReq *o)
	Stop dispatcher reception and obtain the connection for handoff. More...

	HttpAsynchReqResp::HttpAsynchReqResp (HttpServer *server, HttpAsynchReq_OnData onData)
	Create a HttpAsynchReqResp instance. More...

int	HttpAsynchReqResp::start (HttpRequest req, void recBuf, S32 recBufSize, void *sendBuf, S32 sendBufSize)
	Start the HttpAsynchReqResp object. More...

int	HttpAsynchReqResp::startResp (HttpRequest req, void sendBuf, S32 sendBufSize)
	Start response if you know that all data was received by the web-server. More...

ThreadMutex *	HttpAsynchReqResp::getMutex ()

HttpServer *	HttpAsynchReqResp::getServer ()

HttpAsynchResp *	HttpAsynchReqResp::getResponse ()

	HttpAsynchResp::HttpAsynchResp (char buf, int size, HttpRequest req)
	Initiate a HttpAsynchResp from a HttpRequest object. More...

	HttpAsynchResp::HttpAsynchResp (char buf, int size, HttpConnection con)
	Initiate a HttpAsynchResp from a HttpConnection object. More...

bool	HttpAsynchResp::isValid ()
	Check the installed buffer and connection. More...

	HttpAsynchResp::~HttpAsynchResp ()
	Calls method close. More...

void	HttpAsynchResp::close ()
	Flushes the response, if any, and checks the connection object: A valid and persistent HTTP 1.1 socket connection object is moved back into the Web-server's HTTP 1.1 HttpConnection pool such that the connection can be recycled. More...

void	HttpAsynchResp::asynchThreadMode ()
	Set in asynchronous thread mode so you can call the methods in this class using its worker-thread send path. More...

ThreadMutex *	HttpAsynchResp::getMutex ()
	Get the dispatcher lock. More...

int	HttpAsynchResp::setConClose ()
	Close connection when the HttpAsynchResp object is done. More...

int	HttpAsynchResp::setLingeringClose ()
	Request connection closure. More...

int	HttpAsynchResp::setStatus (int statusCode, const char *protocol=0)
	Append the HTTP status line and standard Date/Server headers. More...

int	HttpAsynchResp::setHeader (const char name, const char value)
	Append a response header before starting the body. More...

int	HttpAsynchResp::sendData (const void *data, int pktSize, int chunkSize)
	Begin a fixed-length response body. More...

int	HttpAsynchResp::sendNextChunk (const void *data, int chunkSize)
	Continue the fixed-length body begun with sendData. More...

BufPrint *	HttpAsynchResp::getWriter ()
	BufPrint is used when sending data of unknown length. More...

static SBaFileSize	HttpRecData::valid (HttpRequest *req)
	This method validates the client HTTP request. More...

	HttpRecData::HttpRecData (HttpRequest *req)
	The constructor is typically run by creating an object on the stack. More...

S32	HttpRecData::read (void *buf, S32 bufSize)
	Read data from socket. More...

	HttpRecData::~HttpRecData ()
	Finish using the reader. More...

	MultipartUpload::MultipartUpload (HttpServer server, MultipartUpload_EndOfReq onEndOfReq, MultipartUpload_FormData onFormData, MultipartUpload_FileBegin onFileBegin, MultipartUpload_FileData onFileData, MultipartUpload_Error onError, U32 bufferSize, AllocatorIntf allocator=0)

	MultipartUpload::~MultipartUpload ()
	Detach from the dispatcher, free parsing storage, and close the embedded asynchronous connection if still owned. More...

int	MultipartUpload::start (HttpRequest *req)
	Start asynchronous multipart input, taking the request connection. More...

int	MultipartUpload::run (HttpRequest *req, bool setKeepAlive=true)
	Parse multipart input synchronously, blocking for additional bytes. More...

HttpConnection *	MultipartUpload::getCon (MultipartUpload *o)
	Detach the asynchronous parser and release parsing buffers for a handoff. More...

HttpServer *	MultipartUpload::getServer ()
	Get the server supplied to the constructor. More...

Macro Definition Documentation

◆ HttpAsynchReq_getBuffer

#define HttpAsynchReq_getBuffer ( o ) (o)->buffer

Parameters

[in] o Initialized receiver.

Returns: Borrowed receive buffer, or NULL before start/after stop.

◆ HttpAsynchReq_getBufferSize

#define HttpAsynchReq_getBufferSize ( o ) (o)->bufferSize

Parameters

[in] o Initialized receiver.

Returns: Receive capacity in bytes, zero before start/after stop.

◆ HttpAsynchReq_getPacketSizeLeft

#define HttpAsynchReq_getPacketSizeLeft ( o ) (o)->packetSizeLeft

Parameters

[in] o Initialized receiver.

Returns: Remaining fixed-length bytes; chunked values are parsing state.

◆ HttpAsynchReq_getServer

#define HttpAsynchReq_getServer ( o ) HttpConnection_getServer((HttpConnection*)(o))

Parameters

[in] o Initialized receiver.

Returns: Borrowed server supplied at construction.

◆ HttpAsynchReq_isChunkEncoding

#define HttpAsynchReq_isChunkEncoding ( o ) (o)->chunkEncoding

Parameters

[in] o Initialized receiver.

Returns: TRUE for active chunked reception, FALSE otherwise.

◆ HttpAsynchReqResp_calcPacketSize

#define HttpAsynchReqResp_calcPacketSize ( req ) HttpAsynchReq_calcPacketSize(req)

Inspect the request's body framing without consuming it.

Parameters

[in] req Required borrowed current request.

Returns: Content-Length (zero if absent or zero); -1 if a Transfer-Encoding header is present; -2 for multipart/form-data; -3 for URL-encoded form data already handled by the server. Transfer-Encoding takes precedence in this check. The caller must ensure it denotes chunked encoding. Use MultipartUpload for multipart bodies. Even if the receive buffer fits the complete body, expect a separate completion callback after its data.

◆ HttpAsynchReqResp_destructor

#define HttpAsynchReqResp_destructor ( o )

Value:

   do {\
   HttpAsynchResp_destructor(&(o)->resp);\
   HttpAsynchReq_destructor((HttpAsynchReq*)(o));\
}while(0)

Close the response and destroy receive state; free neither object nor buffers.

Parameters

[in,out] o Initialized combined receiver. May be called from OnData.

◆ HttpAsynchReqResp_getBuffer

#define HttpAsynchReqResp_getBuffer ( o ) HttpAsynchReq_getBuffer((HttpAsynchReq*)o)

Parameters

[in] o Initialized receiver.

Returns: Borrowed receive buffer, or NULL before start/after stop.

◆ HttpAsynchReqResp_getBufferSize

#define HttpAsynchReqResp_getBufferSize ( o ) HttpAsynchReq_getBufferSize((HttpAsynchReq*)o)

Parameters

[in] o Initialized receiver.

Returns: Receive capacity in bytes, zero before start/after stop.

◆ HttpAsynchReqResp_getCon

#define HttpAsynchReqResp_getCon ( o ) ((o))->resp.con

Parameters

[in] o Initialized combined receiver.

Returns: Borrowed response connection, possibly NULL before initialization.

◆ HttpAsynchReqResp_getMutex

#define HttpAsynchReqResp_getMutex ( o )

Value:

SoDisp_getMutex(HttpConnection_getDispatcher( \

HttpAsynchReqResp_getCon(o)))

HttpConnection_getDispatcher

#define HttpConnection_getDispatcher(o)

Definition: HttpConnection.h:130

SoDisp_getMutex

#define SoDisp_getMutex(o)

Definition: SoDisp.h:215

HttpAsynchReqResp_getCon

#define HttpAsynchReqResp_getCon(o)

Definition: HttpAsynchReq.h:433

Parameters

[in] o Initialized combined receiver.

Returns: Borrowed dispatcher mutex; requires an initialized response connection.

◆ HttpAsynchReqResp_getPacketSizeLeft

#define HttpAsynchReqResp_getPacketSizeLeft ( o ) HttpAsynchReq_getPacketSizeLeft((HttpAsynchReq*)o)

Parameters

[in] o Initialized receiver.

Returns: Remaining fixed-length bytes; chunked values are parsing state.

◆ HttpAsynchReqResp_getResponse

#define HttpAsynchReqResp_getResponse ( o ) (&(o)->resp)

Parameters

[in] o Initialized combined receiver.

Returns: Borrowed embedded response; use only after start/startResp.

◆ HttpAsynchReqResp_getServer

#define HttpAsynchReqResp_getServer ( o ) HttpConnection_getServer(HttpAsynchReqResp_getCon(o))

Parameters

[in] o Initialized combined receiver.

Returns: Borrowed server; requires an initialized response connection.

◆ HttpAsynchReqResp_isChunkEncoding

#define HttpAsynchReqResp_isChunkEncoding ( o ) HttpAsynchReq_isChunkEncoding((HttpAsynchReq*)o)

Parameters

[in] o Initialized receiver.

Returns: TRUE for active chunked reception, FALSE otherwise.

◆ HttpAsynchResp_asynchThreadMode

#define HttpAsynchResp_asynchThreadMode ( o ) ((o)->mutex=HttpAsynchResp_getMutex(o))

Select worker-thread send behavior; see HttpAsynchResp::asynchThreadMode.

Parameters

[in,out] o Initialized response, used by one application thread.

◆ HttpAsynchResp_destructor

#define HttpAsynchResp_destructor ( o ) HttpAsynchResp_close(o)

Close the response; no status is returned.

Parameters

[in,out] o Initialized response. Does not free o or borrowed storage.

See also: HttpAsynchResp::close

◆ HttpAsynchResp_getMutex

#define HttpAsynchResp_getMutex ( o ) SoDisp_getMutex(HttpConnection_getDispatcher((HttpConnection*)(o)))

Parameters

[in] o Response with an initialized dispatcher association.

Returns: Borrowed dispatcher mutex, possibly NULL; does not acquire it.

◆ HttpAsynchResp_isAsynchThreadMode

#define HttpAsynchResp_isAsynchThreadMode ( o ) ((o)->mutex ? TRUE : FALSE)

Parameters

[in] o Initialized response.

Returns: TRUE when a worker-thread mutex pointer has been installed, FALSE otherwise (including a server with no mutex).

◆ HttpAsynchResp_setConClose

#define HttpAsynchResp_setConClose ( o ) HttpConnection_clearKeepAlive((HttpConnection*)(o))

Disable persistent connection reuse before sending headers.

Parameters

[in,out] o Initialized standalone response.

Returns: Zero (assigned flag), not an I/O status.

◆ HttpAsynchResp_setLingeringClose

#define HttpAsynchResp_setLingeringClose ( o ) (o)->doLingeringClose=TRUE

Enable the lingering-close queue before sending headers.

Use when terminating an upload that still has unread incoming bytes.

Parameters

[in,out] o Initialized response.

Returns: TRUE (assigned flag), not an I/O status. Unlike the current C++ wrapper, this macro sets the lingering-close flag.

◆ MultipartUpload_getServer

#define MultipartUpload_getServer ( o ) HttpConnection_getServer((HttpConnection*)(o))

Get the server supplied to the constructor.

Returns: Non-NULL borrowed server pointer; ownership does not change.

Parameters

o	Required initialized parser.

Typedef Documentation

◆ HttpAsynchReq

typedef struct HttpAsynchReq HttpAsynchReq

Asynchronously receive data in a resource such as HttpDir or HttpPage.

An instance of the HttpAsynchReq class can be used as a method to receive any kind of data from a client as long as the client does not send the data as a multipart/form-data. A resource receiving multipart/form-data must use the MultipartUpload class.

You typically create an instance of this class in a resource when receiving a request. You can optionally keep instances of this class in a pool. The object is started by calling method start.

HttpAsynchReq is an abstract base class; thus, you must inherit and implement the socket event method. See constructor for how to install the event function.

The detached socket object is installed directly into the SoDisp object, and any socket event is directed to this object. The callback installed by the constructor receives body data and terminal notifications; see HttpAsynchReq_OnData.

See also: HttpRecData

◆ HttpAsynchReq_OnData

typedef void(* HttpAsynchReq_OnData) (struct HttpAsynchReq *super, void *data, S32 size)

Receive data, completion, or an error.

Parameters

[in,out]	super	Borrowed receiver; upcast to the application's containing type when appropriate. Calls can occur within start or later in the dispatcher.
[in]	data	Borrowed bytes, valid only during the callback. Copy retained data. NULL with size zero means completion. Non-NULL with size zero is the preliminary Expect notification before the library sends 100 Continue.
[in]	size	Positive byte count, zero as described above, or a negative error with NULL data: -1 receive failure, -10 malformed chunk framing, -11 chunk header does not fit the receive buffer. Fixed-length bodies are delivered when the buffer fills or the body ends; chunked bodies can produce smaller callbacks. A completion notification is separate from the final positive-length data callback. On completion or error, destroy the receiver or use getCon to transfer its connection to response handling. Do not merely retain an idle receiver: some chunked paths require that the callback terminates receive processing. Destruction from the callback is supported; do not access it afterward.

◆ HttpAsynchReqResp

typedef HttpAsynchReqResp HttpAsynchReqResp

Simultaneously receive and send a stream of data.

The HttpAsynchReqResp class makes it possible to asynchronously receive and send data at the same time. The HttpAsynchReqResp can also be used as a replacement for using a HttpAsynchReq and HttpAsynchResp object. An HttpAsynchReqResp instance is easier to use than first using a HttpAsynchReq object for receiving data and then later using a HttpAsynchResp for sending a response message.

◆ HttpAsynchResp

typedef HttpAsynchResp HttpAsynchResp

Send data asynchronously to a client.

Please see the HTTP protocol stack for an introduction to the HttpAsynchResp class.

You must lock the dispatcher prior to calling any methods in the HttpAsynchResp class unless the object is used from within a Barracuda event callback or you have called method HttpAsynchResp::asynchThreadMode. See using multiple threads in the Barracuda introduction for more information on protecting the Barracuda code.

There is one exception to the above. You can call method HttpAsynchResp::getMutex without locking the dispatcher first. You cannot lock the dispatcher unless you first have a reference to the dispatcher object.

example code

while(sendData)
{
   ThreadLock lock(myAsynchResp->getMutex()); // Keep the lock until scope exit.
   BufPrint* writer = myAsynchResp->getWriter();
   if(!writer || writer->printf("Hi client") < 0)
      break; // Stop producing output after a failure.
} 

Certain restrictions apply to how you can use this object. This is, after all, a lightweight version of HttpResponse. The HttpAsynchResp object does not have large buffers for storing out data. Thus, the methods must be called in the following order:

Calling methods setConClose, setStatus, and setHeader are optional.

Calling method setHeader implicitly calls method setStatus with status code 200 unless you already called setStatus.

Sending data using method sendData or the methods in BufPrint flushes the HTTP header. Thus, you cannot call method setHeader after the HTTP header is flushed.

You must use one of BufPrint or ( HttpAsynchResp::sendData [ & HttpAsynchResp::sendNextChunk ] ) when sending response data.

◆ HttpRecData

typedef struct HttpRecData HttpRecData

The HttpRecData class makes it easy to upload packets or large data chunks when using Barracuda in multithread mode.

This class gives similar functionality to HttpAsynchReq and makes it possible to receive any kind of data sent from a client in a CSP page or in a HttpDir/HttpPage.

CSP example

<%p
if(HttpRecData::valid(request) >=0)
{
   HttpRecData rd(request); //Create on stack inside a CSP page.
   char buf[1500];
   S32 len;
   while( (len = rd.read(buf, sizeof(buf))) > 0)
   {
      // Consume exactly len bytes; the buffer is not NUL-terminated.
   }
   if(len < 0)
      response->printf("failed");
   else
      response->printf("OK");
}
else
{
   response->setStatus(400); // The body format is not supported here.
}
%>

◆ MultipartUpload

typedef struct MultipartUpload MultipartUpload

Parser for multipart/form-data POST requests.

Each field is delivered through formData; files are delivered through fileBegin and fileData callbacks. File bytes are streamed rather than stored as one complete file. Field values must fit in the parser's working storage. The parser does not create files or decode Content-Transfer-Encoding values.

Use start() for dispatcher-driven input or run() for blocking input. All five callbacks are required. Callback cleanup rules differ between these modes: asynchronous completion/error must detach or destroy the parser; synchronous callbacks must keep its storage alive until run() returns. Do not reuse one parser concurrently or switch a completed blocking instance to asynchronous mode.

◆ MultipartUpload_EndOfReq

typedef void(* MultipartUpload_EndOfReq) (struct MultipartUpload *o)

Report the final multipart boundary.

Parameters

o	Parser whose request has completed. This callback returns no value. In asynchronous mode, destroy the parser or call MultipartUpload_getCon() to detach it and transfer the connection. In synchronous run() mode, leave the object alive until run() returns; getCon() is unavailable in that mode.

◆ MultipartUpload_Error

typedef void(* MultipartUpload_Error) (struct MultipartUpload *o, MultipartUpload_ErrorType e)

Executed by MultipartUpload if any errors are detected during parsing of the multipart data stream.

This method must call the MultipartUpload destructor or call MultipartUpload::getCon.

Parameters

o	the object
e	is the error code. The callback returns no value. In synchronous run() mode, leave the object alive and let run() return before freeing it. Not every initialization failure invokes onError; always check the start()/run() result as well.

◆ MultipartUpload_FileBegin

typedef int(* MultipartUpload_FileBegin) (struct MultipartUpload *o, const char *name, const char *fileName, const char *contentType, const char *contentTransferEncoding)

Executed by MultipartUpload when a file is found in the multipart data stream.

Parameters

o	the object
name	the name as specified in the HTML "input" type.
fileName	is the name and possible path of the file entered by the user. The path separator is platform dependent.
contentType	is the content mime type such as "text/plain". This parameter is NULL if not specified in the multipart data stream.
contentTransferEncoding	is the part's Content-Transfer-Encoding header value. The parser does not decode this encoding. This parameter is NULL if not specified in the multipart data stream.

Returns: This function must return 0 on success. Any other value signals an error condition to the MultiPartUpload class. This method must call the MultipartUpload destructor or call MultipartUpload::getCon if returning a non zero value. All strings/data are borrowed and valid only during the callback. Copy data that must be retained. In synchronous run() mode, do not free the parser in a callback; return nonzero to stop and clean up after run() returns. A nonzero callback result becomes MultipartUpload_UserRetErr internally; it is not passed to onError as an additional notification.

◆ MultipartUpload_FileData

typedef int(* MultipartUpload_FileData) (struct MultipartUpload *o, const U8 *data, U16 len)

Executed by MultipartUpload when a data chunk is available.

The servlet first calls MultipartUpload_FileBegin and thereafter calls this method repeatedly until all data is received. End of file is signalled by setting the two input parameters to 0.

Parameters

o	the object
data	a pointer to the received data.
len	Byte count, at most 65535. data=NULL and len=0 mark the end of the current file, not the end of the complete request.

Returns: This function must return 0 on success. Any other value signals an error condition to the MultiPartUpload class. This method must call the MultipartUpload destructor or call MultipartUpload::getCon if returning a non zero value. All strings/data are borrowed and valid only during the callback. Copy data that must be retained. In synchronous run() mode, do not free the parser in a callback; return nonzero to stop and clean up after run() returns. A nonzero callback result becomes MultipartUpload_UserRetErr internally; it is not passed to onError as an additional notification.

◆ MultipartUpload_FormData

typedef int(* MultipartUpload_FormData) (struct MultipartUpload *o, const char *name, const char *value)

Executed by MultipartUpload every time a form data element such as "text" is found in the multipart data stream.

The browser bundles all data into the multipart stream sent to the server. The MultipartUpload servlet calls the formData callback function when it detects form data.

Parameters

o	the object
name	the name as specified in the HTML "input" type.
value	the text entered by the user.

Returns: This function must return 0 on success. Any other value signals an error condition to the MultiPartUpload class. This method must call the MultipartUpload destructor or call MultipartUpload::getCon if returning a non zero value. All strings/data are borrowed and valid only during the callback. Copy data that must be retained. In synchronous run() mode, do not free the parser in a callback; return nonzero to stop and clean up after run() returns. A nonzero callback result becomes MultipartUpload_UserRetErr internally; it is not passed to onError as an additional notification.

Enumeration Type Documentation

◆ MultipartUpload_ErrorType

enum MultipartUpload_ErrorType

Error codes used by the callback function MultipartUpload_Error in interface class MultipartUpload.

Function Documentation

◆ asynchThreadMode()

void HttpAsynchResp::asynchThreadMode ( )

Set in asynchronous thread mode so you can call the methods in this class using its worker-thread send path.

This does not serialize multiple application threads accessing the same response; use one owner. You must not call this method if you are calling the methods in this class from within a callback originating from the socket dispatcher SoDisp – i.e., if the mutex is already locked.

◆ calcPacketSize()

SBaFileSize HttpAsynchReq::calcPacketSize ( HttpRequest * req )

static

Inspect the request's body framing without consuming it.

Parameters

[in] req Required borrowed current request.

Returns: Content-Length (zero if absent or zero); -1 if a Transfer-Encoding header is present; -2 for multipart/form-data; -3 for URL-encoded form data already handled by the server. Transfer-Encoding takes precedence in this check. The caller must ensure it denotes chunked encoding. Use MultipartUpload for multipart bodies. Even if the receive buffer fits the complete body, expect a separate completion callback after its data.

◆ close()

void HttpAsynchResp::close ( )

Flushes the response, if any, and checks the connection object: A valid and persistent HTTP 1.1 socket connection object is moved back into the Web-server's HTTP 1.1 HttpConnection pool such that the connection can be recycled.

A non-persistent HTTP connection such as an HTTP 1.0 connection is terminated. Completes the final chunk for writer mode. This void operation does not report flush/close failure; check preceding output results. It does not free borrowed storage. No further output is allowed after close.

◆ getBuffer()

void * HttpAsynchReq::getBuffer ( )

Returns a pointer to the internal buffer where the received data is stored.

The buffer is set in method HttpAsynchReq::start.

Returns: Borrowed buffer passed to start, or NULL before start/after stop. It is not NUL-terminated; use the callback byte count.

◆ getBufferSize()

SBaFileSize HttpAsynchReq::getBufferSize ( )

Returns: Installed receive capacity in bytes, zero before start/after stop.

◆ getCon() [1/2]

HttpConnection * HttpAsynchReq::getCon ( HttpAsynchReq * o )

Stop dispatcher reception and obtain the connection for handoff.

Parameters

[in] o Unused compatibility argument in the C++ method; this method acts on its own instance. The C function uses o as its receiver.

Returns: Borrowed embedded connection pointer, never NULL for a live receiver. The connection may be invalid; use its status checks. Calling this method tells the active callback path that receive processing has ended. It does not itself move or free the connection.

This method is typically called from within the OnData event method when all data is received and you are moving the active connection object to an HttpAsynchResp object.

C code example:

HttpAsynchResp_constructor2(

resp, buf, bufSize, HttpAsynchReq_getCon(req));

HttpAsynchReq_getCon

BA_API HttpConnection * HttpAsynchReq_getCon(HttpAsynchReq *o)

Stop receiving and expose the embedded connection for handoff.

HttpAsynchResp_constructor2

BA_API void HttpAsynchResp_constructor2(HttpAsynchResp *o, char *buf, int size, HttpConnection *con)

Initialize from a connection and take over its socket.

◆ getCon() [2/2]

HttpConnection * MultipartUpload::getCon ( MultipartUpload * o )

Detach the asynchronous parser and release parsing buffers for a handoff.

Parameters

o	Unused argument retained by the C++ wrapper; the operation acts on this.

Returns: Borrowed embedded connection after detachment, or NULL in blocking mode. Move the returned connection into its new owner before destroying this parser. Detachment alone does not close or free that connection.
// In an asynchronous callback, transfer the connection to a response object.

HttpAsynchResp_constructor2(resp, buf, bufSize, MultipartUpload_getCon(upload));

MultipartUpload_getCon
BA_API HttpConnection * MultipartUpload_getCon(MultipartUpload *o)
Detach and prepare an asynchronous connection handoff.

◆ getMutex() [1/2]

ThreadMutex * HttpAsynchReqResp::getMutex ( )

Returns: Borrowed dispatcher mutex for the active response connection. Requires a successfully initialized response; does not acquire the mutex.

◆ getMutex() [2/2]

ThreadMutex * HttpAsynchResp::getMutex ( )

Get the dispatcher lock.

This is the only method in this class that can be called without locking the dispatcher.

Returns: Borrowed dispatcher mutex; NULL when the server has no mutex. Requires a properly initialized connection/dispatcher association.

◆ getPacketSizeLeft()

SBaFileSize HttpAsynchReq::getPacketSizeLeft ( )

Inspect receive progress after successful start.

Returns: For fixed-length bodies, remaining bytes not yet received, including zero at completion. For chunked bodies this is internal parsing state, not the remaining body size; use isChunkEncoding and completion callbacks instead. Before start or after failure, do not interpret it as progress.

◆ getResponse()

HttpAsynchResp * HttpAsynchReqResp::getResponse ( )

Returns: Borrowed embedded response object, not separately owned. Use only after start/startResp initializes it; check its operation results.

◆ getServer() [1/2]

struct HttpServer * HttpAsynchReqResp::getServer ( )

Returns: Borrowed server for the active response connection. Requires a successfully initialized response.

◆ getServer() [2/2]

HttpServer * MultipartUpload::getServer ( )

Get the server supplied to the constructor.

Returns: Non-NULL borrowed server pointer; ownership does not change.

◆ getWriter()

BufPrint * HttpAsynchResp::getWriter ( )

BufPrint is used when sending data of unknown length.

For a HTTP/1.1. connection, the data is sent in chunk transfer mode.

This method returns NULL if HttpAsynchResp::sendData was called prior to this method.

Returns: Borrowed embedded writer, or NULL if headers cannot be sent, fixed-length mode was selected, or the response is closed. Its storage is not separately owned. Check every writer operation. Obtaining the writer sends headers and selects body mode; it is not a read-only accessor. close finishes the response.

◆ HttpAsynchReq()

HttpAsynchReq::HttpAsynchReq	(	HttpServer *	server,
		HttpAsynchReq_OnData	data
	)

Create an instance of HttpAsynchReq.

Parameters

server	Required borrowed server, valid throughout receiver use.
data	Required callback, valid throughout receiver use. HttpAsynchReq is an abstract class and you must, therefore, implement the OnData socket event method.

◆ HttpAsynchReq_calcPacketSize()

BA_API SBaFileSize HttpAsynchReq_calcPacketSize ( HttpRequest * req )

Inspect the request's body framing without consuming it.

Parameters

[in] req Required borrowed current request.

Returns: Content-Length (zero if absent or zero); -1 if a Transfer-Encoding header is present; -2 for multipart/form-data; -3 for URL-encoded form data already handled by the server. Transfer-Encoding takes precedence in this check. The caller must ensure it denotes chunked encoding. Use MultipartUpload for multipart bodies. Even if the receive buffer fits the complete body, expect a separate completion callback after its data.

◆ HttpAsynchReq_constructor()

BA_API void HttpAsynchReq_constructor	(	HttpAsynchReq *	o,
		HttpServer *	server,
		HttpAsynchReq_OnData	data
	)

Create an instance of HttpAsynchReq.

Parameters

	server	Required borrowed server, valid throughout receiver use.
	data	Required callback, valid throughout receiver use. HttpAsynchReq is an abstract class and you must, therefore, implement the OnData socket event method.
[in,out]	o	Caller-owned receiver instance.

◆ HttpAsynchReq_destructor()

BA_API void HttpAsynchReq_destructor ( HttpAsynchReq * o )

Parameters

[in,out] o Initialized receiver; closes its owned connection and releases dispatcher registration, but does not free o or the receive buffer. May be called from OnData. See HttpAsynchReq::~HttpAsynchReq.

◆ HttpAsynchReq_getCon()

BA_API HttpConnection * HttpAsynchReq_getCon ( HttpAsynchReq * o )

Stop receiving and expose the embedded connection for handoff.

Parameters

[in,out] o Live receiver.

Returns: Borrowed non-NULL connection pointer; it may hold an invalid socket. See HttpAsynchReq::getCon for callback and transfer semantics.

◆ HttpAsynchReq_start()

BA_API int HttpAsynchReq_start	(	HttpAsynchReq *	o,
		HttpRequest *	req,
		void *	buffer,
		S32	bufferSize
	)

Take over the request connection and start asynchronous reception.

Parameters

[in,out]	req	Borrowed current request with an uncommitted response.
[in]	buffer	Caller-owned writable storage, valid until reception stops.
[in]	bufferSize	Capacity in bytes, at least 255. Chunk header lines must fit this buffer. Chunked trailer fields are not supported.

Returns: Zero when started, including when a callback already completed or destroyed the receiver. Negative on failure: -30 invalid buffer/capacity, -20 already started, -1 multipart input or committed response, -2 form input, invalid connection or failed 100 Continue, E_MALLOC pushback allocation failure, -100 other rejected body sizing. -1 can also follow a completion callback that did not destroy or hand off the receiver. Callbacks may run before return. Arrange ownership accordingly and never dereference an object destroyed by such a callback. On failure, clean up a still-live receiver; the connection may already have been taken over. Do not read the body through another API or continue using the original response after takeover. Initialize again before reusing a stopped object.

Parameters

[in,out] o Caller-owned receiver instance.

◆ HttpAsynchReq_stop()

BA_API void HttpAsynchReq_stop ( HttpAsynchReq * o )

Parameters

[in,out] o Initialized receiver. Does not free borrowed buffer storage. Use destruction for final connection cleanup.

◆ HttpAsynchReqResp()

HttpAsynchReqResp::HttpAsynchReqResp	(	HttpServer *	server,
		HttpAsynchReq_OnData	onData
	)

Create a HttpAsynchReqResp instance.

Parameters

server	Required borrowed server, valid throughout object use.
onData	Required asynchronous receive callback method. HttpAsynchReqResp inherits from HttpAsynchReq and it is the HttpAsynchReq object which calls the callback method when the internal buffer is full. End of stream is signaled by setting the two parameters to the callback to null.

◆ HttpAsynchReqResp_constructor()

BA_API void HttpAsynchReqResp_constructor	(	HttpAsynchReqResp *	o,
		HttpServer *	server,
		HttpAsynchReq_OnData	data
	)

Initialize combined receive/response state.

Parameters

[out]	o	Caller-owned object.
[in]	server	Required borrowed server, valid throughout use.
[in]	data	Required callback; see HttpAsynchReq_OnData.

◆ HttpAsynchReqResp_start()

BA_API int HttpAsynchReqResp_start	(	HttpAsynchReqResp *	o,
		HttpRequest *	req,
		void *	recBuf,
		S32	recBufSize,
		void *	sendBuf,
		S32	sendBufSize
	)

Start the HttpAsynchReqResp object.

The onData callback method is called directly if all data was received by the client; otherwise, the HttpAsynchReq object is installed into the SoDisp. The method returns a negative value if the HttpAsynchReq object failed to start. The method returns 0 if the object started successfully or if the destructor was called from within the onData callback.

Returns: The status from HttpAsynchReq::start, with the same synchronous callback and cleanup rules.

Parameters

	req	Required borrowed current request with an uncommitted response.
	recBuf	Borrowed writable receive buffer, valid until reception stops. The onData callback is called when the buffer is full.
	recBufSize	Receive capacity in bytes, at least 255.
	sendBuf	Separate borrowed writable response buffer, valid until close.
	sendBufSize	Response capacity in bytes; use at least 256. The buffers must not overlap while sending and receiving concurrently.
[in,out]	o	Caller-owned receiver instance.

◆ HttpAsynchReqResp_startResp()

BA_API int HttpAsynchReqResp_startResp	(	HttpAsynchReqResp *	o,
		HttpRequest *	req,
		void *	sendBuf,
		S32	sendBufSize
	)

Start response if you know that all data was received by the web-server.

This is a faster method than calling start if you know that the web-server received all data in its internal buffer before delegating the request to the requested service.

Parameters

[in,out]	req	Current request; caller must account for any unread body before selecting this response-only path. No receive callback runs.
[in]	sendBuf	Borrowed writable response storage, valid until close.
[in]	sendBufSize	Response capacity in bytes; use at least 256.

Returns: Zero after initialization, -1 if the response was committed, -2 if the request connection is invalid. Zero does not validate the send buffer; satisfy its preconditions and check response isValid.

Parameters

[in,out] o Caller-owned receiver instance.

◆ HttpAsynchResp() [1/2]

HttpAsynchResp::HttpAsynchResp	(	char *	buf,
		int	size,
		HttpConnection *	con
	)

Initiate a HttpAsynchResp from a HttpConnection object.

Parameters

buf	Required borrowed writable output buffer, valid until close. It is not freed by the response.
size	Output capacity in bytes. Use at least 256 (the internal minimum check is 200). For chunked writer output, usable payload capacity (size minus 8) must not exceed 65535.
con	Source connection whose active socket is moved to this object. NULL creates no active socket. Check isValid before output. For HttpAsynchReq, obtain the source with its getCon handoff method.

◆ HttpAsynchResp() [2/2]

HttpAsynchResp::HttpAsynchResp	(	char *	buf,
		int	size,
		HttpRequest *	req
	)

Initiate a HttpAsynchResp from a HttpRequest object.

Parameters

buf	Required borrowed writable output buffer, valid until close. It is not freed by the response.
size	Output capacity in bytes. Use at least 256 (the internal minimum check is 200). For chunked writer output, usable payload capacity (size minus 8) must not exceed 65535.
req	Required current request with an uncommitted response. Its active connection is moved to this object; do not use the original response afterward. Check isValid after construction.

◆ HttpAsynchResp_close()

BA_API void HttpAsynchResp_close ( HttpAsynchResp * o )

Flushes the response, if any, and checks the connection object: A valid and persistent HTTP 1.1 socket connection object is moved back into the Web-server's HTTP 1.1 HttpConnection pool such that the connection can be recycled.

A non-persistent HTTP connection such as an HTTP 1.0 connection is terminated. Completes the final chunk for writer mode. This void operation does not report flush/close failure; check preceding output results. It does not free borrowed storage. No further output is allowed after close.

Parameters

[in,out] o Initialized response.

◆ HttpAsynchResp_constructor()

BA_API void HttpAsynchResp_constructor	(	HttpAsynchResp *	o,
		char *	buf,
		int	size,
		HttpRequest *	req
	)

Initialize from a request and take over its connection.

Parameters

[out]	o	Caller-owned response storage.
[in]	buf	Required borrowed writable buffer, valid until close.
[in]	size	Capacity in bytes; use at least 256. See the C++ constructor for the chunked-writer capacity limit.
[in,out]	req	Current request with an uncommitted response. Check HttpAsynchResp_isValid after construction.

◆ HttpAsynchResp_constructor2()

BA_API void HttpAsynchResp_constructor2	(	HttpAsynchResp *	o,
		char *	buf,
		int	size,
		HttpConnection *	con
	)

Initialize from a connection and take over its socket.

Parameters

[out]	o	Caller-owned response storage.
[in]	buf	Required borrowed writable buffer, valid until close.
[in]	size	Capacity in bytes; use at least 256. See the C++ constructor for the chunked-writer capacity limit.
[in,out]	con	Source connection, or NULL for no active socket. Check HttpAsynchResp_isValid after construction.

◆ HttpAsynchResp_getWriter()

BA_API BufPrint * HttpAsynchResp_getWriter ( HttpAsynchResp * o )

BufPrint is used when sending data of unknown length.

For a HTTP/1.1. connection, the data is sent in chunk transfer mode.

This method returns NULL if HttpAsynchResp::sendData was called prior to this method.

Returns: Borrowed embedded writer, or NULL if headers cannot be sent, fixed-length mode was selected, or the response is closed. Its storage is not separately owned. Check every writer operation. Obtaining the writer sends headers and selects body mode; it is not a read-only accessor. close finishes the response.

Parameters

[in,out] o Initialized response.

◆ HttpAsynchResp_isValid()

BA_API BaBool HttpAsynchResp_isValid ( HttpAsynchResp * o )

Check the installed buffer and connection.

Returns: True if storage is installed and the connection currently reports valid, false otherwise. This cannot guarantee that a later send succeeds.

Parameters

[in,out] o Initialized response.

◆ HttpAsynchResp_ReqRespInit()

BA_API void HttpAsynchResp_ReqRespInit	(	HttpAsynchResp *	o,
		char *	buf,
		int	size,
		HttpConnection *	con
	)

Initialize the response half of a combined request/response object.

Prefer HttpAsynchReqResp_start to configure both halves together.

Parameters

[out]	o	Caller-owned response storage.
[in]	buf	Required borrowed writable buffer, valid until close.
[in]	size	Capacity in bytes; use at least 256 and respect the chunked-writer limit documented by HttpAsynchResp.
[in,out]	con	Required borrowed receive connection, valid until close; this initializer shares it instead of moving its socket.

◆ HttpAsynchResp_sendData()

BA_API int HttpAsynchResp_sendData	(	HttpAsynchResp *	o,
		const void *	data,
		int	pktSize,
		int	chunkSize
	)

Begin a fixed-length response body.

Parameters

[in]	data	Borrowed source for this call, or NULL to send headers only.
[in]	pktSize	Nonnegative total body length in bytes, fitting int.
[in]	chunkSize	Initial byte count, between zero and pktSize; provide this many readable bytes when data is non-NULL.

Returns: Zero on success, negative on header/send failure (-3 length-header formatting, -4 body send, or a propagated header error). If body mode was already selected, the call returns zero without sending anything. Call once, then sendNextChunk until exactly pktSize bytes have been supplied. Total length is the caller's responsibility; the implementation does not track remaining bytes. Do not combine this mode with getWriter.

Parameters

[in,out] o Initialized response.

◆ HttpAsynchResp_sendNextChunk()

BA_API int HttpAsynchResp_sendNextChunk	(	HttpAsynchResp *	o,
		const void *	data,
		int	chunkSize
	)

Continue the fixed-length body begun with sendData.

Parameters

[in]	data	Borrowed source containing chunkSize readable bytes.
[in]	chunkSize	Nonnegative byte count; cumulative output must not exceed the pktSize declared by sendData. This is not HTTP chunked transfer coding.

Returns: -1 if fixed-length mode has not started; otherwise the connection's send status (zero success, negative failure). No partial count is provided.

Parameters

[in,out] o Initialized response.

◆ HttpAsynchResp_setHeader()

BA_API int HttpAsynchResp_setHeader	(	HttpAsynchResp *	o,
		const char *	name,
		const char *	value
	)

Append a response header before starting the body.

Parameters

[in]	name	Required NUL-terminated HTTP field name, used during this call.
[in]	value	Required NUL-terminated field value, used during this call. Neither string may contain CR or LF. Validation is the caller's responsibility.

Returns: Zero on success; -110 after headers have ended, -2 output failure, or a negative setStatus error when emitting the default 200 status. Repeated calls append fields rather than replacing earlier fields. Leave Content-Length, Transfer-Encoding and Connection framing to this response API.

Parameters

[in,out] o Initialized response.

◆ HttpAsynchResp_setStatus()

BA_API int HttpAsynchResp_setStatus	(	HttpAsynchResp *	o,
		int	statusCode,
		const char *	protocol
	)

Append the HTTP status line and standard Date/Server headers.

Parameters

[in]	statusCode	Code recognized by HttpServer_getStatusCode; unknown codes produce its fallback text rather than a valid numeric status line.
[in]	protocol	Borrowed NUL-terminated HTTP version for this call, normally "1.1" (also selected by NULL); do not include "HTTP/" or line breaks.

Returns: Zero on success; -200 missing buffer, -100 status already selected, -11 formatting/output failure. Partial headers may already have been sent. Set status before any header or body output. The default is 200.

Parameters

[in,out] o Initialized response.

◆ HttpRecData()

HttpRecData::HttpRecData ( HttpRequest * req )

The constructor is typically run by creating an object on the stack.

Parameters

req Required borrowed request for the current command, valid until this reader is destroyed. Run valid first and handle a negative result before constructing the reader. Construction claims consumption of the body and can send a 100 Continue response. Use from a command worker thread, not the dispatcher thread. The request body must not be read concurrently by another API.

◆ HttpRecData_constructor()

BA_API void HttpRecData_constructor	(	HttpRecData *	o,
		HttpRequest *	req
	)

The constructor is typically run by creating an object on the stack.

Parameters

	req	Required borrowed request for the current command, valid until this reader is destroyed. Run valid first and handle a negative result before constructing the reader. Construction claims consumption of the body and can send a 100 Continue response. Use from a command worker thread, not the dispatcher thread. The request body must not be read concurrently by another API.
[out]	o	Caller-owned reader storage.

◆ HttpRecData_destructor()

BA_API void HttpRecData_destructor ( HttpRecData * o )

Finish reading, terminating the connection if unread body bytes remain.

Parameters

[in,out] o Initialized reader. Does not free o or its request.

See also: HttpRecData::~HttpRecData

◆ HttpRecData_read()

BA_API S32 HttpRecData_read	(	HttpRecData *	o,
		void *	buf,
		S32	bufSize
	)

Read data from socket.

Parameters

buf	Required caller-owned writable buffer of at least bufSize bytes. Returned data is binary and is not NUL-terminated.
bufSize	Positive capacity in bytes. Reads block until this many body bytes are obtained, the body ends, or an error occurs.

Returns: the length received. The method returns 0 when all data is received. The method returns a negative value if the socket connection fails or chunk framing is rejected. -1 is also returned for nonpositive bufSize or an invalid reader. On an error, no partial byte count is supplied, even if buf was partly written. Do not use the buffer contents or retry after that error. Chunked bodies with trailer fields are not supported.

Parameters

[in,out] o Initialized reader for a live command.

◆ HttpRecData_valid()

BA_API SBaFileSize HttpRecData_valid ( HttpRequest * req )

This method validates the client HTTP request.

The data received from the client must have a content-length or be chunk encoded. This is a preliminary body-type check, not complete HTTP framing validation. The caller must ensure that any Transfer-Encoding used here is chunked.

Parameters

[in] req Required borrowed request for the current command.

Returns

the content length if this is a valid request. The return value can be zero if the client sends chunk encoded data. This method returns the following error codes:

-1: No Content-Type, zero/missing Content-Length, and no Transfer-Encoding header.
-2: URL encoded data consumed by web-server.
-3: Received multipart/form-data. Use MultipartUpload.

◆ isChunkEncoding()

bool HttpAsynchReq::isChunkEncoding ( )

Returns: True if the active request is received as chunked data.

◆ isValid()

bool HttpAsynchResp::isValid ( )

Check the installed buffer and connection.

Returns: True if storage is installed and the connection currently reports valid, false otherwise. This cannot guarantee that a later send succeeds.

◆ MultipartUpload()

MultipartUpload::MultipartUpload	(	HttpServer *	server,
		MultipartUpload_EndOfReq	onEndOfReq,
		MultipartUpload_FormData	onFormData,
		MultipartUpload_FileBegin	onFileBegin,
		MultipartUpload_FileData	onFileData,
		MultipartUpload_Error	onError,
		U32	bufferSize,
		AllocatorIntf *	allocator = `0`
	)

Parameters

server	Required borrowed server; it and its dispatcher must outlive the parser.
onEndOfReq	is called when the multipart upload is completed. See MultipartUpload_EndOfReq.
onFormData	the function where you process form data. See MultipartUpload_FormData.
onFileBegin	is called when a file is found in the input stream. See MultipartUpload_FileBegin.
onFileData	is repeatedly called until end of file. See MultipartUpload_FileData.
onError	is called if an error is encountered when processing the input stream. See MultipartUpload_Error.
bufferSize	Initial buffer size and growth increment in bytes. Initialization uses at least 1024 bytes and may grow to hold buffered request data. Zero disables later growth. Growth increments above 50000 are not used by the current implementation. This is working storage, not a total file-upload size limit.
allocator	Borrowed allocator with allocation, reallocation, and free support. NULL selects AllocatorIntf_getDefault(). Keep it alive until parser destruction. The input buffer is allocated by start()/run(), not by this constructor.

◆ MultipartUpload_constructor()

void BA_API MultipartUpload_constructor	(	MultipartUpload *	o,
		HttpServer *	server,
		MultipartUpload_EndOfReq	endOfReq,
		MultipartUpload_FormData	formData,
		MultipartUpload_FileBegin	fileBegin,
		MultipartUpload_FileData	fileData,
		MultipartUpload_Error	onError,
		U32	bufferSize,
		AllocatorIntf *	allocator
	)

Construct a parser as described by MultipartUpload::MultipartUpload.

Parameters

o	Required storage to initialize.
server	Required borrowed server.
endOfReq	Required completion callback.
formData	Required form-field callback.
fileBegin	Required file-header callback.
fileData	Required file-data callback.
onError	Required error callback.
bufferSize	Initial working-buffer size and growth increment in bytes.
allocator	Borrowed allocator, or NULL for the default allocator.

◆ MultipartUpload_destructor()

BA_API void MultipartUpload_destructor ( MultipartUpload * o )

Detach from the dispatcher, free parsing storage, and close the embedded asynchronous connection if still owned.

In blocking mode the request retains its separate connection. The server and allocator are borrowed and not freed.

Parameters

o	Required initialized parser.

◆ MultipartUpload_getCon()

BA_API HttpConnection * MultipartUpload_getCon ( MultipartUpload * o )

Detach and prepare an asynchronous connection handoff.

Parameters

o	Required initialized parser on which to act.

Returns: Borrowed embedded connection, or NULL in blocking mode; see MultipartUpload::getCon.

◆ MultipartUpload_run()

BA_API int MultipartUpload_run	(	MultipartUpload *	o,
		HttpRequest *	req,
		BaBool	setKeepAlive
	)

Parse multipart input synchronously, blocking for additional bytes.

Parameters

req	Required current POST multipart/form-data request.
setKeepAlive	True (default) enables keep-alive when possible; false does not enable it. This does not force a close or override later errors.

Returns: Zero on completion while the connection remains valid; negative initialization errors as for start(), or -1 for later processing/connection failure. Callbacks receive data during this call and must not free the parser. The request retains the connection; getCon() returns NULL in this mode.

Parameters

o	Required initialized parser.

◆ MultipartUpload_start()

BA_API int MultipartUpload_start	(	MultipartUpload *	o,
		HttpRequest *	req
	)

Start asynchronous multipart input, taking the request connection.

Parameters

req	Required uncommitted POST multipart/form-data request with a live connection. The parser enables keep-alive and can send 100 Continue.

Returns: Zero when initialized or when buffered-input processing has already invoked a completion/error callback. Negative initialization results include -1 committed response, -2 invalid connection, -3 wrong method/content type, -4 boundary setup failure, -5 buffer allocation failure, and E_MALLOC for request-data pushback failure. A callback may already have handled cleanup. Callbacks can run before this function returns. Do not assume a zero result means the object is still alive or the upload succeeded.

Parameters

o	Required initialized parser.

◆ read()

S32 HttpRecData::read	(	void *	buf,
		S32	bufSize
	)

Read data from socket.

Parameters

buf	Required caller-owned writable buffer of at least bufSize bytes. Returned data is binary and is not NUL-terminated.
bufSize	Positive capacity in bytes. Reads block until this many body bytes are obtained, the body ends, or an error occurs.

Returns: the length received. The method returns 0 when all data is received. The method returns a negative value if the socket connection fails or chunk framing is rejected. -1 is also returned for nonpositive bufSize or an invalid reader. On an error, no partial byte count is supplied, even if buf was partly written. Do not use the buffer contents or retry after that error. Chunked bodies with trailer fields are not supported.

◆ run()

int MultipartUpload::run	(	HttpRequest *	req,
		bool	setKeepAlive = `true`
	)

Parse multipart input synchronously, blocking for additional bytes.

Parameters

req	Required current POST multipart/form-data request.
setKeepAlive	True (default) enables keep-alive when possible; false does not enable it. This does not force a close or override later errors.

Returns: Zero on completion while the connection remains valid; negative initialization errors as for start(), or -1 for later processing/connection failure. Callbacks receive data during this call and must not free the parser. The request retains the connection; getCon() returns NULL in this mode.

◆ sendData()

int HttpAsynchResp::sendData	(	const void *	data,
		int	pktSize,
		int	chunkSize
	)

Begin a fixed-length response body.

Parameters

[in]	data	Borrowed source for this call, or NULL to send headers only.
[in]	pktSize	Nonnegative total body length in bytes, fitting int.
[in]	chunkSize	Initial byte count, between zero and pktSize; provide this many readable bytes when data is non-NULL.

Returns: Zero on success, negative on header/send failure (-3 length-header formatting, -4 body send, or a propagated header error). If body mode was already selected, the call returns zero without sending anything. Call once, then sendNextChunk until exactly pktSize bytes have been supplied. Total length is the caller's responsibility; the implementation does not track remaining bytes. Do not combine this mode with getWriter.

◆ sendNextChunk()

int HttpAsynchResp::sendNextChunk	(	const void *	data,
		int	chunkSize
	)

Continue the fixed-length body begun with sendData.

Parameters

[in]	data	Borrowed source containing chunkSize readable bytes.
[in]	chunkSize	Nonnegative byte count; cumulative output must not exceed the pktSize declared by sendData. This is not HTTP chunked transfer coding.

Returns: -1 if fixed-length mode has not started; otherwise the connection's send status (zero success, negative failure). No partial count is provided.

◆ setConClose()

int HttpAsynchResp::setConClose ( )

Close connection when the HttpAsynchResp object is done.

A persistent HTTP 1.1 connection is recycled and sent back to the connection pool in the web-server when the HttpAsynchResp object is done. Calling this method makes sure the connection closes when the HttpAsynchResp object is done.

Returns: Zero (the assigned keep-alive flag), not a delivery status. You should call this method if you stream data such as audio.

◆ setHeader()

int HttpAsynchResp::setHeader	(	const char *	name,
		const char *	value
	)

Append a response header before starting the body.

Parameters

[in]	name	Required NUL-terminated HTTP field name, used during this call.
[in]	value	Required NUL-terminated field value, used during this call. Neither string may contain CR or LF. Validation is the caller's responsibility.

Returns: Zero on success; -110 after headers have ended, -2 output failure, or a negative setStatus error when emitting the default 200 status. Repeated calls append fields rather than replacing earlier fields. Leave Content-Length, Transfer-Encoding and Connection framing to this response API.

◆ setLingeringClose()

int HttpAsynchResp::setLingeringClose ( )

Request connection closure.

Returns: Zero, as for setConClose.

Warning: The current C++ wrapper calls setConClose and does not enable the lingering-close queue. When unread incoming data requires a lingering close, use the C macro HttpAsynchResp_setLingeringClose(thisResponse) before headers are sent. The macro and this wrapper currently have different behavior.

◆ setStatus()

int HttpAsynchResp::setStatus	(	int	statusCode,
		const char *	protocol = `0`
	)

Append the HTTP status line and standard Date/Server headers.

Parameters

[in]	statusCode	Code recognized by HttpServer_getStatusCode; unknown codes produce its fallback text rather than a valid numeric status line.
[in]	protocol	Borrowed NUL-terminated HTTP version for this call, normally "1.1" (also selected by NULL); do not include "HTTP/" or line breaks.

Returns: Zero on success; -200 missing buffer, -100 status already selected, -11 formatting/output failure. Partial headers may already have been sent. Set status before any header or body output. The default is 200.

◆ start() [1/3]

int MultipartUpload::start ( HttpRequest * req )

Start asynchronous multipart input, taking the request connection.

Parameters

req	Required uncommitted POST multipart/form-data request with a live connection. The parser enables keep-alive and can send 100 Continue.

Returns: Zero when initialized or when buffered-input processing has already invoked a completion/error callback. Negative initialization results include -1 committed response, -2 invalid connection, -3 wrong method/content type, -4 boundary setup failure, -5 buffer allocation failure, and E_MALLOC for request-data pushback failure. A callback may already have handled cleanup. Callbacks can run before this function returns. Do not assume a zero result means the object is still alive or the upload succeeded.

◆ start() [2/3]

int HttpAsynchReq::start	(	HttpRequest *	req,
		void *	buffer,
		S32	bufferSize
	)

Take over the request connection and start asynchronous reception.

Parameters

[in,out]	req	Borrowed current request with an uncommitted response.
[in]	buffer	Caller-owned writable storage, valid until reception stops.
[in]	bufferSize	Capacity in bytes, at least 255. Chunk header lines must fit this buffer. Chunked trailer fields are not supported.

Returns: Zero when started, including when a callback already completed or destroyed the receiver. Negative on failure: -30 invalid buffer/capacity, -20 already started, -1 multipart input or committed response, -2 form input, invalid connection or failed 100 Continue, E_MALLOC pushback allocation failure, -100 other rejected body sizing. -1 can also follow a completion callback that did not destroy or hand off the receiver. Callbacks may run before return. Arrange ownership accordingly and never dereference an object destroyed by such a callback. On failure, clean up a still-live receiver; the connection may already have been taken over. Do not read the body through another API or continue using the original response after takeover. Initialize again before reusing a stopped object.

◆ start() [3/3]

int HttpAsynchReqResp::start	(	HttpRequest *	req,
		void *	recBuf,
		S32	recBufSize,
		void *	sendBuf,
		S32	sendBufSize
	)

Start the HttpAsynchReqResp object.

The onData callback method is called directly if all data was received by the client; otherwise, the HttpAsynchReq object is installed into the SoDisp. The method returns a negative value if the HttpAsynchReq object failed to start. The method returns 0 if the object started successfully or if the destructor was called from within the onData callback.

Returns: The status from HttpAsynchReq::start, with the same synchronous callback and cleanup rules.

Parameters

req	Required borrowed current request with an uncommitted response.
recBuf	Borrowed writable receive buffer, valid until reception stops. The onData callback is called when the buffer is full.
recBufSize	Receive capacity in bytes, at least 255.
sendBuf	Separate borrowed writable response buffer, valid until close.
sendBufSize	Response capacity in bytes; use at least 256. The buffers must not overlap while sending and receiving concurrently.

◆ startResp()

int HttpAsynchReqResp::startResp	(	HttpRequest *	req,
		void *	sendBuf,
		S32	sendBufSize
	)

Start response if you know that all data was received by the web-server.

This is a faster method than calling start if you know that the web-server received all data in its internal buffer before delegating the request to the requested service.

Parameters

[in,out]	req	Current request; caller must account for any unread body before selecting this response-only path. No receive callback runs.
[in]	sendBuf	Borrowed writable response storage, valid until close.
[in]	sendBufSize	Response capacity in bytes; use at least 256.

Returns: Zero after initialization, -1 if the response was committed, -2 if the request connection is invalid. Zero does not validate the send buffer; satisfy its preconditions and check response isValid.

◆ stop()

void HttpAsynchReq::stop ( )

Remove active dispatcher reception, mark an active connection terminated, and clear receive-buffer state.

Does not free borrowed buffer storage. Use destruction for final connection cleanup.

◆ valid()

SBaFileSize HttpRecData::valid ( HttpRequest * req )

static

This method validates the client HTTP request.

The data received from the client must have a content-length or be chunk encoded. This is a preliminary body-type check, not complete HTTP framing validation. The caller must ensure that any Transfer-Encoding used here is chunked.

Parameters

[in] req Required borrowed request for the current command.

Returns

the content length if this is a valid request. The return value can be zero if the client sends chunk encoded data. This method returns the following error codes:

-1: No Content-Type, zero/missing Content-Length, and no Transfer-Encoding header.
-2: URL encoded data consumed by web-server.
-3: Received multipart/form-data. Use MultipartUpload.

◆ ~HttpAsynchReq()

HttpAsynchReq::~HttpAsynchReq ( )

Stop dispatcher reception and destroy the owned connection.

Does not free this object or the borrowed buffer. May be called from OnData; after a connection handoff, it does not close the moved connection.

◆ ~HttpAsynchResp()

HttpAsynchResp::~HttpAsynchResp ( )

Calls method close.

◆ ~HttpRecData()

HttpRecData::~HttpRecData ( )

Finish using the reader.

If body bytes remain unread, mark the connection terminated rather than attempting to drain them. Does not destroy the request. Destroy before its command returns.

◆ ~MultipartUpload()

MultipartUpload::~MultipartUpload ( )

Detach from the dispatcher, free parsing storage, and close the embedded asynchronous connection if still owned.

In blocking mode the request retains its separate connection. The server and allocator are borrowed and not freed.

Detailed Description

Modules

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ HttpAsynchReq_getBuffer

◆ HttpAsynchReq_getBufferSize

◆ HttpAsynchReq_getPacketSizeLeft

◆ HttpAsynchReq_getServer

◆ HttpAsynchReq_isChunkEncoding

◆ HttpAsynchReqResp_calcPacketSize

◆ HttpAsynchReqResp_destructor

◆ HttpAsynchReqResp_getBuffer

◆ HttpAsynchReqResp_getBufferSize

◆ HttpAsynchReqResp_getCon

◆ HttpAsynchReqResp_getMutex

◆ HttpAsynchReqResp_getPacketSizeLeft

◆ HttpAsynchReqResp_getResponse

◆ HttpAsynchReqResp_getServer

◆ HttpAsynchReqResp_isChunkEncoding

◆ HttpAsynchResp_asynchThreadMode

◆ HttpAsynchResp_destructor

◆ HttpAsynchResp_getMutex

◆ HttpAsynchResp_isAsynchThreadMode

◆ HttpAsynchResp_setConClose

◆ HttpAsynchResp_setLingeringClose

◆ MultipartUpload_getServer

Typedef Documentation

◆ HttpAsynchReq

◆ HttpAsynchReq_OnData

◆ HttpAsynchReqResp

◆ HttpAsynchResp

◆ HttpRecData

◆ MultipartUpload

◆ MultipartUpload_EndOfReq

◆ MultipartUpload_Error

◆ MultipartUpload_FileBegin

◆ MultipartUpload_FileData

◆ MultipartUpload_FormData

Enumeration Type Documentation

◆ MultipartUpload_ErrorType

Function Documentation

◆ asynchThreadMode()

◆ calcPacketSize()

◆ close()

◆ getBuffer()

◆ getBufferSize()

◆ getCon() [1/2]

◆ getCon() [2/2]

◆ getMutex() [1/2]

◆ getMutex() [2/2]

◆ getPacketSizeLeft()

◆ getResponse()

◆ getServer() [1/2]

◆ getServer() [2/2]

◆ getWriter()

◆ HttpAsynchReq()

◆ HttpAsynchReq_calcPacketSize()

◆ HttpAsynchReq_constructor()

◆ HttpAsynchReq_destructor()

◆ HttpAsynchReq_getCon()

◆ HttpAsynchReq_start()

◆ HttpAsynchReq_stop()

◆ HttpAsynchReqResp()

◆ HttpAsynchReqResp_constructor()

◆ HttpAsynchReqResp_start()

◆ HttpAsynchReqResp_startResp()

◆ HttpAsynchResp() [1/2]

◆ HttpAsynchResp() [2/2]

◆ HttpAsynchResp_close()

◆ HttpAsynchResp_constructor()

◆ HttpAsynchResp_constructor2()

◆ HttpAsynchResp_getWriter()

◆ HttpAsynchResp_isValid()

◆ HttpAsynchResp_ReqRespInit()

◆ HttpAsynchResp_sendData()

◆ HttpAsynchResp_sendNextChunk()