|
class HttpRequest : public TcpSocket
This class performs synchronous or asynchronous HTTP requests.
Event<const void *, int> WhenContent
Defines consumer function for HTTP response content. If defined, HttpRequest uses this output event instead of storing the output content in String that can be read using GetContent method. Note that only "valid" content, defined as content in response with status code in the range 200 .. 299 is sent to WhenContent - this avoids problems with multiple requests because of redirection or authorization. It is possible to change this behavior with AllContent - in that case client code is likely to use WhenStart to separate responses to individual requests.
Event<> WhenStart
Invoked each time HttpRequest starts a new request attempt - this includes redirections, authentization or retries on error. Gives chance to client software to restart processing, e.g. to delete partially downloaded file.
Event<> WhenDo
Invoked each time Do routine exits. Useful to show progres or allow abortions in GUI.
Gate<> WhenAuthenticate
Invoked when request returns 401 code (unauthorized). Callback should check returned headers and if possible, provide authorization header (through Authorization). In that case, it should return true to indicate that authorization was (hopefully) resolved - HttpRequest will then try to repeat the query.
Specifies the maximum size of response header (default is 1000000). Returns *this.
HttpRequest& MaxContentSize(int m)
Specifies the maximum size of response content that can be stored in HttpRequest to be retrieved by GetContent method (default is 10000000). Note that this limit does no apply when content data are processed using WhenContent callback. Returns *this.
HttpRequest& MaxRedirect(int n)
Specifies the maximum number of redirections (code 3xx) (default is 10). Returns *this.
HttpRequest& MaxRetries(int n)
Specifies the maximum number of retries on failure (default is 3). Returns *this.
HttpRequest& RequestTimeout(int ms)
Specifies total allowed time for request in milliseconds (default is .120000 - two minutes). Returns *this.
HttpRequest& ChunkSize(int n)
Specifies the maximum size of content data block for processing (default is 4096). Returns *this.
HttpRequest& AllContent(bool b = true)
When active, WhenContent receives content from all responses, even if they are just redirection or authorization texts.
HttpRequest& Method(int m, const char *custom_name = NULL)
Sets HTTP request method. m can be one of METHOD_GET, METHOD_POST, METHOD_HEAD, METHOD_PUT, METHOD_DELETE, METHOD_TRACE, METHOD_OPTIONS, METHOD_CONNECT, METHOD_PATCH. Default setting is METHOD_GET. If custom_name is not NULL, HttpRequest behaves likem performing method m but in HTTP request custom_name is used as method. Returns *this.
HttpRequest& GET()
Same as Method(METHOD_GET) (default). Returns *this.
HttpRequest& POST()
Same as Method(METHOD_POST). Returns *this.
HttpRequest& HEAD()
Same as Method(METHOD_HEAD). Returns *this.
HttpRequest& PUT()
Same as Method(METHOD_PUT). Returns *this.
HttpRequest& DEL()
Same as Method(METHOD_DELETE). Returns *this. Note that this method is not named "DELETE" because of name-clash with Win32 #define.
HttpRequest& TRACE()
Same as Method(METHOD_TRACE). Returns *this.
HttpRequest& OPTIONS()
Same as Method(METHOD_OPTIONS). Returns *this.
HttpRequest& CONNECT()
Same as Method(METHOD_CONNECT). Returns *this.
HttpRequest& PATCH()
Same as Method(METHOD_PATCH). Returns *this.
HttpRequest& Host(const String& h)
Sets server host. Returns *this.
HttpRequest& Port(int p)
Sets.server port. Returns *this.
HttpRequest& SSL(bool b = true)
Activates SSL mode. Returns *this.
HttpRequest& Path(const String& p)
Sets request path. Returns *this.
HttpRequest& Authorization(const String& h)
Sets authorization header (text between "Authorization: " and "\r\n" in header). It is intended to be used in WhenAuthenticate callback to provide login info.
HttpRequest& User(const String& u, const String& p)
Sets user and password according to Basic access authentication. Returns *this.
HttpRequest& Digest()
Forces HttpRequest to use Digest access authentication. - not to send Basic access authentication. Returns *this.
HttpRequest& Digest(const String& d)
Sets digest. This is usually done by HttpRequest when processing 401 response code. Returns *this.
HttpRequest& Url(const char *url)
Sets request url. url is parsed to get host name, port and path, then calling Host, Port and Path methods. If url starts with "https", SSL mode is activated using SSL method. Returns *this.
HttpRequest& UrlVar(const char *id, const String& data)
HttpRequest& operator()(const char *id, const String& data)
Adds name/value pair to the path in the format used by HTML forms with "GET" method. Returns *this.
HttpRequest& PostData(const String& pd)
Sets data to be posted with request. Returns *this.
HttpRequest& PostStream(Stream& s, int64 len = Null)
Sets stream of data to be posted with request. len is number of bytes to be sent from the stream, if Null, all remaining data from the stream are sent. Returns *this.
bool ResolveDigestAuthentication()
This method is assigned to WhenAuthenticate by default. Provides standard HTTP digest authentication.
HttpRequest& PostUData(const String& pd)
Sets data to be posted with request, perform as url-encoding of data. Returns *this.
HttpRequest& Post(const String& data)
Same as POST().PostData(data). Returns *this.
HttpRequest& Post(const char *id, const String& data)
Sets method to POST and name/value pair to the post data in the format used by HTML forms with "POST" method. Returns *this.
HttpRequest& Part(const char *id, const String& data, const char *content_type = NULL, const char *filename = NULL)
First call sets HttpRequest to the multipart mode; unique part boundary is generated automatically. id is name of the part, data is cotnet. If content_type is not NULL nor empty, it defines "Content-Type" part header. filename can be used to define the "filename" part of "Content-Disposition" part header.
HttpRequest& ClearPost()
Empties all Post data and sets the method to GET.
Sets text containing HTTP headers to be add after HttpRequest generated header fields. Returns *this.
Same as Headers(Null).
Adds text containing HTTP headers to be add after HttpRequest generated header fields. Returns *this.
Adds single name/value pair to headers. Returns *this.
HttpRequest& Cookie(const HttpCookie& c)
Sets the cookie to be send with any subsequent request. Member raw of HttpCookie is ignored. Cookie is only send when path and domain match (can be set to Null to match always).
HttpRequest& Cookie(const String& id, const String& value, const String& domain = Null, const String& path = Null)
Sets the cookie to be send with any subsequent request. Member raw of HttpCookie is ignored. Cookie is only send when path and domain match (can be set to Null to match always)..
HttpRequest& CopyCookies(const HttpRequest& r)
Copies cookies from another HttpRequest.
HttpRequest& ClearCookies()
Clears all cookies.
Determines whether HttpRequest should provide standard http header fields (URL, Host, Connection, Accept, Accept-Encoding, User-Agent, Content-Length, Content-Type). Default is yes. Returns *this.
Same as StdHeaders(false).
HttpRequest& Accept(const String& a)
Sets the value of "Accept" field in HttpRequest generated portion of header. Default is "*/*". Returns *this.
HttpRequest& UserAgent(const String& a)
Specifies "User-Agent" HTTP request field. Defualt is "U++ HTTP request". Returns *this.
HttpRequest& ContentType(const String& a)
Specifies "Content-Type" HTTP request field. Returns *this.
HttpRequest& KeepAlive(bool ka = true)
If active, "Connection" HTTP request field is "keep-alive", otherwise "close". Returns *this.
HttpRequest& Proxy(const String& host, int port)
Defines http proxy. Returns *this.
HttpRequest& Proxy(const char *p)
Defines http proxy, p should contain "hostname:port". If port is not present, it is set to 80. Returns *this.
HttpRequest& ProxyAuth(const String& u, const String& p)
Defines username and password authentication for SSL proxy. Returns *this.
HttpRequest& SSLProxy(const String& host, int port)
Defines proxy for SSL connection. Returns *this.
HttpRequest& SSLProxy(const char *p)
Defines proxy for SSL connection, p should contain "hostname:port". If port is not present, it is set to 8080. Returns *this.
HttpRequest& SSLProxyAuth(const String& u, const String& p)
Defines username and password authentication for SSL proxy. Returns *this.
HttpRequest& CommonProxy(const String& host, int port)
Defines both SSL and non-SSL proxies to the same host and port. Same as Proxy(host, port); SSLProxy(host, port). Returns *this.
HttpRequest& CommonProxy(const char *p)
Defines both SSL and non-SSL proxies to the same server. Same as Proxy(p); SSLProxy(p), including default port definitions. Returns *this.
HttpRequest& CommonProxyAuth(const String& u, const String& p)
Defines username and password authentication for both SSL and non-SSL proxis. Same as ProxyAuth(u, p); SSLProxyAuth(u, p). Returns *this.
bool IsSocketError() const
Returns true if there was error on socket level.
bool IsHttpError() const
Returns true if there was error on HTTP protocol level.
bool IsError() const
Same as IsSocketError() || IsHttpError().
String GetErrorDesc() const
Returns error description.
void ClearError()
Clears all errors.
String operator[](const char *id)
Returns response header field. id must be lowercase.
String GetRedirectUrl()
Returns processed Location field of HTTP response header.
int64 GetContentLength()
Returns the content length as specified in HTTP response header or 0 if not specified or header not yet loaded.
int GetStatusCode() const
If request is finished, returns HTTP status code.
String GetReasonPhrase() const
If request is finished, returns HTTP reason phrase.
Returns HttpHeader of response.
String GetCookie(const char *id)
Returns the value of cookie id of response.
String GetContent() const
String operator~() const
operator String() const
Returns current gather content result.
void ClearContent()
Clears the content result to reduce memory consumption. Can be called at any time.
bool Do()
Progresses the request. Maximum duration is defined by Socket::Timeout. Returns true if processing is not finished.
dword GetWaitEvents()
Returns a combination of WAIT_READ and WAIT_WRITE flags to indicate what is blocking the progress of HTTP request. Can be used with SocketWaitEvent.
int GetPhase() const
Returns the current phase of request processing, one of BEGIN, START, DNS, SSLPROXYREQUEST, SSLPROXYRESPONSE, SSLHANDSHAKE, REQUEST, HEADER, BODY, CHUNK_HEADER, CHUNK_BODY, TRAILER, FINISHED, FAILED.
String GetPhaseName() const
Returns the text description of current request phase.
bool InProgress() const
Returns true if request is still in progress.
bool IsFailure() const
Request has failed. That means either a communication error or failure of HTTP protocol. Successfully completed requests ending with non 2xx code are not considered failure.
bool IsSuccess() const
Request succeeded with 2xx code. Not that IsSuccess is not complementary to IsFailure (request can e.g. end with 404 code, which means that both IsFailure() and IsSuccess() are false.
String Execute()
Performs the whole request, returns resulting content on success or String::GetVoid() on failure.
void New()
Starts a new HTTP request. Unlike Clear, it does not change any existing settings. Does not break TCP connection to server. New request uses cookies received in previous requests.
void NewRequest()
Starts a new HTTP request without breaking the connection to the server. Sets all settings to initial state, except Cookies received - those are send with the new request.
void Clear()
Sets HTTP request to initial default state (same as freshly constructed object) including cookies. Terminates TCP connection to server.
HttpRequest()
Default constructor.
HttpRequest(const char *url)
Constructs HttpRequest and calls Url(url).
static void Trace(bool b = true)
Activates/deactivates global logging for HttpRequests (default is not active).
|
