Derived from: none
Declared in: HTTPMessage.h
Library: libHTTP.so
HTTPMessage is an abstract class for representing and manipulating HTTP messages. It implements functionality common to both reqests and responses.
HTTP messages consist of a start-line followed by a variable number of headers and an optional variable length entity-body.
The HTTPMessage class does not assume any specific transport mechanism for the messages it represents. HTTPMessage objects know how to receive and send HTTP messages trough a BDataIO derived objects. All io is performed through the supplied BDataIO derived objects. As such, you can send and receive messages to and from any BDataIO derived object such as a TCP_IO or a BFile.
All message headers are stored internally and can be searched. Any entity-body is represented by a BDataIO object and does not have reside in memory; it can be read as needed.
HTTPMessage( void )
The default constructor calls InitMessage() and creates a new HTTPMessage object.
virtual ~HTTPMessage( void )
The destructor frees all internally allocated storage used by the object, including headers, and deletes the object.
virtual void InitMessage( void )
Setup the message for use or reuse. The start-line is set to a NULL string, content-length is set to 0, the body set to NULL, and any existing headers are removed.
void SetStartLine( const char *start_line ) const char *GetStartLine( void )
SetStartLine copies start_line to the the messages's internal storage for the start-line. The derived classes SetRequestLine() and SetStatusLine() methods are preferable to SetStartLine() because they interpret the line in the context of its message-type and can automatically set message-type specific attributes.
GetStartLine() returns a pointer the internally stored start-line.
void SetVersion( const char *version ) const char *GetVersion( void )
Gets and sets the HTTP version attribute of the message. The default version is "HTTP/1.1."
void AddHeader( const char *header ) void AddHeader( const char *fieldName, const char *fieldValue )
Adds a header to the message's header list. The first flavor accepts a full HTTP message-header of the form: field-name ":" [field-value]. The second flavor takes the field-name and field-value as arguments and creates the message-header for you.
bool RemoveHeader( char *headerPtr ) bool RemoveHeaderByName( const char *fieldName )
Remove a message header. The RemoveHeader() removes the header pointed to by headerPtr while RemoveHeaderByName() removes the first header with the given field-name. They return true if success and false if the header was not found.
const char *FindHeader( const char *fieldName, char *fieldValue=NULL, size_t n=0 )
Find a header by field-name. If a header with a field-name of fieldName is found, its field value is copied to fieldValue. n specifies the size of the buffer provided to fieldValue. FindHeader() returns a pointer to to the full message-header if found and NULL if it was not found.
const char *HeaderAt( int32 index )
Returns a pointer to the full message-header at the specified index if index is in range; it returns NULL if it's not in range. Indicies start at 0 and go to CountHeaders()-1.
int32 CountHeaders( void )
Returns the total number of message-headers in the message.
void FreeHeaders( void )
Removes all message headers.
void SetContentLength( int64 length ) int64 GetContentLength( void )
Get and set the content-length attribute of the message. The content -length attribute specifies the length of the entity-body. A HTTP message is not required to specify its length and this attribute is used for informational purposes only. When SendBody() is called and a message-length is not specified, the message-length is normally signalled by closure of the connection. If a message length is provided, no more than message-length bytes should be received or sent as part of the entity-body.
void SetMessageBody( BDataIO *body ) BDataIO *GetMessageBody( void )
Get and set the entity-body BDataIO object. A NULL body specifies no entity-body.
status_t DeleteMessageBody( void )
Delete the BDataIO object which represents the message body. This should not be called on a statically allocated body object.
void SetBodyBuffering( bool buffered )
SendBody() transmits the body in non-buffered mode by default. This works fine when reading from objects like BFiles. If the body is dynamically generated, such as a CGI, setting this to true will improve network performance.
virtual int32 SendMessage( BDataIO *io, bool simple = false )
Send the message using io for transport. If simple is true, a simpe HTTP message is sent. A simple request contains only a request-line without the HTTP version ( no headers are sent ) and a simple response contains only the entity-body ( no reponse-line or headers ). Simple messages are used by pre-HTTP/1.0 clients and servers. Returns number of bytes sent in the entity-body or -1 if an error occured.
virtual int32 ReceiveMessage( BDataIO *io ) = 0
This pure-virtual method should initalize the message by reading it from io. This will setup the start-line, load any HTTP message-headers and set the entity-body to io. It may also interpret the start-line and setup other message attributes. Returns the number of bytes read or -1 if an error occured.
virtual int32 SendHeaders( BDataIO *io, bool simple = false )
Write the start-line and message-headers stored in the HTTPMessage object to the BDataIO specified by io. Returns the number of bytes sent or -1 if an error occured.
virtual int32 SendBody( BDataIO *io )
If the entity-body is not NULL, up to content-length bytes are moved from the entity-body to io. If no content-length is specified, SendBody() moves data until the EOF is reached. The return value is the number of bytes actually sent or -1 if an error occured.
virtual int32 ReceiveStartLine( BDataIO *io )
Set the start-line by reading it from io. Returns the number of bytes read from io or -1 if an error occured.
virtual int32 ReceiveHeaders( BDataIO *io )
Add message-headers by reading them from io. Returns the number of bytes read or -1 if an error occured.
virtual int32 ReceiveBody( BDataIO *io )
The default implementation just calls SetMessageBody( io ) and returns 0.