Qore Programming Language Reference Manual  0.8.7
 All Classes Namespaces Functions Variables Groups Pages
Qore::HTTPClient Class Reference

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

Public Member Functions

nothing clearProxyURL ()
 Clears the new proxy URL value for the next connection.
 
nothing clearProxyUserPassword ()
 Clears the username and password for the next proxy connection.
 
nothing clearUserPassword ()
 Clears the username and password for the connection.
 
nothing connect ()
 Connects to the remote socket; SSL/TLS negotiation is performed if required.
 
 constructor (hash opts)
 Creates the HTTPClient object based on the option parameter passed.
 
 constructor ()
 Creates the HTTPClient object.
 
 copy ()
 Copying objects of this class is not supported, an exception will be thrown.
 
 destructor ()
 Destroys the HTTPClient object and closes any open connections.
 
nothing disconnect ()
 Disconnects from the remote socket if a connection is established (otherwise does nothing)
 
*string get (string path, *hash headers, *reference info)
 Sends an HTTP GET request and returns the message body received as a string or NOTHING if no message body is received.
 
int getConnectTimeout ()
 Returns the connect timeout as an integer in milliseconds.
 
string getEncoding ()
 Returns the character encoding used for the object.
 
string getHTTPVersion ()
 Returns the HTTP protocol version string used in outgoing messages.
 
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)
 
bool getNoDelay ()
 Returns the TCP_NODELAY setting for the HTTPClient object.
 
hash getPeerInfo ()
 Returns a hash of information about the remote end for connected sockets.
 
*string getProxyURL ()
 Returns the current proxy URL as a string or NOTHING if no proxy URL is set.
 
*string getSSLCipherName ()
 Returns the name of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established.
 
*string getSSLCipherVersion ()
 Returns the version of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established.
 
hash getSocketInfo ()
 Returns information about the local socket as a hash.
 
int getTimeout ()
 Returns the default I/O timeout as an integer in milliseconds.
 
string getURL ()
 Returns the current URL.
 
hash head (string path, *hash headers, *reference info)
 Sends an HTTP HEAD request and returns as hash of the headers received.
 
bool isConnected ()
 Returns True or False giving the current connection state.
 
bool isProxySecure ()
 Returns the SSL/TLS flag for the next proxy connection.
 
bool isSecure ()
 Returns True if the current connection is encrypted, False if not.
 
*string post (string path, string body, *hash headers, *reference 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.
 
*string post (string path, *binary body, *hash headers, *reference 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.
 
hash send (string body, string method, *string path, *hash headers, softbool getbody=False, *reference 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.
 
hash send (*binary body, string method, string path, *hash headers, softbool getbody=False, *reference 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.
 
nothing setConnectTimeout (timeout timeout_ms=-1)
 Sets the connect timeout in milliseconds.
 
nothing setEncoding (string encoding)
 Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding.
 
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.
 
nothing setEventQueue (Qore::Thread::Queue queue)
 Sets a Queue object to receive HTTPClient and Socket events.
 
nothing setHTTPVersion (string ver)
 Sets the HTTP protocol version string for headers in outgoing messages, allowed values are "1.0" and "1.1".
 
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)
 
int setNoDelay (softbool b=True)
 Sets the TCP_NODELAY setting for the object.
 
nothing setProxySecure (softbool b=True)
 Sets the SSL/TLS flag for the next connection to the proxy.
 
nothing setProxyURL ()
 Clears the new proxy URL value for the next connection.
 
nothing setProxyURL (string url)
 Sets a new proxy URL value for the next connection.
 
nothing setProxyUserPassword (string user, string pass)
 Sets the username and password for the connection to the proxy; call after HTTPClient::setProxyURL()
 
nothing setProxyUserPassword ()
 Clears the username and password for the next proxy connection.
 
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.
 
nothing setTimeout (timeout timeout_ms=0)
 Sets the default I/O timeout value in milliseconds.
 
 setURL (string url)
 Sets a new URL value for the next connection.
 
nothing setUserPassword (string user, string pass)
 Sets the username and password for the connection; call after HTTPClient::setURL()
 
nothing setUserPassword ()
 Clears the username and password for the connection.
 
*string verifyPeerCertificate ()
 Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not established.
 

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 < 200 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 send, 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.6"
Connection "Keep-Alive"
Accept-Encoding "deflate,gzip,bzip2"

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.
Note
This class is not available with the PO_NO_NETWORK parse option.

Member Function Documentation

nothing Qore::HTTPClient::clearProxyURL ( )

Clears the new proxy URL value for the next connection.

Example:
$httpclient.setProxyURL();
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();
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();
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().

Events:
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED
Example:
$httpclient.connect();
Note
For possible exceptions, see the Socket::connect() method (or Socket::connectSSL() for secure connections).
Qore::HTTPClient::constructor ( hash  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().

Parameters
optssets options and changes default behaviour for the object, etc; key names are case-sensitive and therefore must all be in lower-case:
  • url: A string giving the URL to connect to
  • default_port: The default port number to connect to if none is given in the URL
  • 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
  • http_version: Either "1.0" or "1.1" for the claimed HTTP protocol version compliancy in outgoing message headers
  • default_path: The default path to use for new connections if a path is not otherwise specified in the connection URL
  • max_redirects: The maximum number of redirects before throwing an exception (the default is 5)
  • proxy: The proxy URL for connecting through a proxy
  • timeout: The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: 5m)
  • 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)
Example:
my HTTPClient $httpclient(("url":"http://hostname:8080/path"));
Exceptions
HTTP-CLIENT-OPTION-ERRORinvalid or unknown option passed in option hash
HTTP-CLIENT-URL-ERRORinvalid URL string
HTTP-CLIENT-UNKNOWN-PROTOCOLunknown protocol passed in URL
Qore::HTTPClient::constructor ( )

Creates the HTTPClient object.

Example:
my HTTPClient $httpclient();
Qore::HTTPClient::copy ( )

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

Exceptions
HTTPCLIENT-COPY-ERRORcopying HTTPClient objects is not yet supported
Qore::HTTPClient::destructor ( )

Destroys the HTTPClient object and closes any open connections.

Example:
delete $httpclient;
nothing Qore::HTTPClient::disconnect ( )

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

Example:
$httpclient.disconnect();
*string Qore::HTTPClient::get ( string  path,
*hash  headers,
*reference  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.

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.

Parameters
paththe path for the message (i.e. "/path/resource?method&param=value")
headersan optional hash of headers to include in the message
infoan 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
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
Example:
my *string $html = $httpclient.get("/path/file.html");
Exceptions
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown content encoding received or status error communicating with HTTP server (status code < 200 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash with a "code" key (giving the status code) and a "body" key (giving the message body returned by the server)
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
Note
For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)
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:
my int $to = $httpclient.getConnectTimeout();
string Qore::HTTPClient::getEncoding ( )

Returns the character encoding used for the object.

Returns
the character encoding used for the object
Code Flags:
CONSTANT
Example:
my string $encoding = $httpclient.getEncoding();
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:
my string $version = $httpclient.getHTTPVersion();
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:
my int $mr = $httpclient.getMaxRedirects();
bool Qore::HTTPClient::getNoDelay ( )

Returns the TCP_NODELAY setting for the HTTPClient object.

Code Flags:
CONSTANT
Example:
my bool $b = $httpclient.getNoDelay();
See Also
also HTTPClient::setNoDelay()
hash Qore::HTTPClient::getPeerInfo ( )

Returns a hash of information about the remote end for connected sockets.

If the socket is not connected, an exception is thrown

Example:
my hash $h = $httpclient.getPeerInfo();
Returns
a hash of information about the local socket
Exceptions
SOCKET-GETPEERINFO-ERRORthe underlying socket is not open or error in getpeername()
*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:
my *string $proxy_url = $httpclient.getProxyURL();
hash Qore::HTTPClient::getSocketInfo ( )

Returns information about the local socket as a hash.

If the socket is not open, an exception is thrown

Example:
my hash $h = $httpclient.getSocketInfo();
Returns
a hash of information about the remote end for connected sockets
Exceptions
SOCKET-GETSOCKETINFO-ERRORthe underlying socket is not open or error in getsockname()
*string Qore::HTTPClient::getSSLCipherName ( )

Returns the name of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established.

Returns
the name of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established
Code Flags:
CONSTANT
Example:
if ($httpclient.isSecure())
printf("secure connection: %s %s\n", $httpclient.getSSLCipherName(), $httpclient.getSSLCipherVersion());
*string Qore::HTTPClient::getSSLCipherVersion ( )

Returns the version of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established.

Returns
the version of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established
Code Flags:
CONSTANT
Example:
if ($httpclient.isSecure())
printf("secure connection: %s %s\n", $httpclient.getSSLCipherName(), $httpclient.getSSLCipherVersion());
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:
my int $timeout = $httpclient.getTimeout();
string Qore::HTTPClient::getURL ( )

Returns the current URL.

Returns
the current URL
Code Flags:
CONSTANT
Example:
my string $url = $httpclient.getURL();
hash Qore::HTTPClient::head ( string  path,
*hash  headers,
*reference  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.

Parameters
paththe path for the message (i.e. "/path/resource?method&param=value")
headersan optional hash of headers to include in the message
infoan 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
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
Example:
my hash $msg = $httpclient.head("/path");
Exceptions
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown content encoding received or status error communicating with HTTP server (status code < 200 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash with a "code" key (giving the status code) and a "body" key (giving the message body returned by the server)
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
Note
For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)
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:
my bool $b = $httpclient.isConnected();
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:
my bool $b = $httpclient.isProxySecure();
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());
*string Qore::HTTPClient::post ( string  path,
string  body,
*hash  headers,
*reference  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.

Parameters
paththe path for the message (i.e. "/path/resource?method&param=value")
bodythe string to use as the message body
headersan optional hash of headers to include in the message
infoan 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
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
Example:
$httpclient.post("/path", $body);
Exceptions
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown content encoding received or status error communicating with HTTP server (status code < 200 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash with a "code" key (giving the status code) and a "body" key (giving the message body returned by the server)
ENCODING-CONVERSION-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
Note
For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)
*string Qore::HTTPClient::post ( string  path,
*binary  body,
*hash  headers,
*reference  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.

Parameters
paththe path for the message (i.e. "/path/resource?method&param=value")
bodythe optional data to use as the message body
headersan optional hash of headers to include in the message
infoan 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
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
Example:
$httpclient.post("/path", $body);
Exceptions
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown content encoding received or status error communicating with HTTP server (status code < 200 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash with a "code" key (giving the status code) and a "body" key (giving the message body returned by the server)
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
Note
For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)
hash Qore::HTTPClient::send ( string  body,
string  method,
*string  path,
*hash  headers,
softbool  getbody = False,
*reference  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

Parameters
bodyThe message body to send
methodThe name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
pathThe path for the message (i.e. "/path/resource?method&param=value")
headersAn optional hash of headers to include in the message.
getbodyIf 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.
infoAn 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.
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.
Example:
my hash $msg = $httpclient.send($body, "POST", "/path", ("Content-Type":"application/x-yaml"));
Exceptions
HTTP-CLIENT-METHOD-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown content encoding received or status error communicating with HTTP server (status code < 200 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash with a "code" key (giving the status code) and a "body" key (giving the message body returned by the server)
ENCODING-CONVERSION-ERRORthe given string could not be converted to the socket's character encoding
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
Note
For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)
hash Qore::HTTPClient::send ( *binary  body,
string  method,
string  path,
*hash  headers,
softbool  getbody = False,
*reference  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

Parameters
bodyThe message body to send; pass NOTHING (no value) to send no body
methodThe name of the HTTP method ("GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE", or "CONNECT").
pathThe path for the message (i.e. "/path/resource?method&param=value")
headersAn optional hash of headers to include in the message.
getbodyIf 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.
infoAn 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.
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.
Example:
my hash $msg = $httpclient.send($body, "POST", "/path", ("Content-Type":"application/x-yaml"));
Exceptions
HTTP-CLIENT-METHOD-ERRORinvalid/unknown HTTP method passed
HTTP-CLIENT-REDIRECT-ERRORinvalid redirect location given by remote
HTTP-CLIENT-MAXIMUM-REDIRECTS-EXCEEDEDmaximum redirect count exceeded
HTTP-CLIENT-RECEIVE-ERRORunknown content encoding received or status error communicating with HTTP server (status code < 200 or > 299); in case of a status error the "arg" key of the exception hash will be set to a hash with a "code" key (giving the status code) and a "body" key (giving the message body returned by the server)
SOCKET-SEND-ERRORThere was an error sending the data
SOCKET-CLOSEDThe remote end closed the connection
SOCKET-RECV-ERRORThere was an error receiving the data
SOCKET-TIMEOUTData transmission or reception for a single send() or recv() action exceeded the timeout period
SOCKET-SSL-ERRORThere was an SSL error while reading data from the socket
SOCKET-HTTP-ERRORInvalid HTTP data was received
Note
For possible exceptions when implicitly establishing a connection, see the Socket::connect() method (or Socket::connectSSL() for secure connections)
nothing Qore::HTTPClient::setConnectTimeout ( timeout  timeout_ms = -1)

Sets the connect timeout in milliseconds.

Parameters
timeout_msthe 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);
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
encodingthe string encoding for the object; any strings deserialized with this object will be tagged with this character encoding
Example:
$httpclient.setEncoding("UTF-8");
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();
nothing Qore::HTTPClient::setEventQueue ( Qore::Thread::Queue  queue)

Sets a Queue object to receive HTTPClient and Socket events.

Parameters
queuea 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
Example:
$httpclient.setEventQueue($queue);
Exceptions
QUEUE-ERRORthe Queue passed has a maximum size set
See Also
event_handling for more information
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-ERRORinvalid HTTP version passed (allowed values: "1.0" and "1.1")
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
mrthe 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
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.

Parameters
bthe TCP_NODELAY setting for the object
Example:
$httpclient.setNoDelay(True);
See Also
HTTPClient::getNoDelay()
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
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();
nothing Qore::HTTPClient::setProxyURL ( string  url)

Sets a new proxy URL value for the next connection.

Parameters
urlthe new proxy URL value for the next connection
Example:
$httpclient.setProxyURL("http://user:password@proxy_host:8080/path");
Exceptions
HTTP-CLIENT-URL-ERRORinvalid proxy URL string; invalid authorization credentials in proxy URL (username without password or vice-versa)
HTTP-CLIENT-PROXY-PROTOCOL-ERRORunknown protocol passed in URL
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()

Parameters
userthe username to use for proxy authentication in the next HTTP connection
passthe password to use for proxy authentication in the next HTTP connection
Example:
$httpclient.setProxyUserPassword($user, $pass);
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()
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.

Parameters
secureif True, a SSL/TLS connection will be attempted on the next connection. If False, an unencrypted cleartext connection will be established
Example:
$httpclient.setSecure(True);
nothing Qore::HTTPClient::setTimeout ( timeout  timeout_ms = 0)

Sets the default I/O timeout value in milliseconds.

Parameters
timeout_ms0 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);
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

Parameters
urlthe new URL for the object
Example:
$httpclient.setURL("https://user:password@hostname:8080/path");
Exceptions
HTTP-CLIENT-URL-ERRORinvalid URL string; invalid authorization credentials in URL (username without password or vice-versa)
HTTP-CLIENT-UNKNOWN-PROTOCOLunknown protocol (scheme) passed in URL
See Also
HTTPClient::getURL()
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
userthe username to use for authentication in the next HTTP connection
passthe password to use for authentication in the next HTTP connection
Example:
$httpclient.setUserPassword($user, $pass);
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()
*string Qore::HTTPClient::verifyPeerCertificate ( )

Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not established.

Returns
A string code giving the result of verifying the peer's certificate or NOTHING if a secure connection has not been established. The possible values are found in the keys of the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result.
Code Flags:
CONSTANT
Example:
if ($httpclient.isSecure() && exists (my *string $str = $httpclient.verifyPeerCertificate())) {
printf("certificate: %s: %s\n", $str, X509_VerificationReasons.$str);