public:
void Close();
If the connection is open, this function closes it; otherwise it does nothing. Connections are automatically closed when HttpStream objects are destroyed.
public:
void Connect( const string& host, int port = 0 );
This function connects to a web server with the given hostname at the given port number. If the connection fails, GetCode() will return -1 and GetMessage will return a description of what went wrong.
Name Description host The host to connect to. For convenience, this may be a domain name ("www.beunited.org") or an IP address in dotted-quad notation ("127.0.0.1"). It may also contain the port number as is specified in URLs ("www.beunited.org:80"), as long as the parameter port is 0. port The port to connect to. If port == 0, host is searched to see if it contains a port number as explained above. If not, kHttpPort is assumed.
public:
inline void EndHeaders() { Write( "\r\n", 2 ); };
You must call this function exactly once: after you've made your request and sent all of your headers. You will not get a reply until this call has been made. If you call EndHeaders before you're done sending all the headers, those that are sent afterwards will likely be ignored.
public:
inline bool Eof() { return fEof; };
You have reached the end of the stream if the connection has been closed and there is no more data left to be read.
Result: True if all the data has been read from the stream, or false if there may be more pending. Note that if the server has finished sending data but the connection has not been closed, Eof() will return false.public:
inline int GetCode() { return fCode; };
This function returns the status code sent back from the server after our request was made. For a complete listing of codes, look up RFC 2616, section 10 for a complete listing of possible result codes. The most common are 200 (OK) and 404 (Not Found).
Result: The HTTP result code sent by the server, or -1 if either a client-side error occurred (like specifying a nonexistant server or a bad port number) or the result has not yet been returned.public:
inline string GetHeader( const string& header ) { return fHeaders[ ToLower( header ) ]; };
*
Result: The value of the header, or, if the server did not send a header with that name, an empty string.public:
inline string GetMessage() { return fMessage; };
This is a message that the server sends back that provides a short description of the status code. For a complete listing look up RFC 2616, section 10. The most common are "OK" and "Not Found". Note that the strings in the RFC are only suggestions that should be used for displaying messages to the user; any decisions based on status should use the result code instead.
Result: The message sent along with the HTTP result code, or an empty string if a client-side error has occurred (bad server name or port, for example) or the result has not yet been fetched.public:
void GetReply();
You must call this function exactly once: after you've called EndHeaders() and, optionally, Write(), and before you call GetCode(), GetMessage(), GetHeader(), or any of the Read...() functions.
public:
HttpStream( const string& host = B_EMPTY_STRING, int port = 0 );
Creates an HttpStream object, optionally connecting to the given host on the given port.
Name Description host The host to connect to. If the host is not given, no connection is established until Connect() is called. port The port to connect to. If port is 0, host is searched to see if it contains a port, and if it doesn't, kHttpPort is used.
public:
void PutHeader( const string& header, const string& arg );
If you call this function, you must do so after you call PutRequest(), but before you call EndHeaders().
Name Description header The header description (ie, "User-Agent"). arg The header's value.
public:
void PutRequest( const string& request, const string& selector = "/" );
This function must be called exactly once: After the connection has been established, but before PutHeader() is called.
Name Description request What kind of request to make. This parameter is usually "GET" to receive web pages, or occasionally "PUT" to send form data. selector The requested document's path. If there is a query string, it gets put here (ie, "/cgi-bin/query.cgi?name=Dave%20Kleinschmidt").
public:
virtual ssize_t Read( void* buffer, size_t numBytes );
This function will return the next bytes available from the server, up to and including numBytes bytes. If fewer bytes are available, it will not wait for more to fill the buffer. If no data is available, this function blocks until some data has arrived, at which point that data will be delivered.
Result: The number of bytes read; 0 if the connection has been closed and no more data remains to be read.
Name Description buffer The buffer to read into. numBytes The maximum number of bytes to read into the buffer.
public:
void ReadLine( string& buffer, bool removeCr = true );
This function retrieves the next line of text from the remote host (as determined by the receipt of a line feed character), up to but not including the trailing line feed.
Name Description buffer The string to read the next line into. removeCr If the line ends in a carriage return-line feed sequence (CRLF), the CR will be removed if removeCr is true. if removeCr is false, only the LF will be removed. This is useful if you are expecting binary data.
public:
string ReadLine( bool removeCr = true );
This function retrieves the next line of text from the remote host (as determined by the receipt of a line feed character), up to but not including the trailing line feed.
Result: Returns the next line of data.
Name Description removeCr If the line ends in a carriage return-line feed sequence (CRLF), the CR will be removed if removeCr is true. if removeCr is false, only the LF will be removed. This is useful if you are expecting binary data.
public:
void ReadUntil( string& buffer, const string& line, bool removeCrs = true );
This function reads into the given buffer until a line that exactly matches the supplied line is read. If the line is never encountered, the rest of the data in the buffer is fetched. The matched line is removed from the stream.
Name Description buffer The buffer to read into. line The line to read until. removeCrs If true, lines in the buffer are guaranteed to end with only a line feed. If false, they may end with a carriage return-line feed sequence.
public:
inline void SetDebugLevel( bool debugLevel ) { fDebugLevel = debugLevel; };
If debugging is on, all sorts of miscellaneous status information is printed to stdout.
Name Description debugLevel True to turn debugging on, false to turn it off.
public:
virtual ssize_t Write( const void* buffer, size_t numBytes );
This function will send the contents of the given buffer to the remote server. Note that if you want to send data to the server, this must be called after EndHeaders() but before GetReply().
Result: The number of bytes written, which is equal to numBytes if the connection is open and the buffer was sent successfully. The result will be 0 if the connection has been closed.
Name Description buffer The buffer to write from. numBytes The number of bytes to write.
public:
~HttpStream();
Handles the destruction and cleanup of an HttpStream, closing the connection, freeing memory, etc.
public:typedef map< string, string > HeaderMap;
A data member of this type is used to hold the headers returned by the server.
public:static const size_t kBufferSize;
The value of this constant is B_PAGE_SIZE. If you want to tweak this, the value must be a multiple of B_PAGE_SIZE (4096) because areas are used to hold the incoming data.
public:static const int kHttpPort;
This is the default port that HTTP servers accept connections on (port 80).
public:static const char* const kHttpVersion;
The value of this constant is "HTTP/1.0", as HttpStream only implements the functionality of a version 1.0 client.
© 2000 BeUnited (Last Updated 5/10/2000)