HttpRequest Options
The CURL options in the table below are available when making an HttpRequest Get, Post, Put, or Delete request. The options should be specified as a hash, dictionary, or structure of key/value pairs. For example, to set the TIMEOUT option to 180 seconds, you would set options = {TIMEOUT: 180}.
Note: IDL uses the default values for almost all CURL options, except for AUTOREFERER=1, FOLLOWLOCATION=1, HTTPAUTH=0x7FFFFFEF, and PROXYAUTH=0x7FFFFFEF.
Note: The list below describes the most common options. IDL uses the libcurl library, which has numerous other options. Many of these options can also be used by dropping the "CURLOPT_" prefix and providing an appropriate value. For example, if you wanted to set the CURLOPT_USERPWD option, you would simply set options={userpwd:"myuser:mypasswd"}.
|
Option |
Type |
Description |
|---|---|---|
| AUTOREFERER | 0 or 1 | Set to 1 (the default) to automatically set the Referer: header field to the full previous URL when following a redirect. Set to 0 to disable this behavior. |
| BUFFERSIZE | Integer | The preferred size (in bytes) for the internal receiving buffer. Setting this will change how often your callback may be called, and might improve performance for larger sizes. The default is 16384. |
| CAINFO | String | Set to a file path to a certificate bundle. The default is ca-bundle.crt within the IDL installation bin/platform directory. |
| CONNECTTIMEOUT |
Integer |
The maximum time (in seconds) for the connection phase of a request. Setting this to 0 will switch to the default connection timeout of 300 seconds. |
|
CONNECTTIMEOUT_MS |
Integer | The same as CONNECTTIMEOUT, but in milliseconds. |
| COOKIE | String | Set to a string containing one or more cookies to send as part of the request header. The string should have the form "name1=content1;name2=content2;..." where name/content cookies are separated by semicolons. These cookies are read only. |
| COOKIEFILE | String(s) | Set to a file path (or array of file paths) containing cookies to be sent. The files can be in Netscape/Mozilla cookie data format or Set-Cookie header style. This can also be set to a null string to enable cookie retrieval using the COOKIEINFO property. |
| COOKIEJAR | String | Set to a file path. After the request is complete, all known cookies will be written to the specified file. If no cookies are present then the file will not be created. |
| COOKIELIST | String(s) | Set to a string or string array containing cookies to be sent. Each string can be in Netscape/Mozilla cookie data format or Set-Cookie header style. |
| FAILONERROR | 0 or 1 | Set to 1 to force requests to fail if the HTTP response code is ≥ 400. The default is 0, which will return the server's response for all response codes. |
| FILETIME | 0 or 1 | Set to 1 to attempt to retrieve the filetime of the response document. Use the FILETIME property on the response to retrieve the actual value. The default is 0. |
| FOLLOWLOCATION | 0 or 1 | Set to 1 (the default) to automatically follow any Location: header redirects that the server sends in a 30x response. Set to 0 to disable this behavior. |
| HEADER | 0 or 1 | Set to 1 to include the response headers in the response body. The default is 0. This option is usually not needed, as you can use the HEADERS property to retrieve the response headers. |
| HEADEROPT | 0 or 1 | Set to 1 (the default) to send different headers to the server and the proxy (if it exists). The server headers are set using the HEADER keyword, while the proxy headers are set using the PROXYHEADER option (see below). Set to 0 to send the server headers to both the server and proxy. |
|
HTTP_VERSION |
Integer |
The HTTP protocol version to use. 0=don't care, 1=HTTP/1.0, 2=HTTP/1.1, 3=HTTP/2, 4=HTTP/2 TLS with 1.1 fallback (the default), 5=HTTP/2 no 1.1 fallback, 30=HTTP/3, 31=HTTP/3 no fallback. |
| HTTPAUTH | Integer | Set to a bitmask indicating which authentication methods to use when talking to the server. See the table below for possible values. The default is 0x7FFFFFEF, which tries all methods and uses the most secure. |
| HTTPPROXYTUNNEL | 0 or 1 | Set to 1 to tunnel all operations through the HTTP proxy, set by the PROXY option. The default is 0, which converts all non-HTTP requests (such as FTP) to HTTP when using an HTTP proxy. |
| IPRESOLVE | Integer | Set what kind of IP addresses to use when making a connection. 0=either IPv4 or IPv6 (the default), 1=only IPv4, 2=only IPv6. |
| LOGIN_OPTIONS | String | A string containing the login option for the connection. The specific value depends upon the server. Examples include "AUTH=*", "AUTH=NTLM", or "AUTH=+LOGIN". |
| LOW_SPEED_LIMIT | Integer | Transfers below this limit (in bytes per second) will be considered as too slow and will be aborted. The default is 0, which disables the check. |
| LOW_SPEED_TIME | Integer | The number of seconds that the transfer speed needs to be below the LOW_SPEED_LIMIT before aborting. The default is 0, which disables the check. |
| MAXREDIRS | Integer | The maximum number of redirects allowed. The default is 30. |
| NOBODY | 0 or 1 | Set to 1 to not include the body-part in the download response, effectively doing a HEAD request. |
| NOPROXY | String | A comma separated list of host names that do not require a proxy, even if one is specified. You can also specify a single * character, which matches all hosts, and effectively disables the proxy. Set to a null (empty) string to explicitly enable the proxy for all host names. |
| PASSWORD | String | The password for the connection. Normally used with the USERNAME option. |
| PRE_PROXY | String | The pre-proxy host name or dotted numerical IP address of the format [scheme]host[:port]. This is a SOCKS proxy that is connected to before the proxy. The optional scheme can be "socks4://", "socks4a://", "socks5://", or
"
socks5h://". The default port number is 1080. Set this to a null (empty) string to disable use of a pre-proxy. |
| PROXY | String | The proxy host name or dotted numerical IP address of the format [scheme]host[:port][:username:password]. The optional scheme can be "http://", "https://", "socks4://", "socks4a://", "socks5://", or
"
socks5h://". The default port number is 1080. Set this to a null (empty) string to disable use of a proxy. |
| PROXYAUTH | Integer | The same as HTTPAUTH but for proxy authentication. |
| PROXYHEADER | String(s) | An array of custom proxy headers. Each string should have the form Name:Value. If you pass a header with no value, such as "Accept:", then the header is removed. If the header name ends in a semicolon then that header will be sent with an empty value. |
| PROXYPASSWORD | String | The password for the proxy connection. |
| PROXYPORT | Integer | The proxy port number (if not specified in the PROXY option). The default is 0, which uses 443 for HTTPS and 1080 for all others. |
| PROXYTYPE | Integer | The type of the proxy server. Valid values are 0=HTTP/1.1, 1=HTTP/1.0, 2=HTTPS/1, 3=HTTPS/2, 4=HTTPS SOCKS4, 5=SOCKS5, 6=SOCKS4A, 7=SOCKS5 HOSTNAME. |
| PROXYUSERNAME | String | The username for the proxy connection. |
| REFERER | String | Set the Referer: header field in the server request. This can also be set using the HEADERS keyword. |
| RESOLVE | String(s) | An array of custom host names that are used as a DNS cache, which is useful for Server Name Indication (SNI). Each string should have the format [+]host:port:address[, address], where a host:port pair should resolve to the given numeric IP address. The optional "+" indicates that the entry should time out like ordinary DNS cache entries. |
| SSL_VERIFYHOST | 0 or 1 |
Set to 1 (the default) to verify the certificate's name against the host. Use caution when disabling! |
| SSL_VERIFYPEER | 0 or 1 |
Set to 1 (the default) to verify the authenticity of the server's certificate. Use caution when disabling! |
| TIMEOUT | Integer | The maximum time (in seconds) for the entire transfer, including name lookups. The default is 0, which is no limit. |
| TIMEOUT_MS | Integer | The same as TIMEOUT, but in milliseconds. |
| UNRESTRICTED_AUTH | 0 or 1 | Set to 1 to make IDL continue to send authentication (username+password) credentials when following locations, even when the hostname changes. When set to 0 (the default), IDL only sends Authentication: headers to the initial URL, to avoid leaking credentials to other sites. Use with caution. |
| USERNAME | String | The username for the connection. The exact format for the username depends upon the server and could include the domain, such as DOMAIN\user or user/domain.com. |
HTTPAUTH and PROXYAUTH Bitmask Values
The default value for HTTPAUTH is 0x7FFFFFEF, which tries all authentication methods and picks the most secure one. This should rarely need to be changed, but other possible bitmask values are:
| Bitmask Value |
Http Authentication |
|---|---|
|
0 |
None |
| 1 | Basic |
| 2 = 0x2 | Digest |
| 4 = 0x4 | Negotiate (SPNEGO) |
| 8 = 0x8 | NTLM (Microsoft) |
| 16 = 0x10 | Digest with IE flavor |
| 32 = 0x20 |
NTLM delegating to winbind |
| 64 = 0x40 |
Bearer token, used in OAuth 2.0 |
| 128 = 0x80 |
Provides AWS V4 signature authentication |
| 0x80000000 | Only use unrestricted auth or a single other bitmask value |
| 0x7FFFFFEF |
The default value - try all authentication methods except IE digest |
Version History
|
9.0 |
Introduced |