Derived from: BPositionIO
Declared in: HTTP_IO.h
Library: libHTTP.so
A HTTP_Io object is a BPositionIO derived object which can perform io on a remote resource specified by a URI. Much of the interface has been modeled after the BFileIO object. Seeking has been implemented by means of HTTP byte -ranges and will work as long as the remote server supports byte-ranges. Currently only reading is supported; a later release of this library will have write support as well.
A HTTP_Io object manages the connection transparently. It will even attempt to maintain a HTTP/1.1 persistant connection ( as long as the server supports persistant connections ) accross calls to SetTo(). GET and HEAD requests will be made as needed.
The following example illustrates the use of this class:
#include "HTTP_IO.h"
#include &lb;stdio.h&rb;
status_t PrintWebObject( const char *URL )
{
HTTP_Io resource;
status_t status;
if( (status = resource.SetTo( URL, B_READ_ONLY )) == B_OK )
{
ssize_t size;
char buffer[4096];
while( (size = resource.Read( buffer, 4096 )) > 0 )
fwrite( buffer, size, 1, stdout );
fflush( stdout );
return B_OK;
}
else
return status;
}
HTTP_Io( void ) HTTP_Io( const char *URL, uint32 openMode, bool head = true )
Creates a new HTTP_Io object and initializes it. The status of the initialization can be checked with InitCheck().
The default constructor does nothing and sets InitCheck() to B_NO_INIT. The object may then be initialized with SetTo().
The other constructor passes the arguments to SetTo(). See SetTo() for more information.
virtual ~HTTP_Io( void )
Frees any internally allocated storage, closes the connection if open, and deletes the object.
status_t InitCheck( void )
Checks the state of initialization. The return value is the status of the most recent initialization. The resource specified by the URL does not have to exist for successfull initialization. See Exists.
bool Exists( void )
Verify a valid response was returned by the host specified in the URL. This method will perform a HEAD request if HEAD or GET has not been previously called. Exists() may return true even if the resource specified in the URL does not. Check the StatusCode() to verify a successfull request. If it's not a 2xx response-code, the entity-body may only contain an expanation for the error.
bool IsReadable( void ) bool IsWritable( void )
Check permissions. The permissions are set when the object is initialized with SetTo(). Currently only reading is supported. Both return false if the object has not been initialized.
virtual ssize_t Read( void *buffer, size_t numBytes ) virtual ssize_t ReadAt( off_t position, void *buffer, size_t numBytes )
Read from the resource specified by SetTo(). They read from the entity-body of the HTTP response, the headers are not included here. See the BPositionIO class for general information on their use.
-1 is returned if a failure occured such as eof or an io error. Otherwise the number of bytes successfully read is returned.
You may call Read( NULL, 0 ) if you wish to verify the response-code, examine response headers, or verify the resource size and mime-type before actaully reading the from the entity-body. This avoids the additional overhead of a HEAD request being made before the GET request.
ReadAt calls Seek() before attempting to Read(). The use of ReadAt() is discouraged because it is possible for the Seek() to fail. ReadAt() returns -1 if a Seek() failure occurs.
virtual ssize_t Write( const void *buffer, size_t numBytes ) virtual ssize_t WriteAt( off_t position, const void *buffer, size_t numBytes )
Not implementented at this time.
virtual off_t Seek( off_t position, uint32 mode ) virtual off_t Position( void )
Seek() attempts to set the position in the entity-body from which the next Read() will retrieve data. Position() returns the current offset from the start of the entity body.
Seek() may fail if the web server does not support byte-ranges. Check the return value of Seek() to verify success. Seek calls Read( NULL, 0 ) to check for success.
status_t SetTo( const char *URL, uint32 openMode, bool head = true ) void Unset( void )
Initialize the object with the specified URL and openMode. Currently B_READ_ONLY is the only supported open mode. If head is true, Exists() is called and B_ENTRY_NOT_FOUND not found will be returned if it returns false. If head is false, no attempt is made to verify the the resource exists. This may be usefull if you wish to avoid the overhead of HEAD request.
SetTo() returns B_OK on success and an error code in all other cases.
Unset() frees the internally allocated storage associated with calling SetTo() and resets InitStatus() to B_NO_INIT. It's not a given the connection will be closed if persistant connections are being used. Call CloseConnection() if you wish ensure the connection is closed. CloseConnection() will normally be called automatically as needed.
const char *GetURL( void )
Returns the URL specified in the last call to SetTo() or a null string if SetTo() has not been called.
status_t GetType( char *type ) status_t GetSize( off_t *size )
Retrieve the mime-type or content-length of the entity-body. Returns B_NO_INIT if the object has not been initialized or an error code if Exists() was not successfull. Returns B_OK if successfull.
If the mime-type was not specified in the HTTP response, a default mime-type of "application/octet-stream" is used.
If the content-length was not specified, GetSize() sets size to -1. The length of such an entity can be determined by reading until eof.
status_t GetStatusCode( int32 *statusCode ) status_t GetStatusLine( char *statusLine, int32 size )
Get the status-code or status-line of the response. Returns B_NO_INIT if the object has not been initialized or an error code if Exists() was not successfull. Returns B_OK if successfull.
Status codes in the range of 2xx indicate success. You should expect a status code of 200 for most requests or 206 if a Seek() request was successfull. Status codes in the 3xx range indicate redirection, 4xx codes indicate client errors, and 5xx indicate server errors. 404 indicates the resource specified by the URL was not found. See RFC 2068 for a detailed explanation of all possible result codes.
GetStatusLine() retrieves the status-line sent by the server. It includes
the HTTP version being used, the status code, and a human readable result phrase.
Example: HTTP/1.1 404 Not Found
const char *FindHeader( const char *fieldName, char *fieldValue=NULL, size_t n=0 ) const char *HeaderAt( int32 index )
Retrieve HTTP headers sent by the server in the response. FindHeader() searches for a header with a field-name of fieldName and places the field-value in fieldValue if the header was found. HeaderAt() retrieves the header at the specified index. Index values range from 0 to n, where n is the total number of headers -1.
Both FindHeader() and HeaderAt() return the entire header-line if found or in range respecively; otherwise, they return NULL.
A header-line has the following format:
field-name ":" [LWS] field-value
int32 CountHeaders( void )
Returns the total number of headers sent in the response.
void UseProxy( const char *proxyHost, uint16 proxyPort )
UseProxy() tells the HTTP_Io object to make the conneciton through a proxy server instead directly to the host specified in the URL. proxyHost is the network name or IP address of proxy server. proxyPort specifies the TCP port on which the proxy server accepts connections. Ususally this is 8080.
virtual void AddHeaders( void )
This protected hook method allows you to attach custom headers to the HTTP requests made by the object. The default implementation adds the header "User-Agent: libHTTP"
Headers are added by calling HTTPMessage::AddHeader(). For the purposes
of this hook method, you may add headers by the following calls:
request->AddHeader( const char *headerLine );
request->AddHeader( const char *fieldName, const char *fieldValue );