Functions



Close

Abstract: Closes the HTTP connection.
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.


Connect

Abstract: Establishes a connection with a remote host.
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.

Parameters

NameDescription
hostThe 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.
portThe 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.

EndHeaders

Abstract: Signals the end of the outgoing HTTP headers.
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.


Eof

Abstract: Returns whether you've reached the end of the stream.
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.

GetCode

Abstract: Returns the HTTP result code.
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.

GetHeader

Abstract: Returns the value of a header sent back from the server.
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.

GetMessage

Abstract: Returns the HTTP reply message.
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.

GetReply

Abstract: Begins receiving the HTTP response from the remote host.
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.


HttpStream

Abstract: Default constructor.
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.

Parameters

NameDescription
hostThe host to connect to. If the host is not given, no connection is established until Connect() is called.
portThe 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.

PutHeader

Abstract: Sends an HTTP header to the server.
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().

Parameters

NameDescription
headerThe header description (ie, "User-Agent").
argThe header's value.

PutRequest

Abstract: Makes an HTTP request of the server.
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.

Parameters

NameDescription
requestWhat kind of request to make. This parameter is usually "GET" to receive web pages, or occasionally "PUT" to send form data.
selectorThe requested document's path. If there is a query string, it gets put here (ie, "/cgi-bin/query.cgi?name=Dave%20Kleinschmidt").

Read

Abstract: Reads from the HTTP connection into a buffer.
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.

Parameters

NameDescription
bufferThe buffer to read into.
numBytesThe maximum number of bytes to read into the buffer.
Result: The number of bytes read; 0 if the connection has been closed and no more data remains to be read.

ReadLine

Abstract: Reads the next line.
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.

Parameters

NameDescription
bufferThe string to read the next line into.
removeCrIf 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.

ReadLine

Abstract: Reads the next line.
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.

Parameters

NameDescription
removeCrIf 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.
Result: Returns the next line of data.

ReadUntil

Abstract: Reads until a certain line is read.
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.

Parameters

NameDescription
bufferThe buffer to read into.
lineThe line to read until.
removeCrsIf 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.

SetDebugLevel

Abstract: Turns debugging on or off.
public:

inline void SetDebugLevel( bool debugLevel ) { fDebugLevel = debugLevel; };

If debugging is on, all sorts of miscellaneous status information is printed to stdout.

Parameters

NameDescription
debugLevelTrue to turn debugging on, false to turn it off.

Write

Abstract: Sends an arbitrary string to the remote host.
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().

Parameters

NameDescription
bufferThe buffer to write from.
numBytesThe number of bytes to write.
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.

~HttpStream

Abstract: Destructor.
public:

~HttpStream();

Handles the destruction and cleanup of an HttpStream, closing the connection, freeing memory, etc.


© 2000 BeUnited — (Last Updated 5/10/2000)