RWHttpAgent
Module: Internet Protocols Module Package: HTTP
Does not inherit
Local Index
Members
Header File
#include <rw/http/RWHttpAgent.h>
Description
RWHttpAgent handles the details of the most common HTTP requests. It calls RWHttpClient to perform these requests. RWHttpAgent uses an RWHttpClientManager to cache connections to HTTP servers, which means that requests from multiple RWHttpAgent instances can use the same underlying network connection to make requests of an HTTP server.
The default constructor creates an RWHttpAgent that uses a default, global RWHttpClientManager. For greater control, you can first create an RWHttpClientManager and then create an RWHttpAgent that uses this manager. The constructor for the manager takes parameters for the number of threads and the number of connections the manager can create, and the resulting object has methods for querying and resetting these parameters. See the RWHttpClientManager description for details.
Public Constructor
RWHttpAgent();
Constructs an RWHttpAgent that uses the default, global RWHttpClientManager instance.
RWHttpAgent(RWHttpClientManager::PointerType manager);
Constructs an RWHttpAgent that uses a supplied RWHttpClientManager instance.
Public Member Functions
void addCustomHeader(const RWHttpHeaderBase& hdr);
Adds a custom header to the internal header list of the agent. This header is sent with all outgoing requests from this agent.
RWTIOUResult<RWHttpReply> executeDelete(const RWURL& url) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the success or failure of the delete request and any information from the server concerning the delete request.
RWTIOUResult<RWHttpReply> executeGet (const RWURL& url) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the reply from the HTTP server for the requested URL.
RWTIOUResult<RWHttpReply>
executeGetIfModifiedSince(const RWURL& url,
const RWHttpDate& date) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the document associated with the URL, if it has been modified since date. Otherwise it returns a 304 (not modified) return code.
RWTIOUResult<RWHttpReply> executeGetRange(const RWURL& url, const RWHttpRange& range)
const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the reply from the HTTP server for the requested URL. Only the subrange specified by start and end will be returned.
RWTIOUResult<RWHttpReply> executeGetRange(const RWURL& url, const RWHttpRange& range,
const RWHttpDate& date) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the reply from the HTTP server for the requested URL. If the Last-Modified date for the requested URL is older than the date specified, then only the sub-range requested will be returned, otherwise the entire document associated with the URL will be returned.
RWTIOUResult<RWHttpReply> executeGetRange(const RWURL& url, const RWHttpRange& range,
const RWCString& etag) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the reply from the HTTP server for the requested URL. If the Etag for the document matches the etag parameter of the request, only the specified subrange will be returned, otherwise the entire document will be returned. The RWCString should contain 7-bit US-ASCII data.
RWTIOUResult<RWHttpReply> executeHead(const RWURL& url) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains the header information associated with the user-defined URL. The body of the document associated with the URL is not returned.
RWTIOUResult<RWHttpReply>
executeOptions(const RWURL& url, const RWHttpRequestBody&
body=RWHttpRequestStringBody()) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the options associated with the URL.
RWTIOUResult<RWHttpReply>
executeOptions(const RWCString& server, int port=80,
const RWHttpRequestBody&
body=RWHttpRequestStringBody()) const;
Deprecated; use the executeServerOptions method instead. You can refuse to support this function by defining the macro RW_DISABLE_DEPRECATED.
RWTIOUResult<RWHttpReply>
executePost(const RWURL& url,
const RWHttpRequestBody& body) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the success or failure of the POST request and the response from the server to the POST request. The body of the POST request is extracted from the body parameter.
RWTIOUResult<RWHttpReply>
executePut(const RWURL& url,
const RWHttpRequestBody& body) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the success or failure of the PUT request and any information from the server concerning the PUT request. The body of the POST request is extracted from the body parameter.
RWTIOUResult<RWHttpReply>
executeServerOptions(const RWURL& url,
const RWHttpRequestBody& body =
RWHttpRequestStringBody()) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply will contain information concerning the options associated with the server. This is equivalent to executing an OPTIONS * HTTP/1.1 request to server:port. This version uses the scheme encoded in the URL to determine the type of connection to make to the server. The path portion of the specified URL is ignored.
RWTIOUResult<RWHttpReply> executeServerTrace(const RWURL& url) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply will contain information concerning the network path that the request followed to reach the destination server. This is equivalent to executing a TRACE * HTTP/1.1 request to the server:port. This version uses the scheme encoded in the URL to determine the type of connection to make to the server. The path portion of the specified URL is ignored.
RWTIOUResult<RWHttpReply> executeTrace(const RWURL& url) const;
Returns an RWTIOUResult that can be redeemed for an RWHttpReply. The RWHttpReply contains information about the network path that the request followed to reach the destination URL.
RWTIOUResult<RWHttpReply> executeTrace(const RWCString& server, int port=80) const;
Deprecated; use the executeServerTrace method instead. You can refuse to support this function by defining the macro RW_DISABLE_DEPRECATED.
RWHttpClientManager& getClientManagerInstance() const;
Returns a reference to the underlying RWHttpClientManager instance associated with this agent.
bool getFollowRedirects() const;
Returns true if redirects are automatically followed. Otherwise returns false.
RWCString getFrom() const;
Returns the value of the internal from value. The RWCString should contain 7-bit US-ASCII data.
unsigned long getNetworkMaxWait() const;
Returns the amount of time in milliseconds that a request blocks on a socket and waits for data before deciding that the socket is dead.
bool getSendDate() const;
Returns true if a Date header is appended to outgoing requests. Otherwise returns false.
RWCString getUserAgent() const;
Returns the value of the internal User-Agent value. The RWCString should contain 7-bit US-ASCII data.
const RWHttpHeaderList& headers() const;
Returns an RWHttpHeaderList containing all of the headers that are sent with requests from this RWHttpAgent.
bool removeCustomHeader(const RWHttpHeaderBase& hdr);
Removes a header from the internal header list of the agent. If the header was not present in the RWHttpHeaderList, this function returns false.
void setFollowRedirects(bool b);
Determines whether redirect replies (those with reply codes 3XX) are automatically followed. If it is set to true then redirects are followed automatically, and the resulting document is returned instead of the document requested. If redirects are not followed, the 3XX reply from the original request is returned along with any associated message body. The default is to follow the redirects.
void setFrom(const RWCString& from);
Assigns the string from to the internal from value. If from is set to a non-empty string, an RWHttpFromHeader is attached to all requests issued from the RWHttpAgent object. The RWCString should contain 7-bit US-ASCII data.
void setNetworkMaxWait(unsigned long ms);
Sets the maximum amount of time in milliseconds that the RWHttpAgent waits for data to become available from the server or for data to be sent to the server. If you set ms to 0, the RWHttpAgent waits indefinitely.
If data for a request is not available within the user-defined time ms, an RWNetOperationTimeoutError is thrown.
void setSendDate(bool b);
Determines whether a Date header is sent with a request. If b is true, all subsequent requests from this RWHttpAgent object attach an RWHttpDateHeader with the current date. If b is false, a date header is not appended. The default is false.
void setUserAgent(const RWCString& agent);
Assigns the string agent to the internal User-Agent value. If User-Agent is set to a non-empty string, an RWHttpUserAgentHeader is attached to all requests issued from the RWHttpAgent object. The RWCString should contain 7-bit US-ASCII data.
© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.