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 |
---|---|---|---|
| 80 | No | Unencrypted HTTP protocol |
| 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 |
---|---|
| 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 |
---|---|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|
Raised when the HTTP "Content-Length" header is received. | |
Raised when HTTP chunked data is about to be received. | |
Raised when all HTTP chunked data has been received. | |
Raised when an HTTP redirect message is received. | |
Raised when an HTTP message is sent. | |
Raised when an HTTP message is received. | |
Raised when HTTP footers are received. | |
Raised when a block of HTTP chunked data is received. | |
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 |
---|---|---|
Y |
Creates the HTTPClient object based on the parameters passed. | |
N |
Destroys the HTTPClient object and closes any open connections. | |
Y | Copying objects of this class is not supported, an exception will be thrown. | |
N | Returns the current URL. | |
Y | Sets a new URL value for the next connection. | |
N | Returns the current proxy URL. | |
Y | Sets a new proxy URL value for the next connection. | |
N | Clears the proxy URL value. | |
N | Sets the SSL/TLS flag for the next connection to the proxy. | |
N | Returns the SSL/TLS flag. | |
N | Returns the current | |
N | Updates the | |
N |
Connects to the remote socket; SSL/TLS negotiation is performed if required. | |
N |
Disconnects from the remote socket | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
N | Returns the connect timeout as an integer in milliseconds. Negative numbers mean the system default timeout is used. | |
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). | |
Y |
Sets the HTTP protocol version string for headers in outgoing messages, allowed values are '1.0' and '1.1'. | |
N |
Returns the HTTP protocol version string used in outgoing messages. | |
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. | |
N |
Returns True if the current connection is encrypted, False if not. | |
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. | |
N |
Returns the name of the cipher for an encrypted connection. | |
N |
Returns the version of the cipher for an encrypted connection. | |
Y |
Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding. | |
N | Returns the character encoding used for the object | |
N | Sets a Queue object to receive HTTPClient and Socket events. | |
N | Returns the | |
N | Sets the | |
N | Returns True or False giving the current connection state. |
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().
new HTTPClient([opts]
)
$httpclient = new HTTPClient(("url":"http://hostname:8080/path"));
Table 4.537. Arguments for HTTPClient::constructor()
Argument |
Type |
Description |
---|---|---|
|
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 |
---|---|
| A string giving the URL to connect to. |
| The default port number to connect to if none is given in the URL. |
| 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. |
| Either '1.0' or '1.1' for the claimed HTTP protocol version compliancy in outgoing message headers. |
| The default path to use for new connections if a path is not otherwise specified in the connection URL. |
| The maximum number of redirects before throwing an exception (the default is 5). |
| The proxy URL for connecting through a proxy. |
| The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: |
| The timeout value in milliseconds for establishing a new socket connection (also can be a relative date-time value for clarity, ex: |
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 |
---|---|
| invalid or unknown option passed in option hash |
| invalid URL string |
| unknown protocol passed in URL |
Destroys the HTTPClient object and closes any open connections.
delete lvalue
delete $httpclient;
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 |
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 |
---|---|
|
objects of this class may not be copied |
Returns the current URL value for the object. To set the URL, use the HTTPClient::setURL() method.
HTTPClient::getURL()
$url = $httpclient.getURL();
Table 4.546. Arguments for HTTPClient::getURL()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Sets the URL value for the object. To retrieve the current URL value, use the HTTPClient::getURL() method.
HTTPClient::setURL(url
)
$httpclient.setURL("https://user:password@hostname:8080/path");
Table 4.548. Arguments for HTTPClient::setURL()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| invalid URL string |
| unknown protocol passed in URL |
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.
HTTPClient::getProxyURL()
$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. |
Sets the proxy URL value for the object. To retrieve the current URL value, use the HTTPClient::getProxyURL() method.
HTTPClient::setProxyURL(url
)
$httpclient.setProxyURL("http://user:password@proxy_host:8080/path");
Table 4.553. Arguments for HTTPClient::setProxyURL()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| invalid URL string |
| invalid authorization credentials in proxy URL (username without password or vice-versa) |
| unknown protocol passed in URL |
Clears the current proxy URL
HTTPClient::clearProxyURL()
$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. |
Sets the SSL/TLS flag for the next proxy connection. To check the flag, use the HTTPClient::isProxySecure() method.
HTTPClient::setProxySecure(boolean
)
$httpclient.setProxySecure(True);
Table 4.558. Arguments for HTTPClient::setProxySecure()
Argument | Type | Description |
---|---|---|
| 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. |
Returns the SSL/TLS flag for proxy connection. To set the flag, use the HTTPClient::setProxySecure() method.
HTTPClient::isProxySecure()
$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. |
Returns the maximum number of redirects allowed for the object. To set this value, use the HTTPClient::setMaxRedirects() method.
HTTPClient::getMaxRedirects()
$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 |
Sets the maximum number of redirects allowed for the object. To retrieve this value, use the HTTPClient::getMaxRedirects() method.
HTTPClient::setMaxRedirects(max_redirects
)
$httpclient.setMaxRedirects(0); # disable redirections
Table 4.564. Arguments for HTTPClient::setMaxRedirects()
Argument | Type | Description |
---|---|---|
| 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. |
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().
HTTPClient::connect()
$httpclient.connect();
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 |
---|---|
| The attempt to connect exceeeded the maximum number of redirects allowed for the object. |
| There was an error receiving data on the socket |
| The receive attempt timed out. |
Disconnects from the remote socket if a connection is established (otherwise does nothing).
HTTPClient::disconnect()
$httpclient.disconnect();
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 |
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.
HTTPClient::get(path, [headers], [info_reference]
)
$html = $httpclient.get("/path/file.html");
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 |
---|---|---|
|
String |
The path for the message (i.e. '/path/resource?method¶m=value') |
| Hash | An optional hash of headers to include in the message. |
| 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 |
---|---|
|
timeout on response from HTTP server |
|
error communicating with HTTP server |
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.
HTTPClient::head(path, [headers]
)
$response = $httpclient.head("/path");
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 |
---|---|---|
|
String |
The path for the message (i.e. '/path/resource?method¶m=value') |
|
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 |
---|---|
|
timeout on response from HTTP server |
|
error communicating with HTTP server |
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.
HTTPClient::post(path, message, [headers], [info_reference]
)
Table 4.577. Arguments for HTTPClient::post()
Argument |
Type |
Description |
---|---|---|
|
String |
The path for the message (i.e. '/path/resource?method¶m=value') |
|
String or Binary |
The message body to send. |
|
Hash |
An optional hash of headers to include in the message. |
| 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 |
---|---|
|
timeout on response from HTTP server |
|
error communicating with HTTP server |
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.
HTTPClient::send(message, method, path, [headers], [get_body], [info_reference]
)
$msg = $httpclient.send($body, "POST", "/path", ("Connection":"Keep-Alive"));
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 |
---|---|---|
|
String or Binary |
The message body to send. |
|
String |
The name of the HTTP method ( |
|
String |
The path for the message (i.e. '/path/resource?method¶m=value') |
|
Hash |
An optional hash of headers to include in the message. |
|
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. |
| 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 |
---|---|
|
timeout on response from HTTP server |
|
error communicating with HTTP server |
|
invalid HTTP method passed |
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.).
HTTPClient::setConnectTimeout(timeout
)
$httpclient.setConnectTimeout(2m); # sets timeout to 2 minutes
Table 4.583. Arguments for HTTPClient::setConnectTimeout()
Argument |
Type |
Description |
---|---|---|
|
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 |
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::setTimeout(timeout
)
$httpclient.setTimeout(2m); # sets timeout to 2 minutes
Table 4.585. Arguments for HTTPClient::setTimeout()
Argument |
Type |
Description |
---|---|---|
|
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 |
Returns the connect timeout as an integer in milliseconds. Negative numbers mean the default system timeout is used instead.
HTTPClient::getConnectTimeout()
$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 |
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::getTimeout()
$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 |
Sets the HTTP protocol version string for headers in outgoing messages, allowed values are '1.0' and '1.1'.
HTTPClient::setHTTPVersion(version
)
$httpclient.setHTTPVersion("1.1");
Table 4.591. Arguments for HTTPClient::setHTTPVersion()
Argument |
Type |
Description |
---|---|---|
|
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 |
---|---|
|
invalid HTTP version passed (allowed values: '1.0', '1.1'). |
Returns the HTTP protocol version string used in outgoing messages.
HTTPClient::getHTTPVersion()
$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'). |
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::setSecure([secure]
)
$httpclient.setSecure(True);
Table 4.596. Arguments for HTTPClient::setSecure()
Argument |
Type |
Description |
---|---|---|
|
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 |
Returns True if the current connection is encrypted, False if not.
HTTPClient::isSecure()
$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. |
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::verifyPeerCertificate()
$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. |
Returns the name of the cipher for an encrypted connection.
HTTPClient::getSSLCipherName()
$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. |
Returns the version of the cipher for an encrypted connection.
HTTPClient::getSSLCipherVersion()
$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. |
Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding.
HTTPClient::setEncoding(encoding
)
$httpclient.setEncoding("ISO-8859-1");
Table 4.606. Arguments for HTTPClient::setEncoding()
Argument |
Type |
Description |
---|---|---|
|
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 |
---|---|
|
missing encoding parameter from method call |
Returns the character encoding used for the object
HTTPClient::getEncoding()
$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. |
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.
HTTPClient::setEventQueue([queue]
)
$httpclient.setEventQueue($queue);
Table 4.612. Return Values for HTTPClient::setEventQueue()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Returns the TCP_NODELAY
setting for the HTTPClient object. See also HTTPClient::setNoDelay().
HTTPClient::getNoDelay()
$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 |
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().
HTTPClient::setNoDelay(boolean
)
$httpclient.setNoDelay(True);
Table 4.615. Arguments for HTTPClient::setNoDelay()
Argument | Type | Description |
---|---|---|
| boolean | The |
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(). |
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().
HTTPClient::isConnected()
$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. |