Qore::HTTPClient Class Reference

The HTTPClient class can be used to communicate with HTTP servers with and without TLS/SSL encryption. More...

Inheritance diagram for Qore::HTTPClient:
[legend]

## Public Member Functions

nothing | addDefaultHeaders (hash< auto > hdr)
| Sets headers to send by default with every outgoing request. More...
nothing | clearProxyURL ()
| Clears the new proxy URL value for the next connection. More...
nothing | clearProxyUserPassword ()
| Clears the username and password for the next proxy connection. More...
| clearStats ()
| Clears performance statistics. More...
nothing | clearUserPassword ()
| Clears the username and password for the connection. More...
nothing | clearWarningQueue ()
| Removes any warning Queue object from the Socket. More...
nothing | connect ()
| Connects to the remote socket; SSL/TLS negotiation is performed if required. More...
| constructor (hash< auto > opts)
| Creates the HTTPClient object based on the option parameter passed. More...
| constructor ()
| Creates the HTTPClient object. More...
| copy ()
| Copying objects of this class is not supported, an exception will be thrown. More...
| destructor ()
| Destroys the HTTPClient object and closes any open connections. More...
nothing | disconnect ()
| Disconnects from the remote socket if a connection is established (otherwise does nothing) More...
*string | get (string path, *hash< auto > headers, *reference< hash< auto >> info)
| Sends an HTTP `GET` request and returns the message body received as a string or NOTHING if no message body is received. More...
string | getAssumedEncoding ()
| returns the assumed character encoding for messages from the HTTP server without any charset indicator More...
int | getConnectTimeout ()
| Returns the connect timeout as an integer in milliseconds. More...
*string | getConnectionPath ()
| Returns the current connection path set in the URL. More...
hash< string, string > | getDefaultHeaders ()
| Returns a hash of default headers to be sent with every outgoing request. More...
string | getDefaultPath ()
| Returns the default path used by the object if no path is set in the URL. More...
string | getEncoding ()
| Returns the character encoding used for the object. More...
bool | getEncodingPassthru ()
| get the encoding passthru status More...
bool | getErrorPassthru ()
| get the error passthru status More...
string | getHTTPVersion ()
| Returns the HTTP protocol version string used in outgoing messages. More...
string | getHostHeaderValue ()
| returns the `Host` header value for this object More...
int | getMaxRedirects ()
| Returns the current `max_redirects` value for the object (the maximum number of HTTP redirects that will be processed before an exception is raised) More...
bool | getNoDelay ()
| Returns the `TCP_NODELAY` setting for the HTTPClient object. More...
*string | getProxyURL ()
| Returns the current proxy URL as a string or NOTHING if no proxy URL is set. More...
bool | getRedirectPassthru ()
| get the redirect passthru status More...
int | getTimeout ()
| Returns the default I/O timeout as an integer in milliseconds. More...
*string | getURL ()
| Returns the current URL. More...
hash< auto > | getUsageInfo ()
| Returns performance statistics for the socket. More...
hash< auto > | head (string path, *hash< auto > headers, *reference< hash< auto >> info)
| Sends an HTTP `HEAD` request and returns as hash of the headers received. More...
bool | isConnected ()
| Returns True or False giving the current connection state. More...
bool | isProxySecure ()
| Returns the SSL/TLS flag for the next proxy connection. More...
bool | isSecure ()
| Returns True if the current connection is encrypted, False if not. More...
*string | post (string path, string body, *hash< auto > headers, *reference< hash< auto >> info)
| Sends an HTTP `POST` request with a message body and returns the message body received as a string or NOTHING if no message body is received. More...
*string | post (string path, *binary body, *hash< auto > headers, *reference< hash< auto >> info)
| Sends an HTTP `POST` request with a message body and returns the message body received as a string or NOTHING if no message body is received. More...
hash< auto > | send (string body, string method, *string path, *hash< auto > headers, softbool getbody=False, *reference< hash< auto >> info)
| Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...
hash< auto > | send (*binary body, string method, *string path, *hash< auto > headers, softbool getbody=False, *reference< hash< auto >> info)
| Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. More...
nothing | send (Qore::OutputStream os, *data body, string method, *string path, *hash< auto > headers, timeout timeout_ms=0, softbool getbody=False, *reference< hash< auto >> info, *code rcb)
| Sends an HTTP request with the specified method and optional message body; headers are returned through an optional receive callback and any body received is written to the OutputStream. More...
nothing | sendChunked (Qore::OutputStream os, Qore::InputStream is, string method, int max_chunk_size=4096, *string path, *hash< auto > headers, timeout timeout_ms=0, softbool getbody=False, *reference< hash< auto >> info, *code rcb, *code tcb)
| Sends a chunked HTTP request with the specified method and message body; headers are returned through an optional receive callback and any body received is written to the OutputStream. More...
nothing | sendWithCallbacks (code scb, code rcb, string method, *string path, *hash< auto > headers, timeout timeout_ms=0, softbool getbody=False, *reference< hash< auto >> info)
| Sends an HTTP request with the specified method and chunked message body as given by a send callback; headers and any body received are returned through a receive callback. More...
nothing | sendWithRecvCallback (code rcb, string body, string method, *string path, *hash< auto > headers, timeout timeout_ms=0, softbool getbody=False, *reference< hash< auto >> info)
| Sends an HTTP request with the specified method and optional message body; headers and any body received are returned through a receive callback. More...
nothing | sendWithRecvCallback (code rcb, *binary body, string method, *string path, *hash< auto > headers, timeout timeout_ms=0, softbool getbody=False, *reference< hash< auto >> info)
| Sends an HTTP request with the specified method and optional message body; headers and any body received are returned through a receive callback. More...
hash< auto > | sendWithSendCallback (code scb, string method, *string path, *hash< auto > headers, timeout timeout_ms=0, softbool getbody=False, *reference< hash > info)
| Sends an HTTP request with the specified method and chunked message body as given by a send callback and returns headers and any body received as a response in a hash format. More...
| setAssumedEncoding (*string encoding)
| sets the assumed character encoding for messages from the HTTP server without any charset indicator More...
nothing | setConnectTimeout (timeout timeout_ms=-1)
| Sets the connect timeout in milliseconds. More...
| setConnectionPath (*string uri_path)
| Overrides any connection path set in the URL. More...
nothing | setDefaultPath (*string path)
| Sets the default path used by the object if no path is set in the URL. More...
nothing | setEncoding (string encoding)
| Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding. More...
bool | setEncodingPassthru (bool set=True)
| set the encoding passthru status More...
bool | setErrorPassthru (bool set=True)
| set the error passthru status More...
nothing | setEventQueue ()
| Clears any Queue object that may be set on the HTTPClient object so that I/O events are no longer captured on the object. More...
nothing | setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
| Sets a Queue object to receive HTTPClient and Socket events. More...
nothing | setHTTPVersion (string ver)
| Sets the HTTP protocol version string for headers in outgoing messages, allowed values are `"1.0"` and "1.1". More...
nothing | setMaxRedirects (softint mr=0)
| Updates the setting for the `max_redirects` value for the object (maximum number of HTTP redirects that will be processed before an exception is raised) More...
int | setNoDelay (softbool b=True)
| Sets the `TCP_NODELAY` setting for the object. More...
| setPersistent ()
| temporarily disables implicit reconnections; must be called when the server is already connected More...
nothing | setProxySecure (softbool b=True)
| Sets the SSL/TLS flag for the next connection to the proxy. More...
nothing | setProxyURL ()
| Clears the new proxy URL value for the next connection. More...
nothing | setProxyURL (string url)
| Sets a new proxy URL value for the next connection. More...
nothing | setProxyUserPassword (string user, string pass)
| Sets the username and password for the connection to the proxy; call after HTTPClient::setProxyURL() More...
nothing | setProxyUserPassword ()
| Clears the username and password for the next proxy connection. More...
bool | setRedirectPassthru (bool set=True)
| set the redirect passthru status More...
nothing | setSecure (softbool secure=True)
| Sets the object to make a secure SSL/TLS connection on the next connect if the passed argument is True, or an unencrypted cleartext connection if it is False. More...
nothing | setTimeout (timeout timeout_ms=0)
| Sets the default I/O timeout value in milliseconds. More...
| setURL (string url)
| Sets a new URL value for the next connection. More...
nothing | setUserPassword (string user, string pass)
| Sets the username and password for the connection; call after HTTPClient::setURL() More...
nothing | setUserPassword ()
| Clears the username and password for the connection. More...
nothing | setWarningQueue (int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s)
| Sets a Queue object to receive socket warnings. More...
Public Member Functions inherited from Qore::Socket
Socket | accept ()
| Accepts connections on a listening socket. More...
*Socket | accept (timeout timeout_ms)
| Accepts connections on a listening socket (see Socket::listen()) accepting a timeout value with a millisecond resolution. More...
| acceptAllCertificates (bool accept_all=True)
| with peer verification enabled, all certificates are accepted regardless of the validity of the Certificate Authority More...
Socket | acceptSSL ()
| Accepts connections on a listening socket and attempts to negotiate a TLS/SSL connection. More...
*Socket | acceptSSL (timeout timeout_ms)
| Accepts connections on a listening socket and attempts to negotiate a TLS/SSL connection accepting a timeout value with a millisecond resolution. More...
int | bind (string str, softbool reuseaddr=False)
| Opens and binds the socket to a port, interface and port (if the bind_to string has a format "host:port"), or UNIX domain socket file. More...
int | bind (int port, softbool reuseaddr=False)
| Opens and binds the socket to an INET port on all interfaces. More...
nothing | bindINET (*string iface, *softstring service, softbool reuseaddr=False, softint family=AF_UNSPEC, softint socktype=SOCK_STREAM, softint protocol=0)
| Opens and binds the socket to the given IPv4 or IPv6 interface (or if no interface is given, then to all interfaces on the local system) and port (the port number will be derived from the service name if a numeric port number is not given) More...
nothing | bindUNIX (string path, softint socktype=SOCK_STREAM, softint protocol=0)
| Opens and binds the socket to the given UNIX domain socket file as given by the filename argument. If any errors occur, an exception is thrown. More...
bool | captureRemoteCertificates (bool set=True)
| Sets the flag for capturing remote X.509 certificates; by default no capture of remote certificates is performed. More...
| clearStats ()
| Clears performance statistics. More...
nothing | clearWarningQueue ()
| Removes any warning Queue object from the Socket. More...
int | close ()
| Closes an open socket. More...
nothing | connect (string target, timeout timeout_ms=-1)
| Connects to a remote port (if the string has a format "host:port") or UNIX domain socket file with an optional timeout value with a millisecond resolution. More...
nothing | connectINET (string host, softstring service, timeout timeout_ms=-1, softint family=AF_UNSPEC, softint socktype=SOCK_STREAM, softint protocol=0)
| Connects to the given host and port with an optional timeout value with a millisecond resolution. More...
nothing | connectINETSSL (string host, softstring service, timeout timeout_ms=-1, softint family=AF_UNSPEC, softint socktype=SOCK_STREAM, softint protocol=0)
| Connects to the given host and port and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution. More...
nothing | connectSSL (string target, timeout timeout_ms=-1)
| Connects to a remote socket and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution. More...
nothing | connectUNIX (string path, softint socktype=SOCK_STREAM, softint protocol=0)
| Connects to a UNIX domain socket file. More...
nothing | connectUNIXSSL (string path, softint socktype=SOCK_STREAM, softint protocol=0)
| Connects to the given UNIX domain socket file and attempts to establish a TLS/SSL connection. More...
| constructor ()
| Creates the socket object. More...
| copy ()
| Creates a new Socket object, not based on the source being copied. More...
bool | getAcceptAllCertificates ()
| returns the current value of the "accept all certificates" flag More...
string | getCharset ()
| Returns the character encoding for the socket. More...
int | getConnectionId ()
| Returns an integer connection ID that is incremented every time the socket is disconnected. More...
string | getEncoding ()
| Returns the character encoding for the socket. More...
bool | getNoDelay ()
| Returns the `TCP_NODELAY` setting for the socket. More...
hash< auto > | getPeerInfo (bool host_lookup=True)
| Returns a hash of information about the remote end for connected sockets. More...
int | getPort ()
| Returns the port number of the socket for INET sockets. More...
int | getRecvTimeout ()
| Returns the receive timeout socket option value as an integer in milliseconds. More...
*SSLCertificate | getRemoteCertificate ()
| Returns any remote certificate captured or NOTHING if there is none. More...
*string | getSSLCipherName ()
| Returns the name of the cipher for an encrypted connection or NOTHING if a secure connection has not been established. More...
*string | getSSLCipherVersion ()
| Returns the version string of the cipher for an encrypted connection or NOTHING if a secure connection has not been established. More...
int | getSendTimeout ()
| Returns the send timeout socket option value as an integer in milliseconds. More...
int | getSocket ()
| Returns the socket file descriptor number. More...
hash< auto > | getSocketInfo (bool host_lookup=True)
| Returns information about the local socket as a hash. More...
int | getSslVerifyMode ()
| returns the current SSL verification mode More...
hash< auto > | getUsageInfo ()
| Returns performance statistics for the socket. More...
bool | isDataAvailable (timeout timeout_ms=0)
| Returns True or False depending on whether there is data to be read on the socket. More...
bool | isOpen ()
| Returns True if the socket is open. More...
bool | isSecure ()
| Returns True if the connection is a secure TLS/SSL connection. More...
bool | isWriteFinished (timeout timeout_ms=0)
| Returns True or False depending on whether all the data has been written to the socket. More...
int | listen (int backlog=20)
| Listens for connections on a bound socket; sets the socket in a listening state. More...
bool | pendingHttpChunkedBody ()
| returns True if the socket is still connected, and a HTTP header was read indicating chunked transfer encoding, but no chunked body has been read yet More...
hash< auto > | readHTTPChunkedBody (timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a string in the `"body"` key of a hash (including footers received) More...
hash< auto > | readHTTPChunkedBodyBinary (timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a binary object in the `"body"` key of a hash (including footers received) More...
| readHTTPChunkedBodyBinaryWithCallback (code rcb, timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a string in the `"body"` key of a hash (including footers received) More...
hash< auto > | readHTTPChunkedBodyToOutputStream (Qore::OutputStream os, timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding, writes it in an OutputStream and returns any footers received. More...
| readHTTPChunkedBodyWithCallback (code rcb, timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a string in the `"body"` key of a hash (including footers received) More...
hash< auto > | readHTTPHeader (timeout timeout_ms=-1, *reference< hash< auto >> info)
| Retuns a hash representing the data in the HTTP header read, or, if the data cannot be parsed as an HTTP header, then an exception is thrown, and the data read is returned as a string in the `arg` key of the exception hash. More...
string | readHTTPHeaderString (timeout timeout_ms=-1)
| Retuns a string representing the data in the HTTP header read (reads until `"\r\n\r\n"`) More...
string | recv (softint size=0, timeout timeout_ms=-1)
| Receives data from the socket and returns a string tagged with the Socket's character encoding. More...
binary | recvBinary (softint size=0, timeout timeout_ms=-1)
| Receives data from the socket and returns a binary object. More...
nothing | recvToOutputStream (Qore::OutputStream os, softint size=-1, timeout timeout_ms=-1)
| Receives data from the socket and writes the bytes to an OutputStream. More...
int | recvi1 (timeout timeout_ms=-1)
| Receives a 1-byte signed integer from the socket. More...
int | recvi2 (timeout timeout_ms=-1)
| Receives a 2-byte (16-bit) signed integer in big-endian format (network byte order) from the socket. More...
int | recvi2LSB (timeout timeout_ms=-1)
| Receives a 2-byte (16-bit) signed integer in little-endian format from the socket. More...
int | recvi4 (timeout timeout_ms=-1)
| Receives a 4-byte (32-bit) signed integer in big-endian format (network byte order) from the socket. More...
int | recvi4LSB (timeout timeout_ms=-1)
| Receives a 4-byte (32-bit) signed integer in little-endian format from the socket. More...
int | recvi8 (timeout timeout_ms=-1)
| Receives an 8-byte (64-bit) signed integer in big-endian format (network byte order) from the socket. More...
int | recvi8LSB (timeout timeout_ms=-1)
| Receives an 8-byte (64-bit) signed integer in little-endian format from the socket. More...
int | recvu1 (timeout timeout_ms=-1)
| Receives a 1-byte unsigned integer from the socket. More...
int | recvu2 (timeout timeout_ms=-1)
| Receives a 2-byte (16-bit) unsigned integer in big-endian format (network byte order) from the socket. More...
int | recvu2LSB (timeout timeout_ms=-1)
| Receives a 2-byte (16-bit) unsigned integer in little-endian format from the socket. More...
int | recvu4 (timeout timeout_ms=-1)
| Receives a 4-byte (32-bit) unsigned integer in big-endian format (network byte order) from the socket. More...
int | recvu4LSB (timeout timeout_ms=-1)
| Receives a 4-byte (32-bit) unsigned integer in little-endian format from the socket. More...
int | send (binary bin, timeout timeout_ms=-1)
| Sends binary data over the socket; if any errors occur, an exception is thrown. More...
int | send (string str, timeout timeout_ms=-1)
| Sends string data over the socket; string data is converted to the socket's encoding if necessary; if any errors occur, an exception is thrown. More...
nothing | send2 (binary bin, timeout timeout_ms=-1)
| Sends binary data over the socket; if any errors occur, an exception is thrown. More...
nothing | send2 (string str, timeout timeout_ms=-1)
| Sends string data over the socket; string data is converted to the socket's encoding if necessary; if any errors occur, an exception is thrown. More...
int | sendBinary (string str, timeout timeout_ms=-1)
| Sends string data over the socket without converting the string to the socket's encoding, but instead is sent exactly as-is; if any errors occur, an exception is thrown. More...
int | sendBinary (binary bin, timeout timeout_ms=-1)
| Sends binary data over the socket; if any errors occur, an exception is thrown. More...
nothing | sendBinary2 (string str, timeout timeout_ms=-1)
| Sends string data over the socket without converting the string to the socket's encoding, but instead is sent exactly as-is; if any errors occur, an exception is thrown. More...
nothing | sendBinary2 (binary bin, timeout timeout_ms=-1)
| Sends binary data over the socket; if any errors occur, an exception is thrown. More...
nothing | sendFromInputStream (Qore::InputStream input_stream, softint size=-1, timeout timeout_ms=-1)
| Reads data from an InputStream and sends the bytes over the socket. More...
nothing | sendHTTPChunkedBodyFromInputStream (Qore::InputStream input_stream, int max_chunk_size=4096, timeout timeout_ms=-1, *code tcb)
| Sends an HTTP message body in chunked transfer encoding. More...
nothing | sendHTTPChunkedBodyTrailer (*hash< auto > trailer, timeout timeout_ms=-1)
| Sends the trialer of an HTTP message body in chunked transfer encoding. More...
nothing | sendHTTPMessage (string method, string path, string http_version, hash< auto > headers, string body, *reference< hash > info, timeout timeout_ms=-1)
| Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body. More...
nothing | sendHTTPMessage (string method, string path, string http_version, hash< auto > headers, *binary body, *reference< hash< auto >> info, timeout timeout_ms=-1)
| Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body. More...
nothing | sendHTTPMessageWithCallback (code scb, string method, string path, string http_version, hash< auto > headers, *reference< hash< auto >> info, timeout timeout_ms=-1)
| Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body. More...
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, string body, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and an optional message body. More...
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, string body, *reference< hash< auto >> info, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and an optional message body. More...
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, *binary body, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and a message body as literal binary data. More...
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, *binary body, *reference< hash< auto >> info, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and a message body as literal binary data. More...
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, Qore::InputStream input_stream, int max_chunk_size=4096, *reference< hash< auto >> info, timeout timeout_ms=-1, *code tcb)
| Sends an HTTP response with user-defined headers and a message body from an input stream in chunked transfer encoding. More...
nothing | sendHTTPResponseWithCallback (code scb, softint status_code, string status_desc, string http_version, hash< auto > headers, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and a message body to send with chunked transfer encoding provided by a callback. More...
nothing | sendHTTPResponseWithCallback (code scb, softint status_code, string status_desc, string http_version, hash< auto > headers, *reference< hash< auto >> info, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and a message body to send with chunked transfer encoding provided by a callback. More...
int | sendi1 (softint i=0, timeout timeout_ms=-1)
| Sends a 1-byte integer over the socket. More...
int | sendi2 (softint i=0, timeout timeout_ms=-1)
| Sends a 2-byte (16-bit) integer in big-endian format (network byte order) over the socket. More...
int | sendi2LSB (softint i=0, timeout timeout_ms=-1)
| Sends a 2-byte (16-bit) integer in little-endian format over the socket. More...
int | sendi4 (softint i=0, timeout timeout_ms=-1)
| Sends a 4-byte (32-bit) integer in big-endian format (network byte order) over the socket. More...
int | sendi4LSB (softint i=0, timeout timeout_ms=-1)
| Sends a 4-byte (32-bit) integer in little-endian format over the socket. More...
int | sendi8 (softint i=0, timeout timeout_ms=-1)
| Sends an 8-byte (64-bit) integer in big-endian format (network byte order) over the socket. More...
int | sendi8LSB (softint i=0, timeout timeout_ms=-1)
| Sends an 8-byte (64-bit) integer in little-endian format over the socket. More...
nothing | setCertificate (SSLCertificate cert)
| Sets the X.509 certificate to use for negotiating encrypted connections. More...
nothing | setCertificate (string cert_pem)
| Sets the X.509 certificate to use for negotiating encrypted connections from the PEM-encoded string representing the X.509 certificate. More...
nothing | setCertificate (binary cert_der)
| Sets the X.509 certificate to use for negotiating encrypted connections from the DER-encoded binary object representing the X.509 certificate. More...
nothing | setCharset (string encoding)
| Sets the character encoding for the socket. More...
nothing | setEncoding (string encoding)
| Sets the character encoding for the socket. More...
nothing | setEventQueue ()
| Removes any Queue object from the Socket object so that socket events are no longer added to the Queue. More...
nothing | setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
| Sets a Queue object to receive socket events. More...
int | setNoDelay (bool nd=True)
| Sets the boolean `TCP_NODELAY` setting for the socket. More...
nothing | setPrivateKey (SSLPrivateKey key)
| Sets the private key to use for negotiating encrypted connections along with the X.509 certificate. More...
nothing | setPrivateKey (string key_pem, *string pass)
| Sets the private key to use for negotiating encrypted connections along with the X.509 certificate from a PEM-encoded string representing the private key and an optional password. More...
nothing | setPrivateKey (binary key_der)
| Sets the private key to use for negotiating encrypted connections along with the X.509 certificate from a DER-encoded binary object representing the private key. More...
int | setRecvTimeout (timeout timeout_ms)
| sets the receive timeout as a socket option More...
int | setSendTimeout (timeout timeout_ms)
| sets the send timeout as a socket option More...
| setSslVerifyMode (int mode)
| sets the SSL verification mode More...
nothing | setWarningQueue (int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s)
| Sets a Queue object to receive socket warnings. More...
int | shutdown ()
| Ensures that a socket will be closed even if the file descriptor is shared with other processes (for example, after a call to fork()) More...
nothing | shutdownSSL ()
| Shuts down the SSL connection on a secure connection. More...
nothing | upgradeClientToSSL (timeout timeout_ms=-1)
| Upgrades a client socket connection to a TLS/SSL connection. More...
nothing | upgradeServerToSSL (timeout timeout_ms=-1)
| Upgrades a server socket connection to a TLS/SSL connection. More...
*string | verifyPeerCertificate ()
| Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not currently established. More...

## Additional Inherited Members

Static Public Member Functions inherited from Qore::Socket
static list< hash< SocketPollInfo > > | poll (list< hash< SocketPollInfo >> items, timeout timeout_ms)
| polls multiple sockets and returns all sockets with events More...

## Detailed Description

The HTTPClient class can be used to communicate with HTTP servers with and without TLS/SSL encryption.

Restrictions:
  Qore::PO_NO_NETWORK

The HTTPClient class can be used to communicate with HTTP servers using the HTTP or HTTPS (HTTP using an SSL/TLS encrypted connection) protocol.

By default `"Connection: Keep-Alive"` is always sent regardless of the HTTP protocol level set for the object, however if a server response contains `"Connection: close"`, the connection will be closed as soon as the full response (including any message body if present) has been read.

HTTP redirect responses are supported and can be limited with the `max_redirects` constructor hash key or by using the HTTPClient::setMaxRedirects() method. The default maximum number of redirects allowed is 5.

HTTP basic authentication is supported; set the username and password in the URL (ex: `"http://username:password@host:port/path"`). To change the URL from the one set by the constructor, call HTTPClient::setURL().

HTTP proxies and basic proxy authentication are supported by setting the proxy constructor hash key to the proxy URL (with a proxy username and password if required) or by calling the HTTPClient::setProxyURL() method.

Objects of this class are thread-safe and support serializing multiple simultaneous requests from many threads. If a request is in progress and another thread attempts to make a request at the same time, the second thread will block until the first is complete. Therefore the total amount of time a thread could wait for a response in a multi-threaded context could be greater than the timeout value (which applies to the maximum time a single internal send() or recv() action can take).

This class understands and automatically decodes `"deflate"`, `"gzip"`, and `"bzip2"` content encodings as well.

The default I/O timeout value is 300,000 milliseconds (5 minutes). Note that the timeout value applies to individual internal send() or recv() operations; for this reason for large transfers the overall I/O time could exceed the timeout value.

When an exception is thrown (for example, a response code of < `100` or >= `400` is received from the server), any message body returned will be in the `"arg"` key of the exception hash.

This class understands the protocols in the following table.
HTTPClient Class Protocols

Protocol/Scheme | Default Port | SSL? | Description
`http` | `80` | No | Unencrypted HTTP protocol
`https` | `443` | Yes | HTTP protocol with SSL/TLS encryption

Whenever using an HTTPClient method where a hash of headers can be passed to the method, some headers are generated by default by the class and can be overridden, and some are cannot be overridden and are ignored if passed by the client. See the following tables for details.

HTTPClient Mandatory Headers

Header | Description
`Content-Length` | This header is only sent if a message body is sent, and, if so, the length is calculated automatically.

HTTPClient Default, but Overridable Headers

Header | Default Value
`Accept` | `"text/html"`
`Content-Type` | `"text/html"`
`User-Agent` | `"Qore-HTTP-Client/0.8.8"`
`Connection` | `"Keep-Alive"`
`Accept-Encoding` | `"gzip,deflate,bzip2"`

Note that if the `Content-Type` header is sent without a `";charset=xxx"` or `";boundary=xxxx"` specification, and a string is used as the message body for the request and the string does not have `ISO-8859-1` encoding, a `";charset=xxx"` string will be appended to the `Content-Type` header to ensure that the message is received and processed correctly on the remote end. In all other cases the caller is responsible for correctly setting the `Content-Type` header including any necessary `":charset=xxx"` specification.

This class supports posting network events to a Queue. See I/O Event Handling for more information.

The events raised by this object are listed in the following table: HTTPClient Events

Name | Description
EVENT_HTTP_CONTENT_LENGTH | Raised when the HTTP `"Content-Length"` header is received.
EVENT_HTTP_CHUNKED_START | Raised when HTTP chunked data is about to be received.
EVENT_HTTP_CHUNKED_END | Raised when all HTTP chunked data has been received.
EVENT_HTTP_REDIRECT | Raised when an HTTP redirect message is received.
EVENT_HTTP_SEND_MESSAGE | Raised when an HTTP message is sent.
EVENT_HTTP_MESSAGE_RECEIVED | Raised when an HTTP message is received.
EVENT_HTTP_FOOTERS_RECEIVED | Raised when HTTP footers are received.
EVENT_HTTP_CHUNKED_DATA_RECEIVED | Raised when a block of HTTP chunked data is received.
EVENT_HTTP_CHUNK_SIZE | Raised when the next chunk size for HTTP chunked data is known.

# HTTP GET Requests With a Message Body

The Qore HTTPClient class allows `GET` requests to be made with a message body, however please note that this is a bad practice according to HTTP 1.1 RFCs; specifically:

- RFC 2616 section 4.3:

      if the request method does not include defined semantics for an entity-body,
      then the message-body SHOULD be ignored when handling the request.

- RFC 7231 section 4.3.1:

      A payload within a GET request message has no defined semantics; sending a
      payload body on a GET request might cause some existing implementations to
      reject the request.

Therefore we can conclude that `GET` methods do not include defined semantics, and therefore message bodies included with `GET` requests `SHOULD` be ignored according to the HTTP 1.1 spec, therefore it's recommended not to send a message body with a `GET` request if standards compliance and compatibility is a goal.

Note
  - This class is not available with the PO_NO_NETWORK parse option.
  - URLs with UNIX sockets are generally supported in Qore with the following syntax: `scheme://socket=`url_encoded_path`/path`, where url_encoded_path is a path with URL-encoding as performed by encode_url(string, True); for example: `"http://socket=%2ftmp%socket-dir%2fsocket-file-1/url/path"`; this allows a filesystem path to be used in the host portion of the URL and for the URL to include a URL path as well.
  - HTTP headers should accept data in ISO-8859-1 (LATIN-1) encoding, but in practice for maximum compatibility US-ASCII should be used with any non-ASCII characters encoded with MIME encoded-word format according to RFC 2047. This class currently only performs character encoding conversion on strings used as the message body.
  - The default character encoding for this class is the same as the default character encoding for Qore (normally `UTF-8`); this class does not include a `";charset="` specification in the `"Content-Type"` header when sending binary message boundaries

Since
  Qore 1.0 added code to add a `";charset=xxx"` to HTTP messages with a non-ISO-8859-1 string message body

## Member Function Documentation

## addDefaultHeaders()

nothing Qore::HTTPClient::addDefaultHeaders | ( | hash< auto > | hdr | ) |

Sets headers to send by default with every outgoing request.

Parameters

  hdr | headers to send by default with every outgoing request

See also
  getDefaultHeaders()

Since
  Qore 0.9.5

## clearProxyURL()

nothing Qore::HTTPClient::clearProxyURL | ( |  | ) |

Clears the new proxy URL value for the next connection.

Example:
  httpclient.setProxyURL();

## clearProxyUserPassword()

nothing Qore::HTTPClient::clearProxyUserPassword | ( |  | ) |

Clears the username and password for the next proxy connection.

Call this method after calling HTTPClient::setProxyURL() to clear any proxy authentication information present in the URL used in HTTPClient::setProxyURL()

Example:
  httpclient.clearProxyUserPassword();

## clearStats()

Qore::HTTPClient::clearStats | ( |  | ) |

Clears performance statistics.

Example:
  httpclient.clearStats();

Since
  Qore 0.8.9

See also
  HTTPClient::getUsageInfo()

## clearUserPassword()

nothing Qore::HTTPClient::clearUserPassword | ( |  | ) |

Clears the username and password for the connection.

Call this method after calling HTTPClient::setURL() to clear any authentication information present in the URL used in HTTPClient::setURL()

Example:
  httpclient.clearUserPassword();

## clearWarningQueue()

nothing Qore::HTTPClient::clearWarningQueue | ( |  | ) |

Removes any warning Queue object from the Socket.

Example:
  httpclient.clearWarningQueue();

See also
  HTTPClient::setWarningQueue()

Since
  Qore 0.8.9

## connect()

nothing Qore::HTTPClient::connect | ( |  | ) |

Connects to the remote socket; SSL/TLS negotiation is performed if required.

If the protocol indicates that a secure connection should be established (or HTTPClient::setSecure() was called previsouly), SSL/TLS negotiation will be attempted.

If the `TCP_NODELAY` flag has been set (see HTTPClient::setNoDelay()), then after a successful connection to the remote socket, this option will be set on the socket. If an error occurs setting the `TCP_NODELAY` option, the internal flag is set to false (use HTTPClient::getNoDelay() to check the flag's state) and the error code can be retrieved with errno().

Example:
  httpclient.connect();

Events:
  EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Note
  For possible exceptions, see the Socket::connect() method (or Socket::connectSSL() for secure connections).

## constructor() [1/2]

Qore::HTTPClient::constructor | ( | hash< auto > | opts | ) |

Creates the HTTPClient object based on the option parameter passed.

To connect, call any method that requires a connection and an implicit connection is established, or call HTTPClient::connect().

Example:
  HTTPClient httpclient(("url":"http://hostname:8080/path"));

Parameters

  opts

  sets options and changes default behaviour for the object, etc; key names are case-sensitive and therefore must all be in lower-case:
  - `additional_methods:` An optional hash defining additional HTTP methods to handle. This allows the HTTPClient class to handle various HTTP extensions like e.g. WebDAV. The hash is defined with new method names as keys; the values are True or False indicating if the method can accept a message body; for example:
    # add two new HTTP methods for WebDAV; both require message bodies
    HTTPClient httpclient({"url": url, "additional_methods": {"PROPFIND": True, "MKCOL": True}});
  - `assume_encoding:` assumes the given encoding if the server does not send a charset value
  - `connect_timeout:` The timeout value in milliseconds for establishing a new socket connection (also can be a relative date-time value for clarity, ex: `30s`)
  - `default_path:` The default path to use for new connections if a path is not otherwise specified in the connection URL
  - `default_port:` The default port number to connect to if none is given in the URL
  - `encoding:` The default character encoding for outgoing messge bodies
  - `encoding_passthru:` Do not decode known content-encodings but rather pass the body through as-is
  - `error_passthru:` If True then HTTP status codes indicating errors will not cause an `HTTP-CLIENT-RECEIVE-ERROR` exception to be raised, rather such responses will be passed through to the caller like any other response
  - `headers:` A hash of headers to send in every outgoing request
  - `http_version:` Either `"1.0"` or `"1.1"` for the claimed HTTP protocol version compliancy in outgoing message headers
  - `max_redirects:` The maximum number of redirects before throwing an exception (the default is 5)
  - `protocols:` A hash describing new protocols, the key is the protocol name and the value is either an integer giving the default port number or a hash with `"port"` and `"ssl"` keys giving the default port number and a boolean value to indicate that an SSL connection should be established
  - `proxy:` The proxy URL for connecting through a proxy
  - `redirect_passthru:` if True then redirect responses will be passed to the caller instead of processed
  - `ssl_cert_path:` a path to an X.509 client certificate file in PEM format; if this option is used, then the calling context must not be restricted with sandbox restriction Qore::PO_NO_FILESYSTEM which is checked at runtime
  - `ssl_key_path:` a path to a private key file in PEM format for the X.509 client certificate; if this option is used, then the calling context must not be restricted with sandbox restriction Qore::PO_NO_FILESYSTEM which is checked at runtime
  - `ssl_key_password:` the password to the private key given with `ssl_key_path`
  - `ssl_verify_cert:` if True then the server's certificate will only be accepted if it's verified
  - `timeout:` The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: `5m`)
  - `url:` A string giving the URL to connect to

Exceptions

  HTTP-CLIENT-OPTION-ERROR | invalid or unknown option passed in option hash
  HTTP-CLIENT-URL-ERROR | invalid URL string
  HTTP-CLIENT-UNKNOWN-PROTOCOL | unknown protocol passed in URL
  ILLEGAL-FILESYSTEM-ACCESS | if the calling context is restricted with the Qore::PO_NO_FILESYSTEM sandboxing restriction and one of the following options is used: `ssl_cert_path` or `ssl_key_path`

Note
  - URLs with UNIX sockets are generally supported in Qore with the following syntax: `scheme://socket=`url_encoded_path`/path`, where url_encoded_path is a path with URL-encoding as performed by encode_url(string, True); for example: `"http://socket=%2ftmp%socket-dir%2fsocket-file-1/url/path"`; this allows a filesystem path to be used in the host portion of the URL and for the URL to include a URL path as well.
  - other I/O errors can be thrown opening and reading the certificate and/or private key files if the `ssl_cert_path` or `ssl_key_path` options are used
  - the Qore::PO_NO_FILESYSTEM sandbox restriction is checked at runtime if one of the following options is used: `ssl_cert_path` or `ssl_key_path`

Since
  - Qore 0.8.13 added the following options:
    - `ssl_cert_path`
    - `ssl_key_path`
    - `ssl_key_password`
    - `ssl_verify_cert`
  - Qore 0.9.3 added the following options:
    - `encoding_passthru`
    - `error_passthru`
    - `redirect_passthru`
  - Qore 0.9.4.2 added the following option:
    - `assume_encoding`
  - Qore 0.9.4.6 added the following option:
    - `encoding`
  - Qore 0.9.5 added the following option:
    - `headers`

## constructor() [2/2]

Qore::HTTPClient::constructor | ( |  | ) |

Creates the HTTPClient object.

Example:
  HTTPClient httpclient();

## copy()

Qore::HTTPClient::copy | ( |  | ) |

Copying objects of this class is not supported, an exception will be thrown.

Exceptions

  HTTPCLIENT-COPY-ERROR | copying HTTPClient objects is not yet supported

## destructor()

Qore::HTTPClient::destructor | ( |  | ) |

Destroys the HTTPClient object and closes any open connections.

Example:
  delete httpclient;

## disconnect()

nothing Qore::HTTPClient::disconnect | ( |  | ) |

Disconnects from the remote socket if a connection is established (otherwise does nothing)

Example:
  httpclient.disconnect();

## get()

*string Qore::HTTPClient::get | ( | string | path,
|  | *hash< auto > | headers,
|  | *reference< hash< auto >> | info
| ) |  |

Sends an HTTP `GET` request and returns the message body received as a string or NOTHING if no message body is received.

In order to get the headers and the body, use the HTTPClient::send() method instead (although note that sending an HTTP message bosdy with a `GET` request is not standards compliant; see HTTP GET Requests With a Message Body for more information).

If no connection has already been established, an internal call to HTTPClient::connect() will be made before sending the request.

If any content encoding is used for the message body in the reply, the content is decoded and returned as a string; if the content encoding uses an unknown method, then an exception is thrown.

Example:
  *string html = httpclient.get("/path/file.html");

Parameters

  path | the path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

  info

  an optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Returns
  the message body in the reply to this message or NOTHING in case of an error or an erroneous reply by the server with no body

Events:
  EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded

  HTTP-CLIENT-RECEIVE-ERROR

  unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server); note that this error is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True; see the `error_passthru` option in HTTPClient::constructor()

  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also
  HTTP GET Requests With a Message Body

Since
  Qore 0.9.3 added support for the `response-headers-raw` info key

## getAssumedEncoding()

string Qore::HTTPClient::getAssumedEncoding | ( |  | ) |

returns the assumed character encoding for messages from the HTTP server without any charset indicator

Code Flags:
  RET_VALUE_ONLY

Example:
  string str = httpclient.getAssumedEncoding();

Returns
  the assumed character encoding for messages from the HTTP server without any charset indicator; by default this is `"ISO-8859-1"`

Since
  Qore 0.9.4.2

## getConnectionPath()

*string Qore::HTTPClient::getConnectionPath | ( |  | ) |

Returns the current connection path set in the URL.

Returns
  the current connection path set in the URL

Code Flags:
  CONSTANT

Example:
  *string path = httpclient.getConnectionPath();

See also
  setConnectionPath()

## getConnectTimeout()

int Qore::HTTPClient::getConnectTimeout | ( |  | ) |

Returns the connect timeout as an integer in milliseconds.

Returns
  Returns the connect timeout as an integer in milliseconds; negative numbers mean the system default timeout is used

Code Flags:
  CONSTANT

Example:
  int to = httpclient.getConnectTimeout();

## getDefaultHeaders()

hash<string,string> Qore::HTTPClient::getDefaultHeaders | ( |  | ) |

Returns a hash of default headers to be sent with every outgoing request.

Code Flags:
  CONSTANT

Returns
  a hash of default headers to be sent with every outgoing request

See also
  addDefaultHeaders()

Since
  Qore 0.9.5

## getDefaultPath()

string Qore::HTTPClient::getDefaultPath | ( |  | ) |

Returns the default path used by the object if no path is set in the URL.

Returns
  the default path used by the object if no path is set in the URL

Code Flags:
  CONSTANT

Example:
  *string def_path = httpclient.getDefaultPath();

## getEncoding()

string Qore::HTTPClient::getEncoding | ( |  | ) |

Returns the character encoding used for the object.

Returns
  the character encoding used for the object

Code Flags:
  CONSTANT

Example:
  string encoding = httpclient.getEncoding();

## getEncodingPassthru()

bool Qore::HTTPClient::getEncodingPassthru | ( |  | ) |

get the encoding passthru status

Code Flags:
  CONSTANT

Example:
  bool b = httpclient.getErrorPassthru();

Returns
  the current `encoding_passthru` value

If True then message bodies received with known content encodings are not decoded but rather passed through as-is

Since
  Qore 0.9.3

## getErrorPassthru()

bool Qore::HTTPClient::getErrorPassthru | ( |  | ) |

get the error passthru status

Code Flags:
  CONSTANT

Example:
  bool b = httpclient.getErrorPassthru();

Returns
  the current `error_passthru` value

If True then HTTP status codes indicating errors will not cause an `HTTP-CLIENT-RECEIVE-ERROR` exception to be raised, rather such responses will be passed through to the caller like any other response.

Since
  Qore 0.9.3

## getHostHeaderValue()

string Qore::HTTPClient::getHostHeaderValue | ( |  | ) |

returns the `Host` header value for this object

Code Flags:
  CONSTANT

Example:
  string host = httpclient.getHostHeaderValue();

Returns
  the `Host` header value for this object

Since
  Qore 0.9.3

## getHTTPVersion()

string Qore::HTTPClient::getHTTPVersion | ( |  | ) |

Returns the HTTP protocol version string used in outgoing messages.

Returns
  the HTTP protocol version string used in outgoing messages

Code Flags:
  CONSTANT

Example:
  string version = httpclient.getHTTPVersion();

## getMaxRedirects()

int Qore::HTTPClient::getMaxRedirects | ( |  | ) |

Returns the current `max_redirects` value for the object (the maximum number of HTTP redirects that will be processed before an exception is raised)

Returns
  the current `max_redirects` value for the object (the maximum number of HTTP redirects that will be processed before an exception is raised)

Code Flags:
  CONSTANT

Example:
  int mr = httpclient.getMaxRedirects();

## getNoDelay()

bool Qore::HTTPClient::getNoDelay | ( |  | ) |

Returns the `TCP_NODELAY` setting for the HTTPClient object.

Code Flags:
  CONSTANT

Example:
  bool b = httpclient.getNoDelay();

See also
  also HTTPClient::setNoDelay()

## getProxyURL()

*string Qore::HTTPClient::getProxyURL | ( |  | ) |

Returns the current proxy URL as a string or NOTHING if no proxy URL is set.

Returns
  the current proxy URL as a string or NOTHING if no proxy URL is set

Code Flags:
  CONSTANT

Example:
  *string proxy_url = httpclient.getProxyURL();

## getRedirectPassthru()

bool Qore::HTTPClient::getRedirectPassthru | ( |  | ) |

get the redirect passthru status

Code Flags:
  CONSTANT

Example:
  bool b = httpclient.getRedirectPassthru();

Returns
  the current `reddirect_passthru` value

If True then redirect messages will be passed to the caller instead of proceessed

Since
  Qore 0.9.3

## getTimeout()

int Qore::HTTPClient::getTimeout | ( |  | ) |

Returns the default I/O timeout as an integer in milliseconds.

Returns
  the default I/O timeout as an integer in milliseconds; 0 means immediate timeout (when reading only returns data if it is already available), and negative numbers mean never timeout

Code Flags:
  CONSTANT

Example:
  int timeout = httpclient.getTimeout();

## getURL()

*string Qore::HTTPClient::getURL | ( |  | ) |

Returns the current URL.

Returns
  the current URL

Code Flags:
  CONSTANT

Example:
  *string url = httpclient.getURL();

## getUsageInfo()

hash<auto> Qore::HTTPClient::getUsageInfo | ( |  | ) |

Returns performance statistics for the socket.

Code Flags:
  CONSTANT

Example:
  hash<auto> h = httpclient.getUsageInfo();

Returns
  a hash with the following keys:
  - `"bytes_sent"`: an integer giving the total amount of bytes sent
  - `"bytes_recv"`: an integer giving the total amount of bytes received
  - `"us_sent"`: an integer giving the total number of microseconds spent sending data
  - `"us_recv"`: an integer giving the total number of microseconds spent receiving data
  - `"arg"`: (only if warning values have been set with HTTPClient::setWarningQueue()) the optional argument for warning hashes
  - `"timeout"`: (only if warning values have been set with HTTPClient::setWarningQueue()) the warning timeout in microseconds
  - `"min_throughput"`: (only if warning values have been set with HTTPClient::setWarningQueue()) the minimum warning throughput in bytes/sec

Since
  Qore 0.8.9

See also
  HTTPClient::clearStats()

## head()

hash<auto> Qore::HTTPClient::head | ( | string | path,
|  | *hash< auto > | headers,
|  | *reference< hash< auto >> | info
| ) |  |

Sends an HTTP `HEAD` request and returns as hash of the headers received.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:
  hash<auto> msg = httpclient.head("/path");

Parameters

  path | the path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

  info

  an optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Returns
  the headers received from the HTTP server with all key names converted to lower-case

Events:
  EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_REDIRECT

Exceptions

  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded

  HTTP-CLIENT-RECEIVE-ERROR

  unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server); note that this error is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True; see the `error_passthru` option in HTTPClient::constructor()

  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

Since
  Qore 0.9.3 added support for the `response-headers-raw` info key

## isConnected()

bool Qore::HTTPClient::isConnected | ( |  | ) |

Returns True or False giving the current connection state.

Returns
  True or False giving the current connection state

Code Flags:
  CONSTANT

Example:
  bool b = httpclient.isConnected();

## isProxySecure()

bool Qore::HTTPClient::isProxySecure | ( |  | ) |

Returns the SSL/TLS flag for the next proxy connection.

Returns
  the SSL/TLS flag for the next proxy connection

Code Flags:
  CONSTANT

Example:
  bool b = httpclient.isProxySecure();

## isSecure()

bool Qore::HTTPClient::isSecure | ( |  | ) |

Returns True if the current connection is encrypted, False if not.

Returns
  True if the current connection is encrypted, False if not

Code Flags:
  CONSTANT

Example:
  if (httpclient.isSecure())
  printf("secure connection: %s %s\n", httpclient.getSSLCipherName(), httpclient.getSSLCipherVersion());

## post() [1/2]

*string Qore::HTTPClient::post | ( | string | path,
|  | string | body,
|  | *hash< auto > | headers,
|  | *reference< hash< auto >> | info
| ) |  |

Sends an HTTP `POST` request with a message body and returns the message body received as a string or NOTHING if no message body is received.

In order to get the headers and the body in the response, use the HTTPClient::send() method instead.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:
  httpclient.post("/path", body);

Parameters

  path | the path for the message (i.e. `"/path/resource?method&param=value"`)
  body | the string to use as the message body
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

  info

  an optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Returns
  the message body in the reply to this message or NOTHING in case no body was present in the response

Events:
  EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded

  HTTP-CLIENT-RECEIVE-ERROR

  unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server); note that this error is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True; see the `error_passthru` option in HTTPClient::constructor()

  ENCODING-CONVERSION-ERROR | the given string could not be converted to the socket's character encoding
  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

Since
  Qore 0.9.3 added support for the `response-headers-raw` info key

## post() [2/2]

*string Qore::HTTPClient::post | ( | string | path,
|  | *binary | body,
|  | *hash< auto > | headers,
|  | *reference< hash< auto >> | info
| ) |  |

Sends an HTTP `POST` request with a message body and returns the message body received as a string or NOTHING if no message body is received.

In order to get the headers and the body in the response, use the HTTPClient::send() method instead.

If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

Example:
  httpclient.post("/path", body);

Parameters

  path | the path for the message (i.e. `"/path/resource?method&param=value"`)
  body | the optional data to use as the message body
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search

  info

  an optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Returns
  the message body in the reply to this message or NOTHING in case no body was present in the response

Events:
  EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT

Exceptions

  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded

  HTTP-CLIENT-RECEIVE-ERROR

  unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server); note that this error is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True; see the `error_passthru` option in HTTPClient::constructor()

  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

Since
  Qore 0.9.3 added support for the `response-headers-raw` info key

## send() [1/3]

hash<auto> Qore::HTTPClient::send | ( | string | body,
|  | string | method,
|  | *string | path,
|  | *hash< auto > | headers,
|  | softbool | getbody = `False`,
|  | *reference< hash< auto >> | info
| ) |  |

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:
  hash<auto> msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

  body | The message body to send; note that sending an HTTP message bosdy with a `GET` request is not standards compliant; see HTTP GET Requests With a Message Body for more information
  method | The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
  path | The path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
  getbody | If this argument is True, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.

  info

  An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Returns
  The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the `"body"` key and the HTTP status will be assigned to the `"status_code"` key.

Exceptions

  HTTP-CLIENT-METHOD-ERROR | invalid/unknown HTTP method passed
  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded

  HTTP-CLIENT-RECEIVE-ERROR

  unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server); note that this error is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True; see the `error_passthru` option in HTTPClient::constructor()

  ENCODING-CONVERSION-ERROR | the given string could not be converted to the socket's character encoding
  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also
  HTTP GET Requests With a Message Body

Since
  Qore 0.9.3 added support for the `response-headers-raw` info key

## send() [2/3]

hash<auto> Qore::HTTPClient::send | ( | *binary | body,
|  | string | method,
|  | *string | path,
|  | *hash< auto > | headers,
|  | softbool | getbody = `False`,
|  | *reference< hash< auto >> | info
| ) |  |

Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:
  hash<auto> msg = httpclient.send(body, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

  body | The message body to send; pass NOTHING (no value) to send no body
  method | The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
  path | The path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
  getbody | If this argument is True, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.

  info

  An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Returns
  The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the `"body"` key and the HTTP status will be assigned to the `"status_code"` key.

Exceptions

  HTTP-CLIENT-METHOD-ERROR | invalid/unknown HTTP method passed
  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded

  HTTP-CLIENT-RECEIVE-ERROR

  unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server); note that this error is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True; see the `error_passthru` option in HTTPClient::constructor()

  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also
  HTTP GET Requests With a Message Body

Since
  Qore 0.9.3 added support for the `response-headers-raw` info key

## send() [3/3]

nothing Qore::HTTPClient::send | ( | Qore::OutputStream | os,
|  | *data | body,
|  | string | method,
|  | *string | path,
|  | *hash< auto > | headers,
|  | timeout | timeout_ms = `0`,
|  | softbool | getbody = `False`,
|  | *reference< hash< auto >> | info,
|  | *code | rcb
| ) |  |

Sends an HTTP request with the specified method and optional message body; headers are returned through an optional receive callback and any body received is written to the OutputStream.

This method is useful for receiving data in real time; data are sent to the output stream as soon as they are received. If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:
  # save the HTTP response body directly to a file with a random file name
  string fn = tmp_location() + DirSep + get_random_string() + ".tmp"
  FileOutputString output_stream(fn);
  # log the "X-Logme" header
  code rcb = sub (hash<auto> h) {
  if (h.hdr."x-logme")
  log("X-Logme: %y", h.hdr."x-logme");
  };
  httpclient.send(output_stream, data, "POST", "/path", ("Content-Type":"application/x-yaml"), NOTHING, NOTHING, NOTHING, rcb);

Parameters

  os | The OutputStream to write the response body to
  body | The message body to send; pass NOTHING (no value) to send no body
  method | The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
  path | The path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
  timeout_ms | the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
  getbody | If this argument is True, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.
  info | An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request.

  rcb

  An optional receive callback for message headers received only; header or trailer data is placed in a hash with the following keys:
  - `"hdr"`: this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message
  - `"info"`: this hash is passed when headers are received; in this case, the hash has at least the the following keys:
    - `"accept-charset"`: the value of any `"Accept-Charset"` header
    - `"accept-encoding"`: the value of any `"Accept-Encoding"` header
    - `"body-content-type"`: the value of the `"Content-Type"` header, if any, without any character set info
    - `"charset"`: any character set value found in the `"Content-Type"` header
    - `"response-headers-raw"`: a hash of unprocessed headers with no case conversions or additional keys
  - `"obj"`: this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)

Exceptions

  HTTP-CLIENT-METHOD-ERROR | invalid/unknown HTTP method passed
  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded

  HTTP-CLIENT-RECEIVE-ERROR

  unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server); note that this error is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True (see the `error_passthru` option in HTTPClient::constructor()) or if a receive callback is used

  ENCODING-CONVERSION-ERROR | the given string could not be converted to the socket's character encoding
  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

Since
  Qore 0.8.13

## sendChunked()

nothing Qore::HTTPClient::sendChunked | ( | Qore::OutputStream | os,
|  | Qore::InputStream | is,
|  | string | method,
|  | int | max_chunk_size = `4096`,
|  | *string | path,
|  | *hash< auto > | headers,
|  | timeout | timeout_ms = `0`,
|  | softbool | getbody = `False`,
|  | *reference< hash< auto >> | info,
|  | *code | rcb,
|  | *code | tcb
| ) |  |

Sends a chunked HTTP request with the specified method and message body; headers are returned through an optional receive callback and any body received is written to the OutputStream.

This method is useful for receiving data in real time; data are sent to the output stream as soon as they are received. If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:
  # save the HTTP response body directly to a file with a random file name
  string fn = tmp_location() + DirSep + get_random_string() + ".tmp"
  FileOutputString output_stream(fn);
  # log the "X-Logme" header
  code rcb = sub (hash<auto> h) {
  if (h.hdr."x-logme")
  log("X-Logme: %y", h.hdr."x-logme");
  };
  # write the "X-Content-Done" header when done
  code tcb = *hash<auto> sub () {
  return {"X-Content-Done": "true"};
  };
  httpclient.sendChunked(output_stream, input_stream, "POST", "/path", ("Content-Type":"application/x-yaml"), NOTHING, NOTHING, NOTHING, rcb, tcb);

Parameters

  os | The OutputStream to write the response body to
  is | The InputStream to read the request body from; each read will be sent as a separate chunk
  method | The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
  max_chunk_size | the maximum chunk size as the read block size for the InputStream read block size; the actual size of the data read will determine the size of each HTTP chunk
  path | The path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
  timeout_ms | the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
  getbody | If this argument is True, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.
  info | An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request.

  rcb

  An optional receive callback for message headers received only; header or trailer data is placed in a hash with the following keys:
  - `"hdr"`: this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message
  - `"info"`: this hash is passed when headers are received; in this case, the hash has at least the the following keys:
    - `"accept-charset"`: the value of any `"Accept-Charset"` header
    - `"accept-encoding"`: the value of any `"Accept-Encoding"` header
    - `"body-content-type"`: the value of the `"Content-Type"` header, if any, without any character set info
    - `"charset"`: any character set value found in the `"Content-Type"` header
    - `"response-headers-raw: a hash of unprocessed headers with no case conversions or additional keys - \c "obj": this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding) @param tcb An optional trailer callback for message trailers to write in the outgoing chunked message; the callback takes no arguments and must return either @ref nothing or @ref hash_type "hash"` giving a hash of trailers for the final chunk

Exceptions

  HTTP-CLIENT-METHOD-ERROR | invalid/unknown HTTP method passed
  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded

  HTTP-CLIENT-RECEIVE-ERROR

  unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server); note that this error is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True (see the `error_passthru` option in HTTPClient::constructor()) or if a receive callback is used

  HTTP-CHUNK-ERROR | the chunk size given is not greater than 0
  HTTP-TRAILER-ERROR | the trailer callback must return either NOTHING or hash; this exception is thrown is another type is returned
  ENCODING-CONVERSION-ERROR | the given string could not be converted to the socket's character encoding
  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

Since
  Qore 0.8.13

## sendWithCallbacks()

nothing Qore::HTTPClient::sendWithCallbacks | ( | code | scb,
|  | code | rcb,
|  | string | method,
|  | *string | path,
|  | *hash< auto > | headers,
|  | timeout | timeout_ms = `0`,
|  | softbool | getbody = `False`,
|  | *reference< hash< auto >> | info
| ) |  |

Sends an HTTP request with the specified method and chunked message body as given by a send callback; headers and any body received are returned through a receive callback.

This method is useful for sending chunked message data where the response is also sent with chunked transfer encoding; chunks are sent to the receive callback as soon as they are received. If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:
  httpclient.sendWithCallbacks(send_callback, rcv_callback, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

  scb | The callback giving the chunked HTTP data to send; this callback must return either a string or a binary value each time it is called to give the chunked data to send; when all data has been sent, then a hash of message trailers can be sent or simply NOTHING which will close the chunked message

  rcb

  The receive callback for the data received; first this method is called with a hash of the message headers, and then with any message body; if a chunked HTTP message is received, then the callback is called once for each chunk; when the message has been received, then the receive callback is called with a hash representing any trailer data received in a chunked transfer or NOTHING if the data was received in a normal message body or if there was no trailer data in a chunked transfer. The argument to this callback is always a hash; data calls have the following keys:
  - `"data"`: the string or binary data
  - `"chunked"`: True if the data was received with chunked transfer encoding, False if not
  Header or trailer data is placed in a hash with the following keys:
  - `"hdr"`: this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message
  - `"info"`: this hash is passed when headers are received; in this case, the hash has at least the following keys:
    - `"accept-charset"`: the value of any `"Accept-Charset"` header
    - `"accept-encoding"`: the value of any `"Accept-Encoding"` header
    - `"body-content-type"`: the value of the `"Content-Type"` header, if any, without any character set info
    - `"charset"`: any character set value found in the `"Content-Type"` header
    - `"response-headers-raw"`: a hash of unprocessed headers with no case conversions or additional keys
  - `"obj"`: this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)
  - `"send_aborted"`: this is set to True if a response header was set while sending an outgoing chunked message

  method | The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
  path | The path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
  timeout_ms | the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
  getbody | If this argument is True, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.

  info

  An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Exceptions

  HTTP-CLIENT-METHOD-ERROR | invalid/unknown HTTP method passed
  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded
  HTTP-CLIENT-RECEIVE-ERROR | unknown content encoding received
  ENCODING-CONVERSION-ERROR | the given string could not be converted to the socket's character encoding
  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  - The `"Transfer-Encoding: chunked"` header is automatically set with this method if no `"Transfer-Encoding"` header is already present
  - if a response is received while the chunked send operation is still in progress, an error is assumed, the send operation is aborted, and the response header is read immediately and the `send_aborted` flag is set in the argument to rcb
  - For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also
  HTTP GET Requests With a Message Body

Since
  - Qore 0.8.10
  - Qore 0.9.3 added support for the `response-headers-raw` info key

## sendWithRecvCallback() [1/2]

nothing Qore::HTTPClient::sendWithRecvCallback | ( | code | rcb,
|  | string | body,
|  | string | method,
|  | *string | path,
|  | *hash< auto > | headers,
|  | timeout | timeout_ms = `0`,
|  | softbool | getbody = `False`,
|  | *reference< hash< auto >> | info
| ) |  |

Sends an HTTP request with the specified method and optional message body; headers and any body received are returned through a receive callback.

This method is useful for receiving chunked message data in real time; chunks are sent to the receive callback as soon as they are received. If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:
  httpclient.sendWithRecvCallback(rcv_callback, data, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

  rcb

  The receive callback for the data received; first this method is called with a hash of the message headers, and then with any message body; if a chunked HTTP message is received, then the callback is called once for each chunk; when the message has been received, then the receive callback is called with a hash representing any trailer data received in a chunked transfer or NOTHING if the data was received in a normal message body or if there was no trailer data in a chunked transfer. The argument to this callback is always a hash; data calls have the following keys:
  - `"data"`: the string or binary data
  - `"chunked"`: True if the data was received with chunked transfer encoding, False if not
  Header or trailer data is placed in a hash with the following keys:
  - `"hdr"`: this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message
  - `"info"`: this hash is passed when headers are received; in this case, the hash has at least the following keys:
    - `"accept-charset"`: the value of any `"Accept-Charset"` header
    - `"accept-encoding"`: the value of any `"Accept-Encoding"` header
    - `"body-content-type"`: the value of the `"Content-Type"` header, if any, without any character set info
    - `"charset"`: any character set value found in the `"Content-Type"` header
    - `"response-headers-raw"`: a hash of unprocessed headers with no case conversions or additional keys
  - `"obj"`: this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)

  body | The message body to send
  method | The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
  path | The path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
  timeout_ms | the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
  getbody | If this argument is True, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.

  info

  An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Exceptions

  HTTP-CLIENT-METHOD-ERROR | invalid/unknown HTTP method passed
  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded
  HTTP-CLIENT-RECEIVE-ERROR | unknown content encoding received
  ENCODING-CONVERSION-ERROR | the given string could not be converted to the socket's character encoding
  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also
  HTTP GET Requests With a Message Body

Since
  - Qore 0.8.10
  - Qore 0.9.3 added support for the `response-headers-raw` info key

## sendWithRecvCallback() [2/2]

nothing Qore::HTTPClient::sendWithRecvCallback | ( | code | rcb,
|  | *binary | body,
|  | string | method,
|  | *string | path,
|  | *hash< auto > | headers,
|  | timeout | timeout_ms = `0`,
|  | softbool | getbody = `False`,
|  | *reference< hash< auto >> | info
| ) |  |

Sends an HTTP request with the specified method and optional message body; headers and any body received are returned through a receive callback.

This method is useful for receiving chunked message data in real time; chunks are sent to the receive callback as soon as they are received. If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:
  httpclient.sendWithRecvCallback(rcv_callback, data, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

  rcb

  The receive callback for the data received; first this method is called with a hash of the message headers, and then with any message body; if a chunked HTTP message is received, then the callback is called once for each chunk; when the message has been received, then the receive callback is called with a hash representing any trailer data received in a chunked transfer or NOTHING if the data was received in a normal message body or if there was no trailer data in a chunked transfer. The argument to this callback is always a hash; data calls have the following keys:
  - `"data"`: the string or binary data
  - `"chunked"`: True if the data was received with chunked transfer encoding, False if not
  Header or trailer data is placed in a hash with the following keys:
  - `"hdr"`: this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message
  - `"info"`: this hash is passed when headers are received; in this case, the hash has at least the the following keys:
    - `"accept-charset"`: the value of any `"Accept-Charset"` header
    - `"accept-encoding"`: the value of any `"Accept-Encoding"` header
    - `"body-content-type"`: the value of the `"Content-Type"` header, if any, without any character set info
    - `"charset"`: any character set value found in the `"Content-Type"` header
    - `"response-headers-raw"`: a hash of unprocessed headers with no case conversions or additional keys
  - `"obj"`: this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)

  body | The message body to send; pass NOTHING (no value) to send no body
  method | The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
  path | The path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
  timeout_ms | the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
  getbody | If this argument is True, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.

  info

  An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Exceptions

  HTTP-CLIENT-METHOD-ERROR | invalid/unknown HTTP method passed
  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded
  HTTP-CLIENT-RECEIVE-ERROR | unknown content encoding received
  ENCODING-CONVERSION-ERROR | the given string could not be converted to the socket's character encoding
  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

Since
  - Qore 0.8.10
  - Qore 0.9.3 added support for the `response-headers-raw` info key

## sendWithSendCallback()

hash<auto> Qore::HTTPClient::sendWithSendCallback | ( | code | scb,
|  | string | method,
|  | *string | path,
|  | *hash< auto > | headers,
|  | timeout | timeout_ms = `0`,
|  | softbool | getbody = `False`,
|  | *reference< hash > | info
| ) |  |

Sends an HTTP request with the specified method and chunked message body as given by a send callback and returns headers and any body received as a response in a hash format.

If a connection has not already been established, an internal call to HTTPClient::connect() will be made before sending the message

Example:
  hash<auto> msg = httpclient.sendWithSendCallback(callback, "POST", "/path", ("Content-Type":"application/x-yaml"));

Parameters

  scb | The callback giving the chunked HTTP data to send; this callback must return either a string or a binary value each time it is called to give the chunked data to send; when all data has been sent, then a hash of message trailers can be sent or simply NOTHING which will close the chunked message
  method | The name of the HTTP method (`"GET"`, `"POST"`, `"HEAD"`, `"OPTIONS"`, `"PUT"`, `"DELETE"`, `"TRACE"`, `"CONNECT"`, or `"PATCH"`). Additional methods can be added in the constructor with the a `additional_methods` option.
  path | The path for the message (i.e. `"/path/resource?method&param=value"`)
  headers | An optional hash of headers to include in the message; values are converted to strings; a list is converted to a string of comma-separated values; headers that differ only in case will be overwritten by the last header in the hash with a matching name with a case-insensitive search
  timeout_ms | the timeout in milliseconds for the socket I/O operations; 0 means use the default timeout value
  getbody | If this argument is True, then the object will try to receive a message body even if no `"Content-Length"` header is present in the response. Use this only with broken servers that send message bodies without a `"Content-Length"` header.

  info

  An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request; this hash contains the following keys:
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `charset:` if there is a `"charset"` declaration in the `"Content-Type"` header, the value is returned in this key
  - `body-content-type`: the outgoing message body MIME `Content-Type` value
  - `headers:` a hash of outgoing HTTP request headers (returned as sent, without any case conversions)
  - `request-uri`: the request URI string sent (ex: `"GET /services/async/38.0/job HTTP/1.1"`)
  - `request-body`: the raw message body in the request (before any content encoding)
  - `response-body`: the raw message body in the response (after any content decoding)
  - `response-headers`: a hash of incoming HTTP headers in the response with keys converted to all lower case for each header in the response message, plus the following Qore-provided keys:
    - `http_version:` the HTTP version in the response URI
    - `status_code:` the HTTP status code of the response
    - `status_message:` the HTTP status message of the response
  - `response-headers-raw`: a hash of raw unprocessed incoming HTTP headers
  - `response-uri`: the HTTP response URI

Returns
  The headers received from the HTTP server with all key names converted to lower-case. The message body (if any) will be assigned to the value of the `"body"` key and the HTTP status will be assigned to the `"status_code"` key.

Exceptions

  HTTP-CLIENT-METHOD-ERROR | invalid/unknown HTTP method passed
  HTTP-CLIENT-REDIRECT-ERROR | invalid redirect location given by remote
  HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDED | maximum redirect count exceeded

  HTTP-CLIENT-RECEIVE-ERROR

  unknown content encoding received or status error communicating with HTTP server (status code < 100 or > 299); in case of a status error the `"arg"` key of the exception hash will be set to a hash equal to the normal return value of this method including a `"status_code"` key (giving the status code) and a `"body"` key (giving the message body returned by the server); note that this error is not raised for HTTP status codes indicating an error if the `error_passthru` option is set to True; see the `error_passthru` option in HTTPClient::constructor()

  ENCODING-CONVERSION-ERROR | the given string could not be converted to the socket's character encoding
  SOCKET-SEND-ERROR | There was an error sending the data
  SOCKET-CLOSED | The remote end closed the connection
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | Data transmission or reception for a single send() or recv() action exceeded the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | Invalid HTTP data was received

Note
  - The `"Transfer-Encoding: chunked"` header is automatically set with this method if no `"Transfer-Encoding"` header is already present
  - For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)

See also
  HTTP GET Requests With a Message Body

Since
  - Qore 0.8.10
  - Qore 0.9.3 added support for the `response-headers-raw` info key

## setAssumedEncoding()

Qore::HTTPClient::setAssumedEncoding | ( | *string | encoding | ) |

sets the assumed character encoding for messages from the HTTP server without any charset indicator

Example:
  httpclient.setAssumedEncoding("utf-8");

Parameters

  encoding | the encoding to set; if empty or not present, the default `"ISO-8859-1"` will be set

Since
  Qore 0.9.4.2

## setConnectionPath()

Qore::HTTPClient::setConnectionPath | ( | *string | uri_path | ) |

Overrides any connection path set in the URL.

Example:
  httpclient.setConnectionPath(new_path);

See also
  getConnectionPath()

Since
  Qore 0.9.3.2

## setConnectTimeout()

nothing Qore::HTTPClient::setConnectTimeout | ( | timeout | timeout_ms = `-1` | ) |

Sets the connect timeout in milliseconds.

Parameters

  timeout_ms | the connect timeout in milliseconds; negative numbers mean use the default system connect timeout. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `30s` = 30 seconds, etc.).

Example:
  httpclient.setConnectTimeout(2m);

## setDefaultPath()

nothing Qore::HTTPClient::setDefaultPath | ( | *string | path | ) |

Sets the default path used by the object if no path is set in the URL.

Parameters

  path | the default path value to set or if NOTHING then clears the path

Example:
  httpclient.setDefaultPath();

## setEncoding()

nothing Qore::HTTPClient::setEncoding | ( | string | encoding | ) |

Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding.

Parameters

  encoding | the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding

Example:
  httpclient.setEncoding("UTF-8");

## setEncodingPassthru()

bool Qore::HTTPClient::setEncodingPassthru | ( | bool | set = `True` | ) |

set the encoding passthru status

Example:
  httpclient.setEncodingPassthru();

Parameters

  set | if True then message bodies received with known content encodings are not decoded but rather passed through as-is

Returns
  the old `encoding_passthru` value

If True then message bodies received with known content encodings are not decoded but rather passed through as-is

Since
  Qore 0.9.3

## setErrorPassthru()

bool Qore::HTTPClient::setErrorPassthru | ( | bool | set = `True` | ) |

set the error passthru status

Example:
  httpclient.setErrorPassthru();

Parameters

  set | if True then HTTP status codes indicating errors will not cause an `HTTP-CLIENT-RECEIVE-ERROR` exception to be raised, rather such responses will be passed through to the caller like any other response

Returns
  the old `error_passthru` value

If True then HTTP status codes indicating errors will not cause an `HTTP-CLIENT-RECEIVE-ERROR` exception to be raised, rather such responses will be passed through to the caller like any other response.

Since
  Qore 0.9.3

## setEventQueue() [1/2]

nothing Qore::HTTPClient::setEventQueue | ( |  | ) |

Clears any Queue object that may be set on the HTTPClient object so that I/O events are no longer captured on the object.

Example:
  httpclient.setEventQueue();

## setEventQueue() [2/2]

nothing Qore::HTTPClient::setEventQueue | ( | Qore::Thread::Queue | queue,
|  | auto | arg,
|  | *bool | with_data
| ) |  |

Sets a Queue object to receive HTTPClient and Socket events.

Example:
  httpclient.setEventQueue(queue);

Parameters

  queue | a Queue object to receive HTTPClient and Socket events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
  arg | an argument that will be included in each event hash in the arg key
  with_data | if True, then the actual raw data transferred / received is also included in the events

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set

See also
  event_handling for more information

Since
  Qore 0.9.4 added the arg and with_data options

## setHTTPVersion()

nothing Qore::HTTPClient::setHTTPVersion | ( | string | ver | ) |

Sets the HTTP protocol version string for headers in outgoing messages, allowed values are `"1.0"` and "1.1".

Parameters

  ver | `"1.0"` or "1.1" for the HTTP protocol compliance version

Example:
  httpclient.setHTTPVersion("1.1");

Exceptions

  HTTP-VERSION-ERROR | invalid HTTP version passed (allowed values: `"1.0"` and "1.1")

## setMaxRedirects()

nothing Qore::HTTPClient::setMaxRedirects | ( | softint | mr = `0` | ) |

Updates the setting for the `max_redirects` value for the object (maximum number of HTTP redirects that will be processed before an exception is raised)

Parameters

  mr | the setting for the maximum number of HTTP redirects that will be processed before an exception is raised

Example:
  httpclient.setMaxRedirects(5);

See also
  HTTPClient::getMaxRedirects() to retrieve this value

## setNoDelay()

int Qore::HTTPClient::setNoDelay | ( | softbool | b = `True` | ) |

Sets the `TCP_NODELAY` setting for the object.

When this setting is True, then data will be immediately sent out over the HTTPClient object's socket, when it is False, then data transmission may be delayed to be packaged with other data for the same target.

Delayed data transmissions may cause problems when the sender immediately closes the socket after sending data; in this case the receiver may not get the data even though the send succeeded.

Note that if no value is given to the method, the argument will be assumed to be True, and output buffering will be turned off for the HTTPClient object.

If the socket is not connected when this call is made, then an internal flag is set and the `TCP_NODELAY` option is enabled when the next connection is established. If the socket is connected, then if an error occurs setting the `TCP_NODELAY` option on the socket, this method will return a non-zero error code; the actual error can be checked with the errno() function.

Example:
  httpclient.setNoDelay(True);

Parameters

  b | the `TCP_NODELAY` setting for the object

See also
  HTTPClient::getNoDelay()

## setPersistent()

Qore::HTTPClient::setPersistent | ( |  | ) |

temporarily disables implicit reconnections; must be called when the server is already connected

Example:
  httpclient.connect();
  httpclient.setPersistent();

The persistent flag is automatically reset to False whenever the connection is closed; it must be called manually for every connection to turn off implicit reconnections.

To turn off the persistent flag manually, call HTTPClient::disconnect()

Since
  Qore 0.8.10

## setProxySecure()

nothing Qore::HTTPClient::setProxySecure | ( | softbool | b = `True` | ) |

Sets the SSL/TLS flag for the next connection to the proxy.

Example:
  httpclient.setProxySecure(True);

See also
  HTTPClient::isProxySecure() to check the flag

## setProxyURL() [1/2]

nothing Qore::HTTPClient::setProxyURL | ( |  | ) |

Clears the new proxy URL value for the next connection.

This variant of the method is equivalent to HTTPClient::clearProxyURL()

Example:
  httpclient.setProxyURL();

## setProxyURL() [2/2]

nothing Qore::HTTPClient::setProxyURL | ( | string | url | ) |

Sets a new proxy URL value for the next connection.

Parameters

  url | the new proxy URL value for the next connection

Example:
  httpclient.setProxyURL("http://user:password@proxy_host:8080/path");

Exceptions

  HTTP-CLIENT-URL-ERROR | invalid proxy URL string; invalid authorization credentials in proxy URL (username without password or vice-versa)
  HTTP-CLIENT-PROXY-PROTOCOL-ERROR | unknown protocol passed in URL

Note
  URLs with UNIX sockets are generally supported in Qore with the following syntax: `scheme://socket=`url_encoded_path`/path`, where url_encoded_path is a path with URL-encoding as performed by encode_url(string, True); for example: `"http://socket=%2ftmp%socket-dir%2fsocket-file-1/url/path"`; this allows a filesystem path to be used in the host portion of the URL and for the URL to include a URL path as well.

## setProxyUserPassword() [1/2]

nothing Qore::HTTPClient::setProxyUserPassword | ( | string | user,
|  | string | pass
| ) |  |

Sets the username and password for the connection to the proxy; call after HTTPClient::setProxyURL()

Call this method after calling HTTPClient::setProxyURL() to set proxy authentication information when not present in the URL used in HTTPClient::setProxyURL()

Example:
  httpclient.setProxyUserPassword(user, pass);

Parameters

  user | the username to use for proxy authentication in the next HTTP connection
  pass | the password to use for proxy authentication in the next HTTP connection

## setProxyUserPassword() [2/2]

nothing Qore::HTTPClient::setProxyUserPassword | ( |  | ) |

Clears the username and password for the next proxy connection.

Call this method after calling HTTPClient::setProxyURL() to clear any proxy authentication information present in the URL used in HTTPClient::setProxyURL()

This variant of the method is equivalent to HTTPClient::clearProxyUserPassword()

Example:
  httpclient.setProxyUserPassword();

See also
  HTTPClient::clearProxyUserPassword()

## setRedirectPassthru()

bool Qore::HTTPClient::setRedirectPassthru | ( | bool | set = `True` | ) |

set the redirect passthru status

Example:
  httpclient.setRedirectPassthru();

Parameters

  set | if True then redirect messages will be passed to the caller instead of proceessed

Returns
  the old `reddirect_passthru` value

If True then redirect messages will be passed to the callers instead of proceessed

Since
  Qore 0.9.3

## setSecure()

nothing Qore::HTTPClient::setSecure | ( | softbool | secure = `True` | ) |

Sets the object to make a secure SSL/TLS connection on the next connect if the passed argument is True, or an unencrypted cleartext connection if it is False.

This method overrides the default behaviour for the protocol set for the object

Note that the behavior of this method when called with no argument changed in version 0.8.0; prior to version 0.8.0 calling this method with no argument would turn off secure mode; the behavior was changed to the current functionality in order to make the usage of this method consistent with other methods of the same name and to make it more logical.

Example:
  httpclient.setSecure(True);

Parameters

  secure | if True, a SSL/TLS connection will be attempted on the next connection. If False, an unencrypted cleartext connection will be established

## setTimeout()

nothing Qore::HTTPClient::setTimeout | ( | timeout | timeout_ms = `0` | ) |

Sets the default I/O timeout value in milliseconds.

Parameters

  timeout_ms | 0 means immediate timeout (when reading will return data only if it is already available), and negative numbers mean never timeout. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.).

Example:
  httpclient.setTimeout(2m);

## setURL()

Qore::HTTPClient::setURL | ( | string | url | ) |

Sets a new URL value for the next connection.

To retrieve the current URL value, use the HTTPClient::getURL() method

Example:
  httpclient.setURL("https://user:password@hostname:8080/path");

Parameters

  url | the new URL for the object

Exceptions

  HTTP-CLIENT-URL-ERROR | invalid URL string; invalid authorization credentials in URL (username without password or vice-versa)
  HTTP-CLIENT-UNKNOWN-PROTOCOL | unknown protocol (scheme) passed in URL

See also
  HTTPClient::getURL()

Note
  URLs with UNIX sockets are generally supported in Qore with the following syntax: `scheme://socket=`url_encoded_path`/path`, where url_encoded_path is a path with URL-encoding as performed by encode_url(string, True); for example: `"http://socket=%2ftmp%socket-dir%2fsocket-file-1/url/path"`; this allows a filesystem path to be used in the host portion of the URL and for the URL to include a URL path as well.

## setUserPassword() [1/2]

nothing Qore::HTTPClient::setUserPassword | ( | string | user,
|  | string | pass
| ) |  |

Sets the username and password for the connection; call after HTTPClient::setURL()

Call this method after calling HTTPClient::setURL() to set authentication information when not present in the URL used in HTTPClient::setURL()

Parameters

  user | the username to use for authentication in the next HTTP connection
  pass | the password to use for authentication in the next HTTP connection

Example:
  httpclient.setUserPassword(user, pass);

## setUserPassword() [2/2]

nothing Qore::HTTPClient::setUserPassword | ( |  | ) |

Clears the username and password for the connection.

Call this method after calling HTTPClient::setURL() to clear any authentication information present in the URL used in HTTPClient::setURL()

This variant of the method is equivalent to HTTPClient::clearUserPassword()

Example:
  httpclient.setUserPassword();

See also
  HTTPClient::clearUserPassword()

## setWarningQueue()

nothing Qore::HTTPClient::setWarningQueue | ( | int | warning_ms,
|  | int | warning_bs,
|  | Queue | queue,
|  | auto | arg,
|  | timeout | min_ms = `1s`
| ) |  |

Sets a Queue object to receive socket warnings.

Example:
  httpclient.setWarningQueue(5000, 5000, queue, "socket-1");

Parameters

  warning_ms

  the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys:
  - `"type"`: a string with the constant value `"SOCKET-OPERATION-WARNING"`
  - `"operation"`: a string giving the operation that caused the warning (ex: `"connect"`)
  - `"us"`: an integer giving the number of microseconds for the operation
  - `"timeout"`: an integer giving the warning threshold in microseconds
  - `"arg"`: if any `"arg"` argument is passed to the HTTPClient::setWarningQueue() method, it will be included in the warning hash here

  warning_bs

  value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with the following keys:
  - `"type"`: a string with the constant value `"SOCKET-THROUGHPUT-WARNING"`
  - `"dir"`: either `"send"` or `"recv"` depending on the direction of the data flow
  - `"bytes"`: the amount of bytes sent
  - `"us"`: an integer giving the number of microseconds for the operation
  - `"bytes_sec"`: a float giving the transfer speed in bytes per second
  - `"threshold"`: an integer giving the warning threshold in bytes per second
  - `"arg"`: if any `"arg"` argument is passed to the HTTPClient::setWarningQueue() method, it will be included in the warning hash here

  queue | the Queue object to receive warning events
  arg | an optional argument to be placed in the `"arg"` key in each warning hash (could be used to identify the socket for example)
  min_ms | the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set
  SOCKET-SETWARNINGQUEUE-ERROR | at least one of warning_ms and warning_bs must be > 0

See also
  HTTPClient::clearWarningQueue()

Since
  - Qore 0.8.9
  - Qore 0.8.12 the minimum threshold for a warning is a transfer of at least 1024 bytes, smaller transfers will not result in a warning