4.10. HTTPClient Class

Note: This class is not available with the PO_NO_NETWORK parse option.

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 number of redirects 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 read timeout value.

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

The default read timeout value is 300,000 milliseconds (5 minutes). Note that the read timeout value applies to individual packets; for this reason for large transfers the overall read time could exceed the read 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.

Table 4.532. HTTPClient Class Protocols

Protocol

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.

Table 4.533. 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.


Table 4.534. HTTPClient Default, but Overridable Headers

Header

Default Value

Accept

text/html

Content-Type

text/html

User-Agent

Qore HTTP Client v0.7.8

Connection

Keep-Alive

Accept-Encoding

deflate,gzip,bzip2


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

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

Table 4.535. 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.


The following table gives an overview of the methods available in the HTTPClient class.

Table 4.536. HTTPClient Class Method Overview

Method

Except?

Description

HTTPClient::constructor()

Y

Creates the HTTPClient object based on the parameters passed.

HTTPClient::destructor()

N

Destroys the HTTPClient object and closes any open connections.

HTTPClient::copy()

Y

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

HTTPClient::getURL()

N

Returns the current URL.

HTTPClient::setURL()

Y

Sets a new URL value for the next connection.

HTTPClient::getProxyURL()

N

Returns the current proxy URL.

HTTPClient::setProxyURL()

Y

Sets a new proxy URL value for the next connection.

HTTPClient::clearProxyURL()

N

Clears the proxy URL value.

HTTPClient::setProxySecure()

N

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

HTTPClient::isProxySecure()

N

Returns the SSL/TLS flag.

HTTPClient::getMaxRedirects()

N

Returns the current max_redirects value.

HTTPClient::setMaxRedirects()

N

Updates the max_redirects value.

HTTPClient::connect()

N

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

HTTPClient::disconnect()

N

Disconnects from the remote socket

HTTPClient::get()

Y

Sends an HTTP GET request and returns the message body received. In order to get the headers and the body, use the HTTPClient::send() method instead. If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

HTTPClient::head()

Y

Sends an HTTP HEAD request and returns the headers received. If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

HTTPClient::post()

Y

Sends an HTTP POST request with a message body and returns the message body received as a response. 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.

HTTPClient::send()

Y

Sends an HTTP request with the specified method and optional message body and returns headers and optionally the body received as a response in a hash format. If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message.

HTTPClient::setConnectTimeout()

N

Sets 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.).

HTTPClient::setTimeout()

N

Sets the default read timeout in milliseconds. Zero means immediate timeout (will return data only if it is already available), and negative numbers mean never timeout (wait forever for data). 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.).

HTTPClient::getConnectTimeout()

N

Returns the connect timeout as an integer in milliseconds. Negative numbers mean the system default timeout is used.

HTTPClient::getTimeout()

N

Returns the default read timeout as an integer in milliseconds. Zero means immediate timeout (only returns data if it is already available), and negative numbers mean never timeout (wait forever for data).

HTTPClient::setHTTPVersion()

Y

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

HTTPClient::getHTTPVersion()

N

Returns the HTTP protocol version string used in outgoing messages.

HTTPClient::setSecure()

N

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 not True or if no argument is passed. This method overrides the default behaviour for the protocol set for the object.

HTTPClient::isSecure()

N

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

HTTPClient::verifyPeerCertificate()

N

Returns a string code giving the result of verifying the remote certificate. Return value are the keys described in the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result.

HTTPClient::getSSLCipherName()

N

Returns the name of the cipher for an encrypted connection.

HTTPClient::getSSLCipherVersion()

N

Returns the version of the cipher for an encrypted connection.

HTTPClient::setEncoding()

Y

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

HTTPClient::getEncoding()

N

Returns the character encoding used for the object

HTTPClient::setEventQueue()

N

Sets a Queue object to receive HTTPClient and Socket events.

HTTPClient::getNoDelay()

N

Returns the TCP_NODELAY setting for the object.

HTTPClient::setNoDelay()

N

Sets the TCP_NODELAY setting for the object.

HTTPClient::isConnected()

N

Returns True or False giving the current connection state.


4.10.1. HTTPClient::constructor()

Synopsis

Creates the HTTPClient object based on the parameters passed. To connect, call any method that requires a connection and an implicit connection is established, or call HTTPClient::connect().

Usage
new HTTPClient([opts])
Example
$httpclient = new HTTPClient(("url":"http://hostname:8080/path"));

Table 4.537. Arguments for HTTPClient::constructor()

Argument

Type

Description

[opts]

Hash

sets options and changes default behaviour for the object, etc. See the table below for information on valid keys and their mening. Note that the key names are case-sensitive and therefore must all be in lower-case.


Table 4.538. HTTPClient::constructor() Option Hash Keys

Key

Description

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)


Table 4.539. Return Values for HTTPClient::constructor()

Return Type

Description

Object

The HTTPClient object is returned


Table 4.540. Exceptions thrown by HTTPClient::constructor()

err

desc

HTTP-CLIENT-CONSTRUCTOR-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


4.10.2. HTTPClient::destructor()

Synopsis

Destroys the HTTPClient object and closes any open connections.

Usage
delete lvalue
Example
delete $httpclient;
Events
EVENT_CHANNEL_CLOSED, EVENT_DELETED

Table 4.541. Arguments for HTTPClient::destructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.542. Return Values for HTTPClient::destructor()

Return Type

Description

n/a

This method returns no value


4.10.3. HTTPClient::copy()

Synopsis

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

Table 4.543. Arguments for HTTPClient::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.544. Return Values for HTTPClient::copy()

Return Type

Description

n/a

This method returns no value


Table 4.545. Exceptions thrown by HTTPClient::copy()

err

desc

HTTP-CLIENT-COPY-ERROR

objects of this class may not be copied


4.10.4. HTTPClient::getURL()

Synopsis

Returns the current URL value for the object. To set the URL, use the HTTPClient::setURL() method.

Usage
HTTPClient::getURL()
Example
$url = $httpclient.getURL();

Table 4.546. Arguments for HTTPClient::getURL()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.547. Return Values for HTTPClient::get()

Return Type

Description

String

The current URL value.


4.10.5. HTTPClient::setURL()

Synopsis

Sets the URL value for the object. To retrieve the current URL value, use the HTTPClient::getURL() method.

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

Table 4.548. Arguments for HTTPClient::setURL()

Argument

Type

Description

url

String

The new URL for the object.


Table 4.549. Return Values for HTTPClient::set()

Return Type

Description

n/a

This method does not return any value.


Table 4.550. Exceptions thrown by HTTPClient::setURL()

err

desc

HTTP-CLIENT-URL-ERROR

invalid URL string

HTTP-CLIENT-UNKNOWN-PROTOCOL

unknown protocol passed in URL


4.10.6. HTTPClient::getProxyURL()

Synopsis

Returns the current proxy URL value for the object (NOTHING if no proxy URL is set). To set the proxy URL, use the HTTPClient::setProxyURL() method.

Usage
HTTPClient::getProxyURL()
Example
$proxy_url = $httpclient.getProxyURL();

Table 4.551. Arguments for HTTPClient::getProxyURL()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.552. Return Values for HTTPClient::getProxyURL()

Return Type

Description

String

The current proxy URL value.


4.10.7. HTTPClient::setProxyURL()

Synopsis

Sets the proxy URL value for the object. To retrieve the current URL value, use the HTTPClient::getProxyURL() method.

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

Table 4.553. Arguments for HTTPClient::setProxyURL()

Argument

Type

Description

url

String

The new proxy URL for the object.


Table 4.554. Return Values for HTTPClient::setProxyURL()

Return Type

Description

n/a

This method does not return any value.


Table 4.555. Exceptions thrown by HTTPClient::setProxyURL()

err

desc

HTTP-CLIENT-URL-ERROR

invalid URL string

HTTP-CLIENT-SET-PROXY-ERROR

invalid authorization credentials in proxy URL (username without password or vice-versa)

HTTP-CLIENT-PROXY-PROTOCOL-ERROR

unknown protocol passed in URL


4.10.8. HTTPClient::clearProxyURL()

Synopsis

Clears the current proxy URL

Usage
HTTPClient::clearProxyURL()
Example
$httpclient.clearProxyURL();

Table 4.556. Arguments for HTTPClient::clearProxyURL()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.557. Return Values for HTTPClient::clearProxyURL()

Return Type

Description

n/a

This method does not return any value.


4.10.9. HTTPClient::setProxySecure()

Synopsis

Sets the SSL/TLS flag for the next proxy connection. To check the flag, use the HTTPClient::isProxySecure() method.

Usage
HTTPClient::setProxySecure(boolean)
Example
$httpclient.setProxySecure(True);

Table 4.558. Arguments for HTTPClient::setProxySecure()

Argument

Type

Description

boolean

Boolean

sets the SSL/TLS flag for the next proxy connection


Table 4.559. Return Values for HTTPClient::setProxySecure()

Return Type

Description

n/a

This method does not return any value.


4.10.10. HTTPClient::isProxySecure()

Synopsis

Returns the SSL/TLS flag for proxy connection. To set the flag, use the HTTPClient::setProxySecure() method.

Usage
HTTPClient::isProxySecure()
Example
$bool = $httpclient.isProxySecure();

Table 4.560. Arguments for HTTPClient::isProxySecure()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.561. Return Values for HTTPClient::isProxySecure()

Return Type

Description

Boolean

The value of the SSL/TLS flag for the proxy connection.


4.10.11. HTTPClient::getMaxRedirects()

Synopsis

Returns the maximum number of redirects allowed for the object. To set this value, use the HTTPClient::setMaxRedirects() method.

Usage
HTTPClient::getMaxRedirects()
Example
$num = $httpclient.getMaxRedirects();

Table 4.562. Arguments for HTTPClient::getMaxRedirects()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.563. Return Values for HTTPClient::getMaxRedirects()

Return Type

Description

Integer

The current value of the max_redirects setting.


4.10.12. HTTPClient::setMaxRedirects()

Synopsis

Sets the maximum number of redirects allowed for the object. To retrieve this value, use the HTTPClient::getMaxRedirects() method.

Usage
HTTPClient::setMaxRedirects(max_redirects)
Example
$httpclient.setMaxRedirects(0); # disable redirections

Table 4.564. Arguments for HTTPClient::setMaxRedirects()

Argument

Type

Description

max_redirects

Integer

The maximum number of HTTP redirects allowed for hte object before an exception is thrown.


Table 4.565. Return Values for HTTPClient::setMaxRedirects()

Return Type

Description

n/a

This method does not return any value.


4.10.13. HTTPClient::connect()

Synopsis

Connects to the remote socket. If the protocol indicates that a secure connection should be established (or HTTPClient::setSecure() was called previsouly), SSL/TLS negotiation will be attempted. Note: For possible exceptions, see the Socket::connect() method (or Socket::connectSSL() for secure connections).

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().

Usage
HTTPClient::connect()
Example
$httpclient.connect();
Events
EVENT_CONNECTING, EVENT_CONNECTED,EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Table 4.566. Arguments for HTTPClient::connect()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.567. Return Values for HTTPClient::connect()

Return Type

Description

n/a

This method returns no value


Table 4.568. Exceptions thrown by HTTPClient::connect()

err

desc

HTTP-CLIENT-MAXIMUM-.REDIRECTS-EXCEEDED

The attempt to connect exceeeded the maximum number of redirects allowed for the object.

HTTP-CLIENT-RECEIVE-ERROR

There was an error receiving data on the socket

HTTP-CLIENT-TIMEOUT

The receive attempt timed out.


4.10.14. HTTPClient::disconnect()

Synopsis

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

Usage
HTTPClient::disconnect()
Example
$httpclient.disconnect();
Events
EVENT_CHANNEL_CLOSED

Table 4.569. Arguments for HTTPClient::disconnect()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.570. Return Values for HTTPClient::disconnect()

Return Type

Description

n/a

This method returns no value


4.10.15. HTTPClient::get()

Synopsis

Sends an HTTP GET request and returns the message body received. In order to get the headers and the body, use the HTTPClient::send() method instead. If necessary, a connection will be established via an implicit call to HTTPClient::connect() before sending the message.

Usage
HTTPClient::get(path, [headers], [info_reference])
Example
$html = $httpclient.get("/path/file.html");
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

Table 4.571. Arguments for HTTPClient::get()

Argument

Type

Description

path

String

The path for the message (i.e. '/path/resource?method&param=value')

[headers]

Hash

An optional hash of headers to include in the message.

[info_reference]

LValue Reference

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.


Table 4.572. Return Values for HTTPClient::get()

Return Type

Description

String

The message body returned.


Table 4.573. Exceptions thrown by HTTPClient::get()

err

desc

HTTP-CLIENT-TIMEOUT

timeout on response from HTTP server

HTTP-CLIENT-RECEIVE-ERROR

error communicating with HTTP server


4.10.16. HTTPClient::head()

Synopsis

Sends an HTTP HEAD request and returns the headers received. If necessary, a connection will be established via an implicit call to HTTPClient::connect() before sending the message.

Usage
HTTPClient::head(path, [headers])
Example
$response = $httpclient.head("/path");
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

Table 4.574. Arguments for HTTPClient::head()

Argument

Type

Description

path

String

The path for the message (i.e. '/path/resource?method&param=value')

[headers]

Hash

An optional hash of headers to include in the message.


Table 4.575. Return Values for HTTPClient::head()

Return Type

Description

Hash

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


Table 4.576. Exceptions thrown by HTTPClient::head()

err

desc

HTTP-CLIENT-TIMEOUT

timeout on response from HTTP server

HTTP-CLIENT-RECEIVE-ERROR

error communicating with HTTP server


4.10.17. HTTPClient::post()

Synopsis

Sends an HTTP POST request with a message body and returns the message body received as a response. In order to get the headers and the body, use the HTTPClient::send() method instead. If necessary, a connection will be established via an implicit call to HTTPClient::connect() before sending the message.

Usage
HTTPClient::post(path, message, [headers], [info_reference])

Table 4.577. Arguments for HTTPClient::post()

Argument

Type

Description

path

String

The path for the message (i.e. '/path/resource?method&param=value')

message

String or Binary

The message body to send.

[headers]

Hash

An optional hash of headers to include in the message.

[info_reference]

LValue Reference

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.


Table 4.578. Return Values for HTTPClient::post()

Return Type

Description

String

The message body returned.


Table 4.579. Exceptions thrown by HTTPClient::post()

err

desc

HTTP-CLIENT-TIMEOUT

timeout on response from HTTP server

HTTP-CLIENT-RECEIVE-ERROR

error communicating with HTTP server


4.10.18. HTTPClient::send()

Synopsis

Sends an HTTP request with the specified method and optional message body and returns headers and optionally the body received as a response in a hash format. If necessary, a connection will be established via an implicit call to HTTPClient::connect() before sending the message.

Usage
HTTPClient::send(message, method, path, [headers], [get_body], [info_reference])
Example
$msg = $httpclient.send($body, "POST", "/path", ("Connection":"Keep-Alive"));
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

Table 4.580. Arguments for HTTPClient::send()

Argument

Type

Description

message

String or Binary

The message body to send.

method

String

The name of the HTTP method ('GET', 'POST', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE', or 'CONNECT').

path

String

The path for the message (i.e. '/path/resource?method&param=value')

[headers]

Hash

An optional hash of headers to include in the message.

[get_body]

Boolean

if set to True (default is False), then even if the server did not return a 'Content-Length' header in the response, the object will try to read a message body from the socket anyway. Use this only with broken servers that send messages bodies without a 'Content-Length' header.

[info_reference]

LValue Reference

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.


Table 4.581. Return Values for HTTPClient::send()

Return Type

Description

Hash

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.


Table 4.582. Exceptions thrown by HTTPClient::send()

err

desc

HTTP-CLIENT-TIMEOUT

timeout on response from HTTP server

HTTP-CLIENT-RECEIVE-ERROR

error communicating with HTTP server

HTTP-CLIENT-METHOD-ERROR

invalid HTTP method passed


4.10.19. HTTPClient::setConnectTimeout()

Synopsis

Sets the default connect timeout in milliseconds. Negative numbers mean use the default system 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.).

Usage
HTTPClient::setConnectTimeout(timeout)
Example
$httpclient.setConnectTimeout(2m); # sets timeout to 2 minutes

Table 4.583. Arguments for HTTPClient::setConnectTimeout()

Argument

Type

Description

timeout

Integer or Relative Date/Time

Connect timeout in milliseconds, 0 = immediate timeout (do not use), negative numbers = use system default connect timeout.


Table 4.584. Return Values for HTTPClient::setConnectTimeout()

Return Type

Description

n/a

This method returns no value


4.10.20. HTTPClient::setTimeout()

Synopsis

Sets the default read timeout in milliseconds. Zero means immediate timeout (will return data only if it is already available), and negative numbers mean never timeout (wait forever for data). 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.).

Usage
HTTPClient::setTimeout(timeout)
Example
$httpclient.setTimeout(2m); # sets timeout to 2 minutes

Table 4.585. Arguments for HTTPClient::setTimeout()

Argument

Type

Description

timeout

Integer or Relative Date/Time

Read timeout in milliseconds, 0 = immediate timeout, negative numbers = never timeout.


Table 4.586. Return Values for HTTPClient::setTimeout()

Return Type

Description

n/a

This method returns no value


4.10.21. HTTPClient::getConnectTimeout()

Synopsis

Returns the connect timeout as an integer in milliseconds. Negative numbers mean the default system timeout is used instead.

Usage
HTTPClient::getConnectTimeout()
Example
$timeout = $httpclient.getConnectTimeout();

Table 4.587. Arguments for HTTPClient::getConnectTimeout()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.588. Return Values for HTTPClient::getConnectTimeout()

Return Type

Description

Integer

The connect timeout value in milliseconds


4.10.22. HTTPClient::getTimeout()

Synopsis

Returns the default read timeout as an integer in milliseconds. Zero means immediate timeout (only returns data if it is already available), and negative numbers mean never timeout (wait forever for data).

Usage
HTTPClient::getTimeout()
Example
$timeout = $httpclient.getTimeout();

Table 4.589. Arguments for HTTPClient::getTimeout()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.590. Return Values for HTTPClient::getTimeout()

Return Type

Description

Integer

The read timeout value in milliseconds


4.10.23. HTTPClient::setHTTPVersion()

Synopsis

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

Usage
HTTPClient::setHTTPVersion(version)
Example
$httpclient.setHTTPVersion("1.1");

Table 4.591. Arguments for HTTPClient::setHTTPVersion()

Argument

Type

Description

version

String

either '1.0' or '1.1' for the HTTP protocol compliance version.


Table 4.592. Return Values for HTTPClient::setHTTPVersion()

Return Type

Description

n/a

This method returns no value


Table 4.593. Exceptions thrown by HTTPClient::setHTTPVersion()

err

desc

HTTP-VERSION-ERROR

invalid HTTP version passed (allowed values: '1.0', '1.1').


4.10.24. HTTPClient::getHTTPVersion()

Synopsis

Returns the HTTP protocol version string used in outgoing messages.

Usage
HTTPClient::getHTTPVersion()
Example
$version = $httpclient.getHTTPVersion();

Table 4.594. Arguments for HTTPClient::getHTTPVersion()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.595. Return Values for HTTPClient::getHTTPVersion()

Return Type

Description

String

The HTTP protocol version string used in outgoing messages (either '1.0' or '1.1').


4.10.25. HTTPClient::setSecure()

Synopsis

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 not True or if no argument is passed. This method overrides the default behaviour for the protocol set for the object.

Usage
HTTPClient::setSecure([secure])
Example
$httpclient.setSecure(True);

Table 4.596. Arguments for HTTPClient::setSecure()

Argument

Type

Description

[secure]

Boolean

If True, a SSL/TLS connection will be attempted on the next connection. If not True or missing, an unencrypted cleartext connection will be established.


Table 4.597. Return Values for HTTPClient::setSecure()

Return Type

Description

n/a

This method returns no value


4.10.26. HTTPClient::isSecure()

Synopsis

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

Usage
HTTPClient::isSecure()
Example
$bool = $httpclient.isSecure();

Table 4.598. Arguments for HTTPClient::isSecure()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.599. Return Values for HTTPClient::isSecure()

Return Type

Description

Boolean

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


4.10.27. HTTPClient::verifyPeerCertificate()

Synopsis

Returns a string code giving the result of verifying the remote certificate. Return value are the keys described in the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result.

Usage
HTTPClient::verifyPeerCertificate()
Example
$str = $httpclient.verifyPeerCertificate();

Table 4.600. Arguments for HTTPClient::verifyPeerCertificate()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.601. Return Values for HTTPClient::verifyPeerCertificate()

Return Type

Description

String

A string code giving the result of verifying the peer's certificate. No value is returned if no secure connection has been established.


4.10.28. HTTPClient::getSSLCipherName()

Synopsis

Returns the name of the cipher for an encrypted connection.

Usage
HTTPClient::getSSLCipherName()
Example
$str = $httpclient.getSSLCipherName();

Table 4.602. Arguments for HTTPClient::getSSLCipherName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.603. Return Values for HTTPClient::getSSLCipherName()

Return Type

Description

String

The name of the cipher for a secure connection. No value is returned if no secure connection has been established.


4.10.29. HTTPClient::getSSLCipherVersion()

Synopsis

Returns the version of the cipher for an encrypted connection.

Usage
HTTPClient::getSSLCipherVersion()
Example
$str = $httpclient.getSSLCipherVersion();

Table 4.604. Arguments for HTTPClient::getSSLCipherVersion()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.605. Return Values for HTTPClient::getSSLCipherVersion()

Return Type

Description

String

The version of the cipher for a secure connection. No value is returned if no secure connection has been established.


4.10.30. HTTPClient::setEncoding()

Synopsis

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

Usage
HTTPClient::setEncoding(encoding)
Example
$httpclient.setEncoding("ISO-8859-1");

Table 4.606. Arguments for HTTPClient::setEncoding()

Argument

Type

Description

encoding

String

The string encoding to use for this object.


Table 4.607. Return Values for HTTPClient::setEncoding()

Return Type

Description

n/a

This method returns no value


Table 4.608. Exceptions thrown by HTTPClient::setEncoding()

err

desc

HTTP-CLIENT-SETSTRINGENCODING-ERROR

missing encoding parameter from method call


4.10.31. HTTPClient::getEncoding()

Synopsis

Returns the character encoding used for the object

Usage
HTTPClient::getEncoding()
Example
$str = $httpclient.getEncoding();

Table 4.609. Arguments for HTTPClient::getEncoding()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.610. Return Values for HTTPClient::getEncoding()

Return Type

Description

String

The character encoding used for the object.


4.10.32. HTTPClient::setEventQueue()

Synopsis

Sets a Queue object to receive HTTPClient and Socket events. To remove the event queue and stop monitoring events, pass NOTHING to the method. See Event Handling for more information.

Usage
HTTPClient::setEventQueue([queue])
Example
$httpclient.setEventQueue($queue);

Table 4.611. Arguments for HTTPClient::setEventQueue()

Argument

Type

Description

[queue]

Queue

To set the event queue, pass a Queue object; to clear the event queue, pass no argument to the function.


Table 4.612. Return Values for HTTPClient::setEventQueue()

Return Type

Description

n/a

This method does not return any value.


4.10.33. HTTPClient::getNoDelay()

Synopsis

Returns the TCP_NODELAY setting for the HTTPClient object. See also HTTPClient::setNoDelay().

Usage
HTTPClient::getNoDelay()
Example
$nodelay = $httpclient.getNoDelay();

Table 4.613. Arguments for HTTPClient::getNoDelay()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.614. Return Value for HTTPClient::getNoDelay()

Return Type

Description

Boolean

The TCP_NODELAY setting for the HTTPClient object.


4.10.34. HTTPClient::setNoDelay()

Synopsis

Sets the TCP_NODELAY setting for the HTTPClient 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 False, and output buffering will be turned on for the HTTPClient object, which may be the opposite of what the programmer intends, therefore it's recommended to always pass an argument to this method.

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.

See also HTTPClient::getNoDelay().

Usage
HTTPClient::setNoDelay(boolean)
Example
$httpclient.setNoDelay(True);

Table 4.615. Arguments for HTTPClient::setNoDelay()

Argument

Type

Description

boolean

boolean

The TCP_NODELAY setting for the HTTPClient.


Table 4.616. Return Value for HTTPClient::setNoDelay()

Return Type

Description

Integer

0 for success, non-zero for errors. To get error information, see errno() and strerror().


4.10.35. HTTPClient::isConnected()

Synopsis

Returns the connection state of the HTTPClient object. Connections are implicitly established whenever a method is callde requiring a connection; to explicitly establish a connection, see HTTPClient::connect().

Usage
HTTPClient::isConnected()
Example
$connected = $httpclient.isConnected();

Table 4.617. Arguments for HTTPClient::isConnected()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.618. Return Value for HTTPClient::isConnected()

Return Type

Description

Boolean

The connection state of the HTTPClient object.