Package com.chilkatsoft.chilkat2

Class Http

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Http
All Implemented Interfaces:
AutoCloseable
public class Http extends ChilkatObject
<section class="http-summary">

HTTPS client for REST API calls, GET/POST/PUT/DELETE/PATCH requests, uploads, and downloads.

Chilkat.Http is a comprehensive HTTP and HTTPS client class for applications that need to call REST APIs, download files, upload data, submit forms, send JSON or XML, stream large responses, manage cookies and redirects, authenticate with modern or legacy schemes, use TLS client certificates, work through proxies, and troubleshoot HTTP communication in detail.

REST and API requests

Send GET, POST, PUT, PATCH, DELETE, and custom HTTP requests with headers, query parameters, JSON, XML, form data, or raw request bodies.

Uploads and downloads

Download to memory, files, streams, BinData, or StringBuilder, and upload files, forms, multipart content, or application data.

Authentication

Use Basic, Digest, NTLM, Negotiate, Bearer tokens, OAuth2 access tokens, AWS signatures, and other service-specific authentication patterns.

TLS, proxies, and networking

Configure HTTPS, client certificates, TLS behavior, HTTP proxies, SOCKS proxies, proxy authentication, custom timeouts, and network interface preferences.

Cookies, redirects, and sessions

Manage cookies, follow redirects, preserve session state, control request headers, and inspect response headers and status codes.

S3-compatible storage

Use built-in helpers for Amazon S3 and S3-compatible object storage operations such as upload, download, delete, copy, and listing workflows.

Common pattern: Configure authentication, headers, TLS, proxy, and timeout settings first; send the request with the method that matches the desired input/output form; then inspect the response status, headers, body, and LastErrorText when troubleshooting server or network behavior.

For an extended overview, see Http Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Http

      public Http()
      Creates a new Http object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      When set to true, causes the currently running method to abort. Methods that always finish quickly (i.e.have no length file operations or network communications) are not affected. If no method is running, then this property is automatically reset to false when the next method is called. When the abort occurs, this property is reset to false. Both synchronous and asynchronous method calls can be aborted. (A synchronous method call could be aborted by setting this property from a separate thread.)
      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

      public void setAbortCurrent​(boolean value)
      Sets the AbortCurrent property; see getAbortCurrent().
      Parameters:
      value - the new value

    • getAccept

      public String getAccept()
      This property sets the Accept header for all HTTP requests, except those sent by the httpReq(String, HttpRequest, HttpResponse) and httpSReq(String, int, boolean, HttpRequest, HttpResponse) methods that use headers from an HttpRequest object.

      By default, it is set to */*.

      Setting this property is the same as calling setRequestHeader(String, String) with Accept as the header field name.

      The Accept HTTP header is sent by the client (your application) to tell the server which content types (MIME types) it can handle in the response.

      For example, the following means only a JSON response is accepted: 

      Accept: application/json
      Returns:
      the value of the Accept property

    • setAccept

      public void setAccept​(String value)
      Sets the Accept property; see getAccept().
      Parameters:
      value - the new value (not null)

    • getAllowGzip

      public boolean getAllowGzip()
      If true then the Accept-Encoding: gzip is automatically added for all HTTP requests, except those made using the httpReq(String, HttpRequest, HttpResponse) and httpSReq(String, int, boolean, HttpRequest, HttpResponse) methods that use headers from an HttpRequest object.

      The default value is true.

      The Accept-Encoding HTTP header is sent by the client to tell the server which compression algorithms it supports for the response body.

      Example: 

      Accept-Encoding: gzip, deflate

      This means the client can handle responses compressed with gzip or deflate.

      If this property is set to false, then the Accept-Encoding header is added, but the value is empty, like this: 

      Accept-Encoding:

      It means the client explicitly does not accept any content codings (no compression, no transformations).

      • An absent Accept-Encoding header means the client will accept any encoding (server chooses, often gzip).
      • An empty Accept-Encoding header means only the “identity” encoding (i.e., uncompressed) is acceptable.

      The setRequestHeader(String, String) method can be called with Accept-Encoding as the header field name to explicitly set the Accept-Encoding header. Note: Chilkat does not accept Brotli responses. Do not include br in the list of encodings for this header.

      The removeRequestHeader(String) can be called to explicit omit the Accept-Encoding header field from HTTP requests.

      Returns:
      the value of the AllowGzip property

    • setAllowGzip

      public void setAllowGzip​(boolean value)
      Sets the AllowGzip property; see getAllowGzip().
      Parameters:
      value - the new value

    • getAllowHeaderFolding

      public boolean getAllowHeaderFolding()
      When set to false, MIME header folding is not applied to request headers automatically. By default, this setting is true. This property exists for rare instances when a server cannot properly handle folded MIME headers.

      MIME header folding allows long header lines to be split across multiple lines for readability.

      A folded line begins with whitespace (space or tab), which signals continuation.

      Unfolded (single line): 

      Subject: This is a very long subject line that needs to be wrapped across lines

      Folded (wrapped for transport): 

      Subject: This is a very long subject line
  that needs to be wrapped across lines

      When received, the folded version is unfolded back into a single line by removing the CRLF + leading whitespace.

      Returns:
      the value of the AllowHeaderFolding property

    • setAllowHeaderFolding

      public void setAllowHeaderFolding​(boolean value)
      Sets the AllowHeaderFolding property; see getAllowHeaderFolding().
      Parameters:
      value - the new value

    • getAuthSignature

      public String getAuthSignature()
      This property can be set to a JSON string containing the required information to add an HTTP Signature in the following format: 
      Authorization: Signature
   keyId="my-key-1",
   algorithm="hmac-sha256",
   headers="(request-target) host date",
   signature="Base64OfSignature"

      See the linked example below for details.

      Returns:
      the value of the AuthSignature property

    • setAuthSignature

      public void setAuthSignature​(String value)
      Sets the AuthSignature property; see getAuthSignature().
      Parameters:
      value - the new value (not null)

    • getAuthToken

      public String getAuthToken()
      Applications can set this property to the OAuth2 access_token value to be sent in the Authorization: Bearer {access_token} header for all requests. For OAuth1.0a tokens, use the getOAuthToken() property instead.

      Starting from Chilkat v10.1.2, this method can also accept a JSON string containing details needed for automatic OAuth2 access token retrieval via the Client Credentials flow. The JSON must include the client secret, client ID, token endpoint, and scope(s). See the example below for guidance. This feature is compatible with any OAuth2 provider that supports the client credentials flow.

      Returns:
      the value of the AuthToken property

    • setAuthToken

      public void setAuthToken​(String value)
      Sets the AuthToken property; see getAuthToken().
      Parameters:
      value - the new value (not null)

    • getAutoAddHostHeader

      public boolean getAutoAddHostHeader()
      When set to true (the default), the Host header is automatically added to all requests. The domain for the Host header is taken from the URL passed in a method's arguments.

      The Host HTTP header specifies the hostname (and optional port) of the server the client is trying to reach.

      Example: 

      Host: www.example.com

      It’s required in HTTP/1.1 so a server can distinguish between multiple sites (virtual hosts) on the same IP address.

      Returns:
      the value of the AutoAddHostHeader property

    • setAutoAddHostHeader

      public void setAutoAddHostHeader​(boolean value)
      Sets the AutoAddHostHeader property; see getAutoAddHostHeader().
      Parameters:
      value - the new value

    • getAwsAccessKey

      public String getAwsAccessKey()
      The AWS Access Key to be used with the Amazon S3 methods listed below.
      Returns:
      the value of the AwsAccessKey property

    • setAwsAccessKey

      public void setAwsAccessKey​(String value)
      Sets the AwsAccessKey property; see getAwsAccessKey().
      Parameters:
      value - the new value (not null)

    • getAwsEndpoint

      public String getAwsEndpoint()
      Specify the regional endpoint (domain) for Amazon S3 method calls. The default is s3.amazonaws.com, but you can use any valid Amazon S3 endpoint, such as s3-eu-west-1.amazonaws.com, or endpoints from other S3-API compatible services.
      Returns:
      the value of the AwsEndpoint property

    • setAwsEndpoint

      public void setAwsEndpoint​(String value)
      Sets the AwsEndpoint property; see getAwsEndpoint().
      Parameters:
      value - the new value (not null)

    • getAwsRegion

      public String getAwsRegion()
      The AWS S3 region (e.g., us-east-1, us-west-2, eu-west-1, eu-central-1) defaults to us-east-1. It is relevant only when the AwsSignatureVersion property is set to 4 and ignored when set to 2.
      Returns:
      the value of the AwsRegion property

    • setAwsRegion

      public void setAwsRegion​(String value)
      Sets the AwsRegion property; see getAwsRegion().
      Parameters:
      value - the new value (not null)

    • getAwsSecretKey

      public String getAwsSecretKey()
      The AWS Secret Key to be used with the Amazon S3 methods listed below.
      Returns:
      the value of the AwsSecretKey property

    • setAwsSecretKey

      public void setAwsSecretKey​(String value)
      Sets the AwsSecretKey property; see getAwsSecretKey().
      Parameters:
      value - the new value (not null)

    • getAwsSessionToken

      public String getAwsSessionToken()
      This is the AWS session token for temporary security credentials.

      When you call AssumeRole with AWS STS, you get temporary security credentials consisting of:

      • Access key ID
      • Secret access key
      • Session token

      The session token is an extra credential that must be included with the access key and secret key when signing requests. It proves the credentials came from STS and are valid for the limited session duration.

      In short: The AWS session token is a required component of temporary STS credentials, used alongside the key pair to authenticate API calls.

      Returns:
      the value of the AwsSessionToken property

    • setAwsSessionToken

      public void setAwsSessionToken​(String value)
      Sets the AwsSessionToken property; see getAwsSessionToken().
      Parameters:
      value - the new value (not null)

    • getAwsSubResources

      public String getAwsSubResources()
      This property can be used to specify sub-resources to be included in the Amazon S3 methods listed below. For example, set the property to acl&versionId=value to request the acl for a specific version of an object.

      In Amazon S3, sub-resources are special query parameters you can append to an S3 object or bucket URL to access or manage specific properties or features beyond the main resource itself.

      Examples:

      • Bucket sub-resources: ?logging, ?website, ?lifecycle, ?policy
      • Object sub-resources: ?acl, ?torrent, ?restore, ?tagging

      So:

      • Resource = the bucket or object itself (e.g., mybucket/photo.jpg)
      • Sub-resource = a specific aspect or configuration of it, accessed with a query string (e.g., mybucket?logging or photo.jpg?acl).

      In short: S3 sub-resources let you operate on metadata/configuration of a bucket or object, not the content itself.

      Returns:
      the value of the AwsSubResources property

    • setAwsSubResources

      public void setAwsSubResources​(String value)
      Sets the AwsSubResources property; see getAwsSubResources().
      Parameters:
      value - the new value (not null)

    • getBandwidthThrottleDown

      public int getBandwidthThrottleDown()
      If set to a non-zero value, this limits the download bandwidth to the specified maximum number of bytes per second. The default value is 0.
      Returns:
      the value of the BandwidthThrottleDown property

    • setBandwidthThrottleDown

      public void setBandwidthThrottleDown​(int value)
      Sets the BandwidthThrottleDown property; see getBandwidthThrottleDown().
      Parameters:
      value - the new value

    • getBandwidthThrottleUp

      public int getBandwidthThrottleUp()
      If set to a non-zero value, this property limits the upload bandwidth to the specified maximum number of bytes per second. The default is 0.
      Returns:
      the value of the BandwidthThrottleUp property

    • setBandwidthThrottleUp

      public void setBandwidthThrottleUp​(int value)
      Sets the BandwidthThrottleUp property; see getBandwidthThrottleUp().
      Parameters:
      value - the new value

    • getBasicAuth

      public boolean getBasicAuth()
      To enable HTTP basic authentication, set this property to true. The default value is false.

      Then basic authentication is enabled, Chilkat uses the getLogin() and getPassword() properties to include the Authorization: Basic {base64} header in all requests.

      HTTP Basic Authentication is a simple authentication scheme where the client sends a username and password encoded in Base64 in the Authorization header.

      Example: 

      Authorization: Basic dXNlcjpwYXNzd29yZA==

      Here dXNlcjpwYXNzd29yZA== is the Base64 of user:password.

      Returns:
      the value of the BasicAuth property

    • setBasicAuth

      public void setBasicAuth​(boolean value)
      Sets the BasicAuth property; see getBasicAuth().
      Parameters:
      value - the new value

    • getClientIpAddress

      public String getClientIpAddress()
      A computer can have multiple network interfaces (e.g., Ethernet, Wi-Fi, VPN, virtual adapters). Each interface can have one or more IP addresses (IPv4 and/or IPv6).

      If multiple IPs exist (say, 192.168.1.10 on Wi-Fi and 10.0.0.5 on Ethernet), the application can bind explicitly to either one, determining which interface and address the socket will use for communication.

      This property can be set to explicitly bind the communications socket to an IP address.

      The default value is the empty string, which means the application does not bind to a specific local IP before connecting and the OS network stack automatically picks the default source IP.

      Returns:
      the value of the ClientIpAddress property

    • setClientIpAddress

      public void setClientIpAddress​(String value)
      Sets the ClientIpAddress property; see getClientIpAddress().
      Parameters:
      value - the new value (not null)

    • getConnectFailReason

      public int getConnectFailReason()
      This property will be set to the status of the last HTTP connection made (or failed to be made) by any HTTP method.

      Possible values are: 

      0 = success
 
 Normal (non-TLS) sockets:
 1 = empty hostname
 2 = DNS lookup failed
 3 = DNS timeout
 4 = Aborted by application.
 5 = Internal failure.
 6 = Connect Timed Out
 7 = Connect Rejected (or failed for some other reason)
 50 = HTTP proxy authentication failure.
 98 = Async operation in progress.
 99 = Product is not unlocked.
 
 SSL/TLS:
 100 = TLS internal error.
 101 = Failed to send client hello.
 102 = Unexpected handshake message.
 103 = Failed to read server hello.
 104 = No server certificate.
 105 = Unexpected TLS protocol version.
 106 = Server certificate verify failed (the server certificate is expired or the cert's signature verification failed).
 107 = Unacceptable TLS protocol version.
 108 = App-defined server certificate requirements failure.
 109 = Failed to read handshake messages.
 110 = Failed to send client certificate handshake message.
 111 = Failed to send client key exchange handshake message.
 112 = Client certificate's private key not accessible.
 113 = Failed to send client cert verify handshake message.
 114 = Failed to send change cipher spec handshake message.
 115 = Failed to send finished handshake message.
 116 = Server's Finished message is invalid.
 125 = Peer tried to connect using older SSL 2.0 protocol version.
 126 = TLS Pin Set Mismatch.
 127 = TLS 1.3 handshake error.
      Returns:
      the value of the ConnectFailReason property (read-only)

    • getConnectTimeout

      public int getConnectTimeout()
      Determines the maximum time, in seconds, to wait for an HTTP server to accept a TCP connection before timing out. The default value is 30 seconds.

      Note: A TLS connection always starts with a normal TCP connection (e.g., client connects to server on port 443). Once TCP is established, the client and server perform a TLS handshake: they exchange cryptographic messages to authenticate, agree on encryption keys, and set up a secure channel.

      The getReadTimeout() property applies to TLS handshake communications. When establishing a TLS connection, the ConnectTimeout governs the initial TCP connection, followed by the ReadTimeout.

      Returns:
      the value of the ConnectTimeout property

    • setConnectTimeout

      public void setConnectTimeout​(int value)
      Sets the ConnectTimeout property; see getConnectTimeout().
      Parameters:
      value - the new value

    • getCookieDir

      public String getCookieDir()
      Designates a directory path for automatic cookie storage (such as "c:/myCookieDir" or "/Users/example/myCookieDir") when the getSaveCookies() property is set to true. Cookies are saved in XML files, with one file per domain. Alternatively, set the value to memory to cache cookies in memory.

      The default value is the empty string, which means cookies are not saved regardless of the getSaveCookies() setting.

      Returns:
      the value of the CookieDir property

    • setCookieDir

      public void setCookieDir​(String value)
      Sets the CookieDir property; see getCookieDir().
      Parameters:
      value - the new value (not null)

    • getDefaultFreshPeriod

      public int getDefaultFreshPeriod()
      Sets the default freshness period (in minutes) for cached documents when the getFreshnessAlgorithm() property is set to 0. The default value is 10080 (1 week).

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the DefaultFreshPeriod property

    • setDefaultFreshPeriod

      public void setDefaultFreshPeriod​(int value)
      Sets the DefaultFreshPeriod property; see getDefaultFreshPeriod().
      Parameters:
      value - the new value

    • getDigestAuth

      public boolean getDigestAuth()
      Setting this property to true causes the HTTP component to use digest authentication. The default value is false.

      HTTP Digest Authentication is a challenge–response mechanism where the server sends a nonce (a unique random value) to the client. The client must hash the username, password, nonce, and request details (method, URI) into a digest using MD5 (or similar). The server performs the same calculation to verify.

      Unlike Basic Auth, the password is never sent in clear text—only the hash is transmitted—making it more secure against eavesdropping.

      Returns:
      the value of the DigestAuth property

    • setDigestAuth

      public void setDigestAuth​(boolean value)
      Sets the DigestAuth property; see getDigestAuth().
      Parameters:
      value - the new value

    • getEnableSecrets

      public boolean getEnableSecrets()
      This property that automatic resolution of credentials from the operating system’s secure storage.

      When set to true, the supported properties and methods (listed below) can accept a secret specification string (beginning with !!) in place of a literal value. Chilkat detects this format and retrieves the corresponding secret from:

      • Windows Credential Manager (Windows)
      • Apple Keychain (macOS)

      Secrets are identified using a structured string format: !![appName|]service[|domain]|username

      Applies to getAwsAccessKey() , getAwsEndpoint() , getAwsRegion() , getAwsSessionToken() , getAwsSecretKey() , getProxyPassword() , getSocksPassword() , getPassword() .

      This feature allows applications to avoid embedding sensitive data directly in code by securely resolving credentials at runtime.

      The default value is false

      Returns:
      the value of the EnableSecrets property

    • setEnableSecrets

      public void setEnableSecrets​(boolean value)
      Sets the EnableSecrets property; see getEnableSecrets().
      Parameters:
      value - the new value

    • getFetchFromCache

      public boolean getFetchFromCache()
      Set to true to enable fetching pages from cache whenever possible. The default value is false. Only HTTP GET requests are cached. HTTP responses containing Set-Cookie headers are never cached. A page is retrieved from the disk cache if it exists and is deemed fresh by the getFreshnessAlgorithm() property. If the cached page is stale, the HTTP component will send a revalidate request and update the cache based on the response.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the FetchFromCache property

    • setFetchFromCache

      public void setFetchFromCache​(boolean value)
      Sets the FetchFromCache property; see getFetchFromCache().
      Parameters:
      value - the new value

    • getFinalRedirectUrl

      public String getFinalRedirectUrl()
      If the getWasRedirected() property indicates an HTTP GET was redirected, and the getFollowRedirects() property is set to true, this property will hold the final redirect URL. This property will also contain the redirect URL for 301/302 responses, even if getFollowRedirects() is not true.
      Returns:
      the value of the FinalRedirectUrl property (read-only)

    • getFollowRedirects

      public boolean getFollowRedirects()
      When set to true, 301, 302, 303, 307, and 308 redirects are automatically followed. The default setting is true.

      To determine if a redirect occurred, check the getWasRedirected() property. The final URL after redirection is available in the getFinalRedirectUrl() property.

      Returns:
      the value of the FollowRedirects property

    • setFollowRedirects

      public void setFollowRedirects​(boolean value)
      Sets the FollowRedirects property; see getFollowRedirects().
      Parameters:
      value - the new value

    • getFreshnessAlgorithm

      public int getFreshnessAlgorithm()
      To determine the freshness of a cached HTTP GET response, the freshness algorithm is employed. By default, it uses the LM-factor algorithm, which is activated when the getFreshnessAlgorithm() is set to 1. The getLMFactor() property, ranging from 1 to 100, specifies the percentage of the time since the last modification date of the HTML page that the page remains fresh. For instance, if the LMFactor is 50 and the page was last modified 10 days ago, it will expire after 5 days (50% of 10 days). This applies only to HTTP responses without explicit expiration information. If the FreshnessAlgorithm is set to 0, a constant expiry period, defined by the getDefaultFreshPeriod() property, is applied.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the FreshnessAlgorithm property

    • setFreshnessAlgorithm

      public void setFreshnessAlgorithm​(int value)
      Sets the FreshnessAlgorithm property; see getFreshnessAlgorithm().
      Parameters:
      value - the new value

    • getHeartbeatMs

      public int getHeartbeatMs()
      The interval in milliseconds between each AbortCheck event callback, which enables an application to abort certain method calls before they complete. By default, HeartbeatMs is set to 0, meaning no AbortCheck event callbacks will trigger.
      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

      public void setHeartbeatMs​(int value)
      Sets the HeartbeatMs property; see getHeartbeatMs().
      Parameters:
      value - the new value

    • getIgnoreMustRevalidate

      public boolean getIgnoreMustRevalidate()
      If an HTTP response includes the Cache-Control: must-revalidate header, it indicates that the server requires the client to revalidate the page with the server rather than serving it directly from the cache. However, if this property is set to true, the page will be served directly from the cache without revalidation until it expires. The defautl value of this property is false.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the IgnoreMustRevalidate property

    • setIgnoreMustRevalidate

      public void setIgnoreMustRevalidate​(boolean value)
      Sets the IgnoreMustRevalidate property; see getIgnoreMustRevalidate().
      Parameters:
      value - the new value

    • getIgnoreNoCache

      public boolean getIgnoreNoCache()
      Some HTTP responses include headers indicating the page should not be cached. Chilkat HTTP will follow these instructions unless this property is set to true. The default value of this property is false.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the IgnoreNoCache property

    • setIgnoreNoCache

      public void setIgnoreNoCache​(boolean value)
      Sets the IgnoreNoCache property; see getIgnoreNoCache().
      Parameters:
      value - the new value

    • getKeepResponseBody

      public boolean getKeepResponseBody()
      If set to true, the response body, if it is text, is stored in the getLastResponseBody() property for methods not returning an HttpResponse object. By default, this property is false.

      Note: Many methods provide an HttpResponse object as their final output argument.

      Returns:
      the value of the KeepResponseBody property

    • setKeepResponseBody

      public void setKeepResponseBody​(boolean value)
      Sets the KeepResponseBody property; see getKeepResponseBody().
      Parameters:
      value - the new value

    • getLMFactor

      public int getLMFactor()
      The LMFactor is an integer between 1 and 100 that specifies the percentage of time from an HTTP page's last-modified date to be used as the freshness period. The default is 25. For instance, if a page's last-modified date is 4 weeks ago and LMFactor is set to 25, the page will remain fresh in the cache for 1 week (25% of 4 weeks).

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the LMFactor property

    • setLMFactor

      public void setLMFactor​(int value)
      Sets the LMFactor property; see getLMFactor().
      Parameters:
      value - the new value

    • getLastContentType

      public String getLastContentType()
      The Content-Type header value from the most recent HTTP response received.
      Returns:
      the value of the LastContentType property (read-only)

    • getLastFromCache

      public boolean getLastFromCache()
      true if the last GET was fetched from cache.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the LastFromCache property (read-only)

    • getLastHeader

      public String getLastHeader()
      Contains the text of the last HTTP header sent by any method.

      An HTTP request begins with a start line (called the *status line*), which contains the protocol version, status code, and reason phrase (e.g., HTTP/1.1 200 OK).

      After that comes the header section, made up of key–value pairs (like Content-Type: text/html).

      This property contains both the start line and the header section. For example: 

      POST /echo_request_body.asp HTTP/1.1
 Host: chilkatsoft.com
 Accept: */*
 Accept-Encoding: gzip
 Content-Type: application/json
 Content-Length: 26
      Returns:
      the value of the LastHeader property (read-only)

    • getLastModDate

      public String getLastModDate()
      The Last-Modified header value from the most recent HTTP response received.
      Returns:
      the value of the LastModDate property (read-only)

    • getLastResponseBody

      public String getLastResponseBody()
      The response body from the last HTTP request is saved in this property only if the getKeepResponseBody() property is set to TRUE. This applies to methods that don't return an HttpResponse object.
      Returns:
      the value of the LastResponseBody property (read-only)

    • getLastResponseHeader

      public String getLastResponseHeader()
      Returns the most recent full response header for methods that do not use an HttpResponse object. For example: 
      Content-Type: application/json
 Last-Modified: Sun, 20 Aug 2023 11:36:27 GMT
 Accept-Ranges: bytes
 ETag: "34c27f8e5ad3d91:0"
 Server: Microsoft-IIS/10.0
 X-Powered-By: ASP.NET
 Date: Sat, 30 Aug 2025 14:35:55 GMT
 Content-Length: 22
      Returns:
      the value of the LastResponseHeader property (read-only)

    • getLastStatus

      public int getLastStatus()
      Contains the most recent response status code for methods that don't utilize an HttpResponse object.
      Returns:
      the value of the LastStatus property (read-only)

    • getLastStatusText

      public String getLastStatusText()
      Contains the latest response status text for methods that don't use an HttpResponse object. The response status text appears after the status code in the first line of an HTTP response. For example, in the HTTP response below, the status text is OK: 
      HTTP/1.1 200 OK
 Content-Type: application/json
 Last-Modified: Sun, 20 Aug 2023 11:36:27 GMT
 Accept-Ranges: bytes
 ETag: "34c27f8e5ad3d91:0"
 Server: Microsoft-IIS/10.0
 X-Powered-By: ASP.NET
 Date: Sat, 30 Aug 2025 14:35:55 GMT
 Content-Length: 22
 
 { "hello": "world" }
      Returns:
      the value of the LastStatusText property (read-only)

    • getLogin

      public String getLogin()
      This is the login string to be used with HTTP basic, digest, or NTLM authentication.
      Returns:
      the value of the Login property

    • setLogin

      public void setLogin​(String value)
      Sets the Login property; see getLogin().
      Parameters:
      value - the new value (not null)

    • getLoginDomain

      public String getLoginDomain()
      The optional domain name to be used with NTLM authentication.

      In NTLM HTTP authentication, the login domain is the Windows domain that contains the user account.

      The client sends it in the NTLM messages (e.g., DOMAIN\Username) so the server knows which domain controller to contact to verify the credentials. If no domain is given, the server may fall back to checking local machine accounts.

      Returns:
      the value of the LoginDomain property

    • setLoginDomain

      public void setLoginDomain​(String value)
      Sets the LoginDomain property; see getLoginDomain().
      Parameters:
      value - the new value (not null)

    • getMaxConnections

      public int getMaxConnections()
      This class automatically manages simultaneous open HTTP connections. If the maximum number of connections is reached, the least recently active connection is automatically closed. The default value is 10.

      An HTTP connection can remain open if the client and server use persistent connections (e.g., Connection: keep-alive in HTTP/1.1).

      This allows multiple requests and responses to be sent over the same TLS connection instead of opening a new one each time.

      Reasons:

      • Reduces latency (no repeated TLS handshakes).
      • Improves efficiency for sending many requests.

      Also see: closeAllConnections()

      Returns:
      the value of the MaxConnections property

    • setMaxConnections

      public void setMaxConnections​(int value)
      Sets the MaxConnections property; see getMaxConnections().
      Parameters:
      value - the new value

    • getMaxFreshPeriod

      public int getMaxFreshPeriod()
      Sets a time limit for how long a document can remain fresh in the cache, measured in minutes, with a default value of 525,600 minutes (equivalent to 1 year).

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the MaxFreshPeriod property

    • setMaxFreshPeriod

      public void setMaxFreshPeriod​(int value)
      Sets the MaxFreshPeriod property; see getMaxFreshPeriod().
      Parameters:
      value - the new value

    • getMaxResponseSize

      public long getMaxResponseSize()
      Specify the maximum HTTP response size the program will accept. The default value of 0 means there is no size limit. This safeguard helps prevent receiving excessively large responses that could hang or crash the application.
      Returns:
      the value of the MaxResponseSize property

    • setMaxResponseSize

      public void setMaxResponseSize​(long value)
      Sets the MaxResponseSize property; see getMaxResponseSize().
      Parameters:
      value - the new value (0 .. 4294967295)

    • getMaxUrlLen

      public int getMaxUrlLen()
      Limit the length of URLs (including URL parameters) in HTTP requests by setting this property. The default value is 2000 characters.
      Returns:
      the value of the MaxUrlLen property

    • setMaxUrlLen

      public void setMaxUrlLen​(int value)
      Sets the MaxUrlLen property; see getMaxUrlLen().
      Parameters:
      value - the new value

    • getMinFreshPeriod

      public int getMinFreshPeriod()
      Sets the minimum time a document stays fresh in the cache, with a default of 30 minutes.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the MinFreshPeriod property

    • setMinFreshPeriod

      public void setMinFreshPeriod​(int value)
      Sets the MinFreshPeriod property; see getMinFreshPeriod().
      Parameters:
      value - the new value

    • getNegotiateAuth

      public boolean getNegotiateAuth()
      Set this property equal to true for Negotiate authentication.

      Note: The NegotiateAuth property is only available for the Microsoft Windows operating system.

      Returns:
      the value of the NegotiateAuth property

    • setNegotiateAuth

      public void setNegotiateAuth​(boolean value)
      Sets the NegotiateAuth property; see getNegotiateAuth().
      Parameters:
      value - the new value

    • getNtlmAuth

      public boolean getNtlmAuth()
      Setting this property to true causes the HTTP component to use NTLM authentication (also known as IWA -- or Integrated Windows Authentication) when authentication with an HTTP server. The default value is false.
      Returns:
      the value of the NtlmAuth property

    • setNtlmAuth

      public void setNtlmAuth​(boolean value)
      Sets the NtlmAuth property; see getNtlmAuth().
      Parameters:
      value - the new value

    • getNumCacheLevels

      public int getNumCacheLevels()
      This setting determines the directory levels used under each cache root. The default value is 0, meaning cached HTML pages are stored directly in the cache root directory.
      • Level 0: Cached pages are stored in the cache root directory.
      • Level 1: Cached pages go into one of 255 subdirectories (0 to 255) under the cache root.
      • Level 2: Two levels of subdirectories (0-255/0-255) are created under each cache root.

      The HTTP class automatically creates these subdirectories as needed. Multiple directory levels help prevent issues caused by having too many files in a single directory.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the NumCacheLevels property

    • setNumCacheLevels

      public void setNumCacheLevels​(int value)
      Sets the NumCacheLevels property; see getNumCacheLevels().
      Parameters:
      value - the new value

    • getNumCacheRoots

      public int getNumCacheRoots()
      Specifies the number of established cache roots used by the HTTP cache to distribute the disk cache across multiple directories. Each cache root is an absolute directory path, set using the addCacheRoot(String) method.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the NumCacheRoots property (read-only)

    • getOAuth1

      public boolean getOAuth1()
      If true then causes an OAuth Authorization header to be added to any request sent by the HTTP object. For example: 
      Authorization: OAuth realm="http://sp.example.com/",
                 oauth_consumer_key="0685bd9184jfhq22",
                 oauth_token="ad180jjd733klru7",
                 oauth_signature_method="HMAC-SHA1",
                 oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
                 oauth_timestamp="137131200",
                 oauth_nonce="4572616e48616d6d65724c61686176",
                 oauth_version="1.0"

      The information used to compute the OAuth Authorization header is obtained from the other OAuth* properties, such as OAuthConsumerKey, OAuthConsumerSecret, OAuthRealm, etc.

      Returns:
      the value of the OAuth1 property

    • setOAuth1

      public void setOAuth1​(boolean value)
      Sets the OAuth1 property; see getOAuth1().
      Parameters:
      value - the new value

    • getOAuthBodyHash

      public boolean getOAuthBodyHash()
      When set to true, the oauth_body_hash, which contains the SHA-256 hash of the HTTP request body, is automatically included in the OAuth1.0a Authorization header.

      For example: 

      Authorization: OAuth oauth_consumer_key="***", 
   oauth_nonce="A2E91C3B53E0BD7FBF71F441336679E358DDCEEE",
   oauth_body_hash="a5kPTsDwUwmBjC0voNlAAvM6YoaRS5X7sTO49jl3/h8=",
   oauth_timestamp="1756324932",
   oauth_signature_method="RSA-SHA256",
   oauth_version="1.0",
   oauth_signature="****"

      This property is only used when the getOAuth1() property equals true.

      Returns:
      the value of the OAuthBodyHash property

    • setOAuthBodyHash

      public void setOAuthBodyHash​(boolean value)
      Sets the OAuthBodyHash property; see getOAuthBodyHash().
      Parameters:
      value - the new value

    • getOAuthCallback

      public String getOAuthCallback()
      The OAuth 1.0a callback URL. Defaults to oob.

      This property is only used when the getOAuth1() property equals true.

      Returns:
      the value of the OAuthCallback property

    • setOAuthCallback

      public void setOAuthCallback​(String value)
      Sets the OAuthCallback property; see getOAuthCallback().
      Parameters:
      value - the new value (not null)

    • getOAuthConsumerKey

      public String getOAuthConsumerKey()
      The OAuth1.0a consumer key to be used in the oauth_consumer_key parameter of the Authorization header.

      This property is only used when the getOAuth1() property equals true.

      Returns:
      the value of the OAuthConsumerKey property

    • setOAuthConsumerKey

      public void setOAuthConsumerKey​(String value)
      Sets the OAuthConsumerKey property; see getOAuthConsumerKey().
      Parameters:
      value - the new value (not null)

    • getOAuthConsumerSecret

      public String getOAuthConsumerSecret()
      The consumer secret to be used in computing the contents of the OAuth1.0a Authorization header.

      This property is only used when the getOAuth1() property equals true.

      Returns:
      the value of the OAuthConsumerSecret property

    • setOAuthConsumerSecret

      public void setOAuthConsumerSecret​(String value)
      Sets the OAuthConsumerSecret property; see getOAuthConsumerSecret().
      Parameters:
      value - the new value (not null)

    • getOAuthRealm

      public String getOAuthRealm()
      The OAuth1.0a realm to be used in the Authorization header.

      The OAuth 1.0a realm parameter is an optional, descriptive string in the Authorization header that indicates the protected resources’ scope. It is not required, not included in the signature, and rarely used in real-world APIs. Most modern OAuth 1.0a integrations ignore it completely.

      This property is only used when the getOAuth1() property equals true.

      Returns:
      the value of the OAuthRealm property

    • setOAuthRealm

      public void setOAuthRealm​(String value)
      Sets the OAuthRealm property; see getOAuthRealm().
      Parameters:
      value - the new value (not null)

    • getOAuthSigMethod

      public String getOAuthSigMethod()
      Specify the oauth_signature_method parameter in the OAuth 1.0a Authorization header. The default method is HMAC-SHA1, but it can be set to HMAC-SHA256, RSA-SHA1, or RSA-SHA256. For RSA methods, provide an RSA private key using the setOAuthRsaKey(PrivateKey) method.

      This property is only used when the getOAuth1() property equals true.

      Note that RSA-SHA256 is supported from Chilkat v9.5.0.56 onwards.

      Returns:
      the value of the OAuthSigMethod property

    • setOAuthSigMethod

      public void setOAuthSigMethod​(String value)
      Sets the OAuthSigMethod property; see getOAuthSigMethod().
      Parameters:
      value - the new value (not null)

    • getOAuthToken

      public String getOAuthToken()
      The value to be used for the oauth_token parameter in the OAuth1.0a Authorization header.

      This property is only used when the getOAuth1() property equals true.

      Returns:
      the value of the OAuthToken property

    • setOAuthToken

      public void setOAuthToken​(String value)
      Sets the OAuthToken property; see getOAuthToken().
      Parameters:
      value - the new value (not null)

    • getOAuthTokenSecret

      public String getOAuthTokenSecret()
      The OAuth1.0a token secret to be used in computing the Authorization header.

      This property is only used when the getOAuth1() property equals true.

      Returns:
      the value of the OAuthTokenSecret property

    • setOAuthTokenSecret

      public void setOAuthTokenSecret​(String value)
      Sets the OAuthTokenSecret property; see getOAuthTokenSecret().
      Parameters:
      value - the new value (not null)

    • getOAuthVerifier

      public String getOAuthVerifier()
      The value to be used for the verifier to be used in the oauth_verifier parameter of the OAuth1.0a Authorization header.

      This property is only used when the getOAuth1() property equals true.

      Returns:
      the value of the OAuthVerifier property

    • setOAuthVerifier

      public void setOAuthVerifier​(String value)
      Sets the OAuthVerifier property; see getOAuthVerifier().
      Parameters:
      value - the new value (not null)

    • getPassword

      public String getPassword()
      The HTTP password for pages requiring a login/password. Chilkat HTTP can do Basic, Digest, and NTLM HTTP authentication. (NTLM is also known as SPA (or Windows Integrated Authentication). To use Basic authentication, the BasicAuth property must be set equal to true. It is not necessary to set the NtlmAuth or DigestAuth properties beforehand if NTLM or Digest authentication is needed. However, it is most efficient to pre-set these properties when the type of authentication is known in advance.

      Note: When the Login and Password properties are set, and the type of authentication is specified by setting one of the following properties equal to true (BasicAuth, DigestAuth, NtlmAuth), Chilkat will automatically add the Authorization: ... header in the correct format.

      Returns:
      the value of the Password property

    • setPassword

      public void setPassword​(String value)
      Sets the Password property; see getPassword().
      Parameters:
      value - the new value (not null)

    • getPercentDoneScale

      public int getPercentDoneScale()
      This property is only valid in programming environment and languages that allow for event callbacks.

      Sets the value to be defined as 100% complete for the purpose of PercentDone event callbacks. The defaut value of 100 means that at most 100 event PercentDone callbacks will occur in a method that (1) is event enabled and (2) is such that it is possible to measure progress as a percentage completed. This property may be set to larger numbers to get more fine-grained PercentDone callbacks. For example, setting this property equal to 1000 will provide callbacks with .1 percent granularity. For example, a value of 453 would indicate 45.3% competed. This property is clamped to a minimum value of 10, and a maximum value of 100000.

      Returns:
      the value of the PercentDoneScale property

    • setPercentDoneScale

      public void setPercentDoneScale​(int value)
      Sets the PercentDoneScale property; see getPercentDoneScale().
      Parameters:
      value - the new value

    • getPreferIpv6

      public boolean getPreferIpv6()
      If true, then use IPv6 over IPv4 when both are supported for a particular domain. The default value of this property is false, which will choose IPv4 over IPv6.
      Returns:
      the value of the PreferIpv6 property

    • setPreferIpv6

      public void setPreferIpv6​(boolean value)
      Sets the PreferIpv6 property; see getPreferIpv6().
      Parameters:
      value - the new value

    • getProxyAuthMethod

      public String getProxyAuthMethod()
      Set this to basic if you know in advance that Basic authentication is to be used for the HTTP proxy. Otherwise leave this property unset. Note: It is not necessary to set this property. The HTTP component will automatically handle proxy authentication for any of the supported authentication methods: NTLM, Digest, or Basic. Setting this property equal to basic prevents the 407 response which is automatically handled internal to Chilkat and never seen by your application.

      Note: If NTLM authentication does not succeed, set the Global.DefaultNtlmVersion property equal to 1 and then retry.

      Returns:
      the value of the ProxyAuthMethod property

    • setProxyAuthMethod

      public void setProxyAuthMethod​(String value)
      Sets the ProxyAuthMethod property; see getProxyAuthMethod().
      Parameters:
      value - the new value (not null)

    • getProxyDirectTls

      public boolean getProxyDirectTls()
      Set to true if the proxy server expects a direct TLS connection. (This is where the initial connection to the HTTP proxy server is TLS. See Squid Direct TLS Connection. The default value of this property is false.
      Returns:
      the value of the ProxyDirectTls property

    • setProxyDirectTls

      public void setProxyDirectTls​(boolean value)
      Sets the ProxyDirectTls property; see getProxyDirectTls().
      Parameters:
      value - the new value

    • getProxyDomain

      public String getProxyDomain()
      The domain name of a proxy host if an HTTP proxy is used. This can also be set to an IP address.
      Returns:
      the value of the ProxyDomain property

    • setProxyDomain

      public void setProxyDomain​(String value)
      Sets the ProxyDomain property; see getProxyDomain().
      Parameters:
      value - the new value (not null)

    • getProxyLogin

      public String getProxyLogin()
      If an HTTP proxy is used and it requires authentication, this property specifies the HTTP proxy login.
      Returns:
      the value of the ProxyLogin property

    • setProxyLogin

      public void setProxyLogin​(String value)
      Sets the ProxyLogin property; see getProxyLogin().
      Parameters:
      value - the new value (not null)

    • getProxyLoginDomain

      public String getProxyLoginDomain()
      The NTLM authentication domain (optional) if NTLM authentication is used.
      Returns:
      the value of the ProxyLoginDomain property

    • setProxyLoginDomain

      public void setProxyLoginDomain​(String value)
      Sets the ProxyLoginDomain property; see getProxyLoginDomain().
      Parameters:
      value - the new value (not null)

    • getProxyPassword

      public String getProxyPassword()
      If an HTTP proxy is used and it requires authentication, this property specifies the HTTP proxy password.
      Returns:
      the value of the ProxyPassword property

    • setProxyPassword

      public void setProxyPassword​(String value)
      Sets the ProxyPassword property; see getProxyPassword().
      Parameters:
      value - the new value (not null)

    • getProxyPort

      public int getProxyPort()
      The port number of a proxy server if an HTTP proxy is used.
      Returns:
      the value of the ProxyPort property

    • setProxyPort

      public void setProxyPort​(int value)
      Sets the ProxyPort property; see getProxyPort().
      Parameters:
      value - the new value

    • getReadTimeout

      public int getReadTimeout()
      The amount of time in seconds to wait before timing out when reading from an HTTP server. The ReadTimeout is the amount of time that needs to elapse while no additional data is forthcoming. During a long download, if the data stream halts for more than this amount, it will timeout. Otherwise, there is no limit on the length of time for the entire download.

      The default value is 60 seconds. Note: Prior to v9.5.0.76, the default was 20 seconds.

      Returns:
      the value of the ReadTimeout property

    • setReadTimeout

      public void setReadTimeout​(int value)
      Sets the ReadTimeout property; see getReadTimeout().
      Parameters:
      value - the new value

    • getReceivedCertReq

      public boolean getReceivedCertReq()
      Indicates whether the last HTTPS connection received a TLS CertificateRequest handshake message indicating that the server may require a client certificate.
      Returns:
      the value of the ReceivedCertReq property (read-only)

    • getRedirectVerb

      public String getRedirectVerb()
      Indicates the HTTP verb, such as GET, POST, PUT, etc. to be used for a redirect when the FollowRedirects property is set to true. The default value of this property is GET. This will produce the same behavior as a web browser (such as FireFox). If this property is set to the empty string, then it will cause the same verb as the original HTTP request to be used.

      Note: Prior to version 9.5.0.44, the default value of this property was the empty string.

      Returns:
      the value of the RedirectVerb property

    • setRedirectVerb

      public void setRedirectVerb​(String value)
      Sets the RedirectVerb property; see getRedirectVerb().
      Parameters:
      value - the new value (not null)

    • getRequireHostnameMatch

      public boolean getRequireHostnameMatch()
      If true, then the hostname/domain in the URL must match at least one of the entries in the server certificate's SAN. A SAN (Subject Alternative Name) field in an SSL/TLS certificate contains a list of additional domain names, subdomains, IP addresses, or other identifiers that the certificate is valid for.

      In actuality, it is the SNI hostname in the TLS handshake that must match a SAN entry. By default, Chilkat uses the hostname from the URL as the SNI hostname. An application can explicitly set the SNI hostname via the SniHostname property, which would be typical if connecting via an IP address. See the example below.

      Starting in v11.7.0, a wildcard SAN entry is matched as RFC 9525 (formerly RFC 6125) specifies. The wildcard must be the entire left-most label (*.example.com) and stands for exactly one label: *.example.com matches www.example.com, but not a.b.example.com and not the bare example.com. (Earlier versions matched the bare domain, and accepted a wildcard in any position.) A wildcard is not accepted directly under a top-level domain or a country-code second level such as co.uk, and never matches an IP address.

      The default value is false.

      Returns:
      the value of the RequireHostnameMatch property

    • setRequireHostnameMatch

      public void setRequireHostnameMatch​(boolean value)
      Sets the RequireHostnameMatch property; see getRequireHostnameMatch().
      Parameters:
      value - the new value

    • getRequireSslCertVerify

      public boolean getRequireSslCertVerify()
      If true, then the HTTP client will verify the server's SSL certificate. The certificate is expired, or if the cert's signature is invalid, the connection is not allowed. The default value of this property is false.
      Returns:
      the value of the RequireSslCertVerify property

    • setRequireSslCertVerify

      public void setRequireSslCertVerify​(boolean value)
      Sets the RequireSslCertVerify property; see getRequireSslCertVerify().
      Parameters:
      value - the new value

    • getRequiredContentType

      public String getRequiredContentType()
      If set, then any HTTP response to any POST or GET, including downloads, will be rejected if the content-type in the response header does not match this setting. If the content-type does not match, only the header of the HTTP response is read, the connection to the HTTP server is closed, and the remainder of the response is never read.

      This property is empty (zero-length string) by default.

      Some typical content-types are text/html, text/xml, image/gif, image/jpeg, application/zip, application/msword, application/pdf, etc.

      Returns:
      the value of the RequiredContentType property

    • setRequiredContentType

      public void setRequiredContentType​(String value)
      Sets the RequiredContentType property; see getRequiredContentType().
      Parameters:
      value - the new value (not null)

    • getSaveCookies

      public boolean getSaveCookies()
      If this property is true, cookies are automatically persisted to XML files in the directory specified by the CookiesDir property (or in memory if CookieDir = memory). Both CookiesDir and SaveCookies must be set for cookies to be persisted.
      Returns:
      the value of the SaveCookies property

    • setSaveCookies

      public void setSaveCookies​(boolean value)
      Sets the SaveCookies property; see getSaveCookies().
      Parameters:
      value - the new value

    • getSendBufferSize

      public int getSendBufferSize()
      The buffer size to be used with the underlying TCP/IP socket for sending. The default value is 65535.
      Returns:
      the value of the SendBufferSize property

    • setSendBufferSize

      public void setSendBufferSize​(int value)
      Sets the SendBufferSize property; see getSendBufferSize().
      Parameters:
      value - the new value

    • getSendCookies

      public boolean getSendCookies()
      If true, then cookies previously persisted to the CookiesDir are automatically added to all HTTP requests. Only cookies matching the domain and path are added.
      Returns:
      the value of the SendCookies property

    • setSendCookies

      public void setSendCookies​(boolean value)
      Sets the SendCookies property; see getSendCookies().
      Parameters:
      value - the new value

    • getSessionLogFilename

      public String getSessionLogFilename()
      Enables file-based session logging. If set to a filename (or relative/absolute filepath), then the exact HTTP requests and responses are logged to a file. The file is created if it does not already exist, otherwise it is appended.
      Returns:
      the value of the SessionLogFilename property

    • setSessionLogFilename

      public void setSessionLogFilename​(String value)
      Sets the SessionLogFilename property; see getSessionLogFilename().
      Parameters:
      value - the new value (not null)

    • getSniHostname

      public String getSniHostname()
      Sets the SNI hostname for the TLS ClientHello. This property is usually necessary only when the domain is specified by an IP address and an SNI hostname is required. By default Chilkat uses the hostname in the URL for the SNI hostname in the TLS ClientHello extension automatically.
      Returns:
      the value of the SniHostname property

    • setSniHostname

      public void setSniHostname​(String value)
      Sets the SniHostname property; see getSniHostname().
      Parameters:
      value - the new value (not null)

    • getSoRcvBuf

      public int getSoRcvBuf()
      Sets the receive buffer size socket option. Normally, this property should be left unchanged. The default value is 4194304.

      This property can be increased if download performance seems slow. It is recommended to be a multiple of 4096.

      Returns:
      the value of the SoRcvBuf property

    • setSoRcvBuf

      public void setSoRcvBuf​(int value)
      Sets the SoRcvBuf property; see getSoRcvBuf().
      Parameters:
      value - the new value

    • getSoSndBuf

      public int getSoSndBuf()
      Sets the send buffer size socket option. Normally, this property should be left unchanged. The default value is 262144.

      This property can be increased if upload performance seems slow. It is recommended to be a multiple of 4096. Testing with sizes such as 512K and 1MB is reasonable.

      Returns:
      the value of the SoSndBuf property

    • setSoSndBuf

      public void setSoSndBuf​(int value)
      Sets the SoSndBuf property; see getSoSndBuf().
      Parameters:
      value - the new value

    • getSocksHostname

      public String getSocksHostname()
      The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).
      Returns:
      the value of the SocksHostname property

    • setSocksHostname

      public void setSocksHostname​(String value)
      Sets the SocksHostname property; see getSocksHostname().
      Parameters:
      value - the new value (not null)

    • getSocksPassword

      public String getSocksPassword()
      The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.
      Returns:
      the value of the SocksPassword property

    • setSocksPassword

      public void setSocksPassword​(String value)
      Sets the SocksPassword property; see getSocksPassword().
      Parameters:
      value - the new value (not null)

    • getSocksPort

      public int getSocksPort()
      The SOCKS4/SOCKS5 proxy port. The default value is 1080. This property only applies if a SOCKS proxy is used (if the SocksVersion property is set to 4 or 5).
      Returns:
      the value of the SocksPort property

    • setSocksPort

      public void setSocksPort​(int value)
      Sets the SocksPort property; see getSocksPort().
      Parameters:
      value - the new value

    • getSocksUsername

      public String getSocksUsername()
      The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).
      Returns:
      the value of the SocksUsername property

    • setSocksUsername

      public void setSocksUsername​(String value)
      Sets the SocksUsername property; see getSocksUsername().
      Parameters:
      value - the new value (not null)

    • getSocksVersion

      public int getSocksVersion()
      SocksVersion May be set to one of the following integer values:

      0 - No SOCKS proxy is used. This is the default.
      4 - Connect via a SOCKS4 proxy.
      5 - Connect via a SOCKS5 proxy.

      Returns:
      the value of the SocksVersion property

    • setSocksVersion

      public void setSocksVersion​(int value)
      Sets the SocksVersion property; see getSocksVersion().
      Parameters:
      value - the new value

    • getSslAllowedCiphers

      public String getSslAllowedCiphers()
      Provides a means for setting a list of ciphers that are allowed for SSL/TLS connections. The default (empty string) indicates that all implemented ciphers are possible. The TLS ciphers supported in Chilkat v9.5.0.55 and later are: 
      TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
 TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256
 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
 TLS_DHE_RSA_WITH_AES_256_CBC_SHA
 TLS_RSA_WITH_AES_256_CBC_SHA256
 TLS_RSA_WITH_AES_256_GCM_SHA384
 TLS_RSA_WITH_AES_256_CBC_SHA
 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
 TLS_DHE_RSA_WITH_AES_128_CBC_SHA
 TLS_RSA_WITH_AES_128_CBC_SHA256
 TLS_RSA_WITH_AES_128_GCM_SHA256
 TLS_RSA_WITH_AES_128_CBC_SHA
 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
 TLS_RSA_WITH_3DES_EDE_CBC_SHA
 TLS_ECDHE_RSA_WITH_RC4_128_SHA
 TLS_RSA_WITH_RC4_128_SHA
 TLS_RSA_WITH_RC4_128_MD5
 TLS_DHE_RSA_WITH_DES_CBC_SHA
 TLS_RSA_WITH_DES_CBC_SHA

      To restrict SSL/TLS connections to one or more specific ciphers, set this property to a comma-separated list of ciphers such as TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384. The order should be in terms of preference, with the preferred algorithms listed first. (Note that the client cannot specifically choose the algorithm is picked because it is the server that chooses. The client simply provides the server with a list from which to choose.)

      The property can also disallow connections with servers having certificates with RSA keys less than a certain size. By default, server certificates having RSA keys of 512 bits or greater are allowed. Add the keyword rsa1024 to disallow connections with servers having keys smaller than 1024 bits. Add the keyword rsa2048 to disallow connections with servers having keys smaller than 2048 bits.

      Note: Prior to Chilkat v9.5.0.55, it was not possible to explicitly list allowed cipher suites. The deprecated means for indicating allowed ciphers was both incomplete and unprecise. For example, the following keywords could be listed to allow matching ciphers: aes256-cbc, aes128-cbc, 3des-cbc, and rc4. These keywords will still be recognized, but programs should be updated to explicitly list the allowed ciphers.

      secure-renegotiation: Starting in Chilkat v9.5.0.55, the keyword secure-renegotiation may be added to require that all renegotions be done securely (as per RFC 5746).

      best-practices: Starting in Chilkat v9.5.0.55, this property may be set to the single keyword best-practices. This will allow ciphers based on the current best practices. As new versions of Chilkat are released, the best practices may change. Changes will be noted here. The current best practices are:

      • If the server uses an RSA key, it must be 1024 bits or greater.
      • All renegotations must be secure renegotiations.
      • All ciphers using RC4, DES, or 3DES are disallowed.

      Example: The following string would restrict to 2 specific cipher suites, require RSA keys to be 1024 bits or greater, and require secure renegotiations: TLS_DHE_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA, rsa1024, secure-renegotiation

      Returns:
      the value of the SslAllowedCiphers property

    • setSslAllowedCiphers

      public void setSslAllowedCiphers​(String value)
      Sets the SslAllowedCiphers property; see getSslAllowedCiphers().
      Parameters:
      value - the new value (not null)

    • getSslProtocol

      public String getSslProtocol()
      Selects the SSL/TLS protocol version to be used for connections. Possible values are:
      default
      TLS 1.3
      TLS 1.2
      TLS 1.1
      TLS 1.0
      SSL 3.0
      TLS 1.3 or higher
      TLS 1.2 or higher
      TLS 1.1 or higher
      TLS 1.0 or higher
      The default value is default which allows for the protocol to be selected dynamically at runtime based on the requirements of the server. Choosing an exact protocol will cause the connection to fail unless that exact protocol is negotiated. It is better to choose X or higher than an exact protocol. The default is effectively SSL 3.0 or higher.
      Returns:
      the value of the SslProtocol property

    • setSslProtocol

      public void setSslProtocol​(String value)
      Sets the SslProtocol property; see getSslProtocol().
      Parameters:
      value - the new value (not null)

    • getStreamResponseBodyPath

      public String getStreamResponseBodyPath()
      Allows for the HTTP response body to be streamed directly into a file. If this property is set, then any method returning an HTTP response object will stream the response body directly to the file path specified. The HTTP response object will still contain the response header. (This property is useful when the HTTP response is too large to fit into memory.)
      Returns:
      the value of the StreamResponseBodyPath property

    • setStreamResponseBodyPath

      public void setStreamResponseBodyPath​(String value)
      Sets the StreamResponseBodyPath property; see getStreamResponseBodyPath().
      Parameters:
      value - the new value (not null)

    • getTlsCipherSuite

      public String getTlsCipherSuite()
      Contains the current or last negotiated TLS cipher suite. If no TLS connection has yet to be established, or if a connection as attempted and failed, then this will be empty. A sample cipher suite string looks like this: TLS_DHE_RSA_WITH_AES_256_CBC_SHA256.
      Returns:
      the value of the TlsCipherSuite property (read-only)

    • getTlsPinSet

      public String getTlsPinSet()
      Specifies a set of pins for Public Key Pinning for TLS connections. This property lists the expected SPKI fingerprints for the server certificates. If the server's certificate (sent during the TLS handshake) does not match any of the SPKI fingerprints, then the TLS handshake is aborted and the connection fails. The format of this string property is as follows: 
      hash_algorithm, encoding, SPKI_fingerprint_1, SPKI_fingerprint_2, ...

      For example, the following string specifies a single sha256 base64-encoded SPKI fingerprint: 

      "sha256, base64, lKg1SIqyhPSK19tlPbjl8s02yChsVTDklQpkMCHvsTE="

      This example specifies two SPKI fingerprints: 

      "sha256, base64, 4t37LpnGmrMEAG8HEz9yIrnvJV2euVRwCLb9EH5WZyI=, 68b0G5iqMvWVWvUCjMuhLEyekM5729PadtnU5tdXZKs="

      Any of the following hash algorithms are allowed:.sha1, sha256, sha384, sha512, md2, md5, haval, ripemd128, ripemd160,ripemd256, or ripemd320.

      The following encodings are allowed: base64, hex, and any of the encodings indicated in the link below.

      Returns:
      the value of the TlsPinSet property

    • setTlsPinSet

      public void setTlsPinSet​(String value)
      Sets the TlsPinSet property; see getTlsPinSet().
      Parameters:
      value - the new value (not null)

    • getTlsVersion

      public String getTlsVersion()
      Contains the current or last negotiated TLS protocol version. If no TLS connection has yet to be established, or if a connection as attempted and failed, then this will be empty. Possible values are SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3.
      Returns:
      the value of the TlsVersion property (read-only)

    • getUncommonOptions

      public String getUncommonOptions()
      This is a catch-all property to be used for uncommon needs. This property defaults to the empty string and should typically remain empty. Can be set to a list of the following comma separated keywords:
      • QuickDisconnect - Introduced in v9.5.0.77. In the call to CloseAllConnections, do not disconnect cleanly. Instead just disconnect as quickly as possible.
      • ProtectFromVpn - Introduced in v9.5.0.80. On Android systems, will bypass any VPN that may be installed or active.
      • TlsNoClientRootCert - Introduced in v9.5.0.82. Will exclude root CA certs from being included in the client certificate chain that is sent to the server for client-side authentication. This must be set prior to calling SetSslClientCert.
      • AllowEmptyHeaders - Introduced in v9.5.0.82. If present, an empty value string passed to SetHeaderField will cause the header to be added with an empty value. Otherwise, for historical purposes and backward compatibility, the header field is removed when an empty value string is passed.
      • AnsiLogin - Introduced in v9.5.0.87. For HTTP basic authentication, the login and password is sent using the utf-8 byte representation. Some servers expect the ANSI byte representation (typically Windows-1252). Use this keyword to send the login/password using ANSI.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • getUpdateCache

      public boolean getUpdateCache()
      Set this property to true to automatically updated with HTTP GET request responses. Only HTTP GET requests are cached. HTTP responses containing Set-Cookie headers are never cached. The default value is false.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Returns:
      the value of the UpdateCache property

    • setUpdateCache

      public void setUpdateCache​(boolean value)
      Sets the UpdateCache property; see getUpdateCache().
      Parameters:
      value - the new value

    • getUseIEProxy

      public boolean getUseIEProxy()
      If true, the proxy address/port used by Internet Explorer will also be used by Chilkat HTTP. Note: This property only pays attention to the proxy address and port, and does not pay attention to additional information such as IE proxy server exceptions.
      Returns:
      the value of the UseIEProxy property

    • setUseIEProxy

      public void setUseIEProxy​(boolean value)
      Sets the UseIEProxy property; see getUseIEProxy().
      Parameters:
      value - the new value

    • getUserAgent

      public String getUserAgent()
      This property sets the User-Agent header for all HTTP requests, except those sent by the httpReq(String, HttpRequest, HttpResponse) and httpSReq(String, int, boolean, HttpRequest, HttpResponse) methods that use headers from an HttpRequest object.

      By default, it is set to an empty string, meaning no User-Agent header is included.

      Setting this property is the same as calling setRequestHeader(String, String) with User-Agent as the header field name.

      The User-Agent HTTP header is sent by the client to identify the software making the request (browser, app, library, bot, etc.).

      Example: 

      MyApp/1.1

      Note: Some web servers reject requests that do not include a User-Agent.

      Returns:
      the value of the UserAgent property

    • setUserAgent

      public void setUserAgent​(String value)
      Sets the UserAgent property; see getUserAgent().
      Parameters:
      value - the new value (not null)

    • getWasRedirected

      public boolean getWasRedirected()
      This shows whether the last HTTP request automatically followed a redirect. For more information on redirection, see the getFollowRedirects() and getFinalRedirectUrl() properties.
      Returns:
      the value of the WasRedirected property (read-only)

    • addCacheRoot

      public void addCacheRoot​(String dir)
      Disk caching operates similarly to browser caching of web pages, but it focuses on downloading web pages rather than handling HTTP requests to a REST API.

      To activate disk caching, invoke the method at least once. Use the AddCacheRoot method and provide a file path (e.g., D:\MyHttpCache\) to set the root directory. To distribute the cache over multiple directories, call AddCacheRoot multiple times with different directory paths.

      HTTP GET web page caching properties and methods include: getNumCacheRoots(), getNumCacheLevels(), addCacheRoot(String), getFetchFromCache(), getUpdateCache(), getMinFreshPeriod(), getMaxFreshPeriod(), getFreshnessAlgorithm(), getDefaultFreshPeriod(), getLMFactor(), getIgnoreMustRevalidate(), getIgnoreNoCache(), and getLastFromCache().

      Parameters:
      dir - the dir argument (not null)

    • clearHeaders

      public void clearHeaders()
      Removes all headers set by the setRequestHeader(String, String) method.

    • clearInMemoryCookies

      public void clearInMemoryCookies()
      Clears all in-memory cookies accumulated while the getSaveCookies() property was set to true and the getCookieDir() was set to memory.

    • clearUrlVars

      public void clearUrlVars()
      Removes all URL variable values previously set by setUrlVar(String, String) .

    • closeAllConnections

      public void closeAllConnections()
      Closes all remaining open HTTP connections.

      An HTTP object can hold up to 10 connections. If a server response lacks a Connection: Close header, the connection stays open and may be reused for subsequent requests to the same host. Connections are identified by their IP address or domain name as specified in the URL. Once the limit of 10 connections is reached, the least recently used connection will be closed to open a new one.

      Also see: getMaxConnections() .

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • createOcspRequest

      public void createOcspRequest​(JsonObject requestDetails, BinData ocspRequest)
      Generates an OCSP request for one or more certificates using JSON (requestDetails) that specifies the request details. Refer to the examples in the provided links for guidance on constructing the JSON.

      Note: After creating the OCSP request, send it to the server using httpBd(String, String, BinData, String, HttpResponse) with a POST request and a Content-Type of application/ocsp-request. Use parseOcspReply(BinData, JsonObject) to analyze the OCSP response.

      Parameters:
      requestDetails - the requestDetails argument (not null)
      ocspRequest - the ocspRequest argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • createTimestampRequest

      public void createTimestampRequest​(String hashAlg, String hashVal, String reqPolicyOid, boolean addNonce, boolean reqTsaCert, BinData timestampToken)
      Creates an RFC 3161 time-stamp request and returns the binary request token in timestampToken. The hashAlg can be sha1, sha256, sha384, sha512, or md5, The hashVal is the base64 hash of the data to be timestamped. The optional reqPolicyOid is the requested policy OID in a format such as 1.3.6.1.4.1.47272.1.2. The addNonce indicates whether to auto-generate and include a nonce in the request. It may be true or false. The reqTsaCert determines whether or not to request the TSA's certificate (true = Yes, false = No).

      Note: After creating the timestamp request, send it to the server using httpBd(String, String, BinData, String, HttpResponse) with a POST request and a Content-Type of application/timestamp-query. Use verifyTimestampReply(BinData, Cert) to analyze and verify the timestamp reply. See the examples linked below.

      Parameters:
      hashAlg - the hashAlg argument (not null)
      hashVal - the hashVal argument (not null)
      reqPolicyOid - the reqPolicyOid argument (not null)
      addNonce - the addNonce argument
      reqTsaCert - the reqTsaCert argument
      timestampToken - the timestampToken argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • dnsCacheClear

      public void dnsCacheClear()
      This function clears the Chilkat in-memory DNS cache, which stores hostname-to-IP address mappings to avoid repeated DNS lookups.

      Note:

      • The DNS cache is shared across all Chilkat objects, so clearing it will impact all such objects.
      • Chilkat's DNS caching respects the TTL (time to live) of DNS records. If the TTL has expired since the initial lookup, Chilkat will perform a new DNS query and update the cache with the latest IP address.

    • download

      public void download​(String url, String localFilePath)
      Downloads the content at the specified url and saves to a local file at localFilePath.

      The download succeeds if the HTTP response status code is in the 200s. If unsuccessful, no output file is created. If the getKeepResponseBody() property is set to true, the server's error response will be available in the getLastResponseBody() property.

      The response status code will be available in the getLastStatus() property.

      Parameters:
      url - the url argument (not null)
      localFilePath - the localFilePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadAppend

      public void downloadAppend​(String url, String appendToPath)
      Downloads the content at the specified url and appends to the local file at appendToPath. The file is created if it does not yet exist.

      The download succeeds if the HTTP status code is in the 200s. If unsuccessful, no output file is created. If the getKeepResponseBody() property is set to true, the server's error response will be available in the getLastResponseBody() property.

      The response status code will be available in the getLastStatus() property.

      Parameters:
      url - the url argument (not null)
      appendToPath - the appendToPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadBd

      public void downloadBd​(String url, BinData binData)
      Downloads content from url to binData, clearing binData beforehand. binData will only contain the downloaded bytes if the operation is successful.

      The download succeeds if the HTTP status code is in the 200s. If unsuccessful, nothing is written to binData. If the getKeepResponseBody() property is set to true, the server's error response will be available in the getLastResponseBody() property.

      The response status code will be available in the getLastStatus() property.

      Parameters:
      url - the url argument (not null)
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadHash

      public String downloadHash​(String url, String hashAlgorithm, String encoding)
      Fetches the content at url and returns the encoded hash using the specified algorithm (hashAlgorithm: sha1, sha256, sha384, sha512, md2, md5, haval, ripemd128, ripemd160, ripemd256, or ripemd320), and returns the hash encoded in the specified encoding (encoding: Base64, modBase64, Base32, UU, QP for quoted-printable, URL for URL-encoding, Hex, Q, B, url_oath, url_rfc1738, url_rfc2396, or url_rfc3986).
      Parameters:
      url - the url argument (not null)
      hashAlgorithm - the hashAlgorithm argument (not null)
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • downloadSb

      public void downloadSb​(String url, String charset, StringBuilder sb)
      Downloads the content at the url into a Chilkat StringBuilder object. The charset tells Chilkat how to interpret the bytes received. The sb is appended with the downloaded text data.
      Parameters:
      url - the url argument (not null)
      charset - the charset argument (not null)
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • extractMetaRefreshUrl

      public String extractMetaRefreshUrl​(String htmlContent)
      This is a convenience method for extracting the META refresh URL from HTML. For example, if the htmlContent contains a META refresh tag, such as: 
      _LT_meta http-equiv="refresh" content="5;URL='https://example.com/'"_GT_

      Then the return value of this method would be https://example.com/.

      Parameters:
      htmlContent - the htmlContent argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • gSvcOauthAccessToken

      public String gSvcOauthAccessToken​(String iss, String scope, String subEmail, int numSec, Cert cert)
      Obtains a Google API OAuth2 access token for a service account. The iss is your service account email address ending in gserviceaccount.com. The scope should be set to https://mail.google.com/ for GMail. The subEmail is your company email address, e.g. bob@yourcompany.com. numSec is the number of seconds the access token will remain valid.
      Parameters:
      iss - the iss argument (not null)
      scope - the scope argument (not null)
      subEmail - the subEmail argument (not null)
      numSec - the numSec argument
      cert - the cert argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • gSvcOauthAccessToken2

      public String gSvcOauthAccessToken2​(Hashtable claimParams, int numSec, Cert cert)
      This method is similar to G_SvcOauthAccessToken, but offers greater customization. The first three arguments of G_SvcOauthAccessToken are replaced with claimParams to allow for future expansion with name-value parameters. See the example below.
      Parameters:
      claimParams - the claimParams argument (not null)
      numSec - the numSec argument
      cert - the cert argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • genTimeStamp

      public String genTimeStamp()
      Returns the current date and time in GMT (UTC) as a string formatted according to RFC 2616: Day, DD Mon YYYY HH:MM:SS GMT. For example, Thu, 21 Aug 2025 11:17:31 GMT.
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getCacheRoot

      public String getCacheRoot​(int index)
      Returns the Nth cache root, with indexing starting at 0. Cache roots are established by calling addCacheRoot(String) one or more times. The number of established cache roots is in the getNumCacheRoots() property.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getCookieXml

      public String getCookieXml​(String domain)
      Returns cookies in XML format for a specified domain. Cookies are saved only if the getSaveCookies() property is set to true. If the getCookieDir() property is set to memory, cookies are stored in-memory.
      Parameters:
      domain - the domain argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getDomain

      public String getDomain​(String url)
      Utility method to extract the domain name from a URL. For instance, passing in https://chilkatsoft.com/refdoc/csharp.asp will return chilkatsoft.com.
      Parameters:
      url - the url argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getLastJsonData

      public void getLastJsonData​(JsonObject json)
      Offers details about the most recent method called on this object instance, although some methods may not supply any information.
      Parameters:
      json - the json argument (not null)

    • getRequestHeader

      public String getRequestHeader​(String name)
      Returns the value of a header field previously set by calling setRequestHeader(String, String).
      Parameters:
      name - the name argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getServerCert

      public void getServerCert​(String domain, int port, Cert cert)
      Establishes an SSL/TLS connection with a web server to acquire its SSL certificate without retrieving any data, then disconnects.
      Parameters:
      domain - the domain argument (not null)
      port - the port argument
      cert - the cert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getUrlPath

      public String getUrlPath​(String url)
      Returns the path part of a URL. For example, the path part of https://example.com/folder/page?lang=en&sort=asc#section2 is /folder/page.
      Parameters:
      url - the url argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • hasRequestHeader

      public boolean hasRequestHeader​(String name)
      Returns true if the header field specified by name is included in all HTTP requests, except those sent by the httpReq(String, HttpRequest, HttpResponse) or httpSReq(String, int, boolean, HttpRequest, HttpResponse) methods.
      Parameters:
      name - the name argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • httpBd

      public void httpBd​(String verb, String url, BinData bd, String contentType, HttpResponse response)
      Sends an HTTP request to url using the specified HTTP verb (e.g., POST, PUT, PATCH). The body of the request is defined by bd, and the Content-Type header is set by contentType, with possible values like application/octet-stream, application/pdf, image/jpeg, or application/zip. The HTTP response is returned in response.

      This method returns false for HTTP response status codes of 400 or higher, but the response object is still provided in response. If response's status code is 0, it indicates no response was received due to a communication error or another issue. In such cases, check the LastErrorText property for details.

      Parameters:
      verb - the verb argument (not null)
      url - the url argument (not null)
      bd - the bd argument (not null)
      contentType - the contentType argument (not null)
      response - the response argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • httpFile

      public void httpFile​(String verb, String url, String localFilePath, String contentType, HttpResponse response)
      Sends an HTTP request to url using the specified HTTP verb (e.g., POST, PUT, PATCH). The body of the request is streamed directly from localFilePath, and the Content-Type header is set by contentType, with possible values like application/octet-stream, application/pdf, image/jpeg, or application/zip. The HTTP response is returned in response.

      This method returns false for HTTP response status codes of 400 or higher, but the response object is still provided in response. If response's status code is 0, it indicates no response was received due to a communication error or another issue. In such cases, check the LastErrorText property for details.

      Parameters:
      verb - the verb argument (not null)
      url - the url argument (not null)
      localFilePath - the localFilePath argument (not null)
      contentType - the contentType argument (not null)
      response - the response argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • httpJson

      public void httpJson​(String verb, String url, JsonObject json, String contentType, HttpResponse response)
      Sends an HTTP request to url using the specified method in verb (e.g., POST, PUT, PATCH). The request body contains the JSON from json, with the content type set by contentType, such as application/json or application/jsonrequest. The HTTP response is returned in response.

      This method returns false for HTTP response status codes of 400 or higher, but the response object is still provided in response. If response's status code is 0, it indicates no response was received due to a communication error or another issue. In such cases, check the LastErrorText property for details.

      Parameters:
      verb - the verb argument (not null)
      url - the url argument (not null)
      json - the json argument (not null)
      contentType - the contentType argument (not null)
      response - the response argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • httpNoBody

      public void httpNoBody​(String verb, String url, HttpResponse response)
      Sends an HTTP request to url using the specified HTTP verb. The request body is empty. Verbs like GET, HEAD, and DELETE usually do not include a body. No Content-Type header is included because there is no content in the body of the request. The HTTP response is returned in response.

      This method returns false for HTTP response status codes of 400 or higher, but the response object is still provided in response. If response's status code is 0, it indicates no response was received due to a communication error or another issue. In such cases, check the LastErrorText property for details.

      Parameters:
      verb - the verb argument (not null)
      url - the url argument (not null)
      response - the response argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • httpParams

      public void httpParams​(String verb, String url, JsonObject json, HttpResponse response)
      Sends an HTTP verb request to url with query parameters from json. The request has an empty body, and therefore, no Content-Type header is included. Typically, verbs such as GET, HEAD, and DELETE do not require a body. Applications generally call this method with url, while passing query parameters separately in json. See the example below. The HTTP response is returned in response.

      This method returns false for HTTP response status codes of 400 or higher, but the response object is still provided in response. If response's status code is 0, it indicates no response was received due to a communication error or another issue. In such cases, check the LastErrorText property for details.

      Parameters:
      verb - the verb argument (not null)
      url - the url argument (not null)
      json - the json argument (not null)
      response - the response argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • httpReq

      public void httpReq​(String url, HttpRequest request, HttpResponse response)
      Sends an HTTP request to url where the content of the request is defined by request. The path and query part of target is taken from the url instead of the path property within request. 
      scheme   host       path             query    
 ┌────┐  ┌─────────┐┌──────────────┐ ┌────────┐ 
 https://example.com/docs/index.html?search=test

      The HTTP response is returned in response.

      This method returns false for HTTP response status codes of 400 or higher, but the response object is still provided in response. If response's status code is 0, it indicates no response was received due to a communication error or another issue. In such cases, check the LastErrorText property for details.

      Parameters:
      url - the url argument (not null)
      request - the request argument (not null)
      response - the response argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • httpSReq

      public void httpSReq​(String domain, int port, boolean ssl, HttpRequest request, HttpResponse response)
      Sends an HTTP request to web server at domain:port using TLS if ssl equals true. The content of the request, including the path part of the URL, query params, additional headers, and request body is defined by request.

      Note: The domain should include only the domain (host), not the complete URL. The path and query params are defined in the request object. 

      scheme   host       path             query    
 ┌────┐  ┌─────────┐┌──────────────┐ ┌────────┐ 
 https://example.com/docs/index.html?search=test

      response contains the HTTP response.

      This method returns false for HTTP response status codes of 400 or higher, but the response object is still provided in response. If response's status code is 0, it indicates no response was received due to a communication error or another issue. In such cases, check the LastErrorText property for details.

      Parameters:
      domain - the domain argument (not null)
      port - the port argument
      ssl - the ssl argument
      request - the request argument (not null)
      response - the response argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • httpSb

      public void httpSb​(String verb, String url, StringBuilder sb, String charset, String contentType, HttpResponse response)
      Sends an HTTP request to url using the specified verb (e.g., POST, PUT, PATCH). The request body contains the text passed in sb, and the content type is specified by contentType (e.g., text/xml, application/json). The charset defines the text encoding, such as utf-8 or iso-8859-1. The HTTP response is returned in response.

      This method returns false for HTTP response status codes of 400 or higher, but the response object is still provided in response. If response's status code is 0, it indicates no response was received due to a communication error or another issue. In such cases, check the LastErrorText property for details.

      Parameters:
      verb - the verb argument (not null)
      url - the url argument (not null)
      sb - the sb argument (not null)
      charset - the charset argument (not null)
      contentType - the contentType argument (not null)
      response - the response argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • httpStr

      public void httpStr​(String verb, String url, String bodyStr, String charset, String contentType, HttpResponse response)
      Sends an HTTP request to url using the specified verb (e.g., POST, PUT, PATCH). The request body contains the text passed in bodyStr, and the content type is specified by contentType (e.g., text/xml, application/json). The charset defines the text encoding, such as utf-8 or iso-8859-1. The HTTP response is returned in response.

      This method returns false for HTTP response status codes of 400 or higher, but the response object is still provided in response. If response's status code is 0, it indicates no response was received due to a communication error or another issue. In such cases, check the LastErrorText property for details.

      Parameters:
      verb - the verb argument (not null)
      url - the url argument (not null)
      bodyStr - the bodyStr argument (not null)
      charset - the charset argument (not null)
      contentType - the contentType argument (not null)
      response - the response argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • ocspCheck

      public int ocspCheck​(String domain, int port)
      Gets the server certificate at a domain:port and then sends an OCSP request to the certificate's OCSP URL to determine if the certificate has been revoked. Returns the OCSP status, which has one of the following values:
      • -1: Unable to check. See the contents of the LastErrorText property for more informaiton.
      • 0: Good
      • 1: Revoked
      • 2: Unknown

      Parameters:
      domain - the domain argument (not null)
      port - the port argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • parseOcspReply

      public int parseOcspReply​(BinData ocspReply, JsonObject replyData)
      Parses an OCSP reply. Returns the following possible integer values:
      • -1: The ocspReply does not contain a valid OCSP reply.
      • 0: Successful - Response has valid confirmations..
      • 1: Malformed request - Illegal confirmation request.
      • 2: Internal error - Internal error in issuer.
      • 3: Try later - Try again later.
      • 4: Not used - This value is never returned.
      • 5: Sig required - Must sign the request.
      • 6: Unauthorized - Request unauthorized.

      The binaryOCSP reply is provided in ocspReply. The replyData is populated with data parsed from ocspReply.

      OCSP requests are created by calling createOcspRequest(JsonObject, BinData) .

      Parameters:
      ocspReply - the ocspReply argument (not null)
      replyData - the replyData argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • quickDeleteStr

      public String quickDeleteStr​(String url)
      This function sends an HTTP DELETE request to a specified URL and returns the response body as a string.

      The HTTP response code is stored in the getLastStatus() property, while additional response details are available in properties such as getLastResponseHeader() , getLastResponseBody() , getLastModDate() , and getLastContentType() .

      Parameters:
      url - the url argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • quickGetBd

      public void quickGetBd​(String url, BinData binData)
      This function sends an HTTP GET request to a specified URL, which can include query parameters, and returns the binary response body in binData.

      The HTTP response code is stored in the getLastStatus() property. Additional response details can be found in properties like getLastResponseHeader() , getLastModDate() , and getLastContentType() .

      A response code of 400 or higher indicates a failure. If the error response is text-based and the getKeepResponseBody() property is true, it will be available in the getLastResponseBody() property.

      Parameters:
      url - the url argument (not null)
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • quickGetSb

      public void quickGetSb​(String url, StringBuilder sbContent)
      This function sends an HTTP GET request to a specified URL, which can include query parameters, and returns the text response body in sbContent. The existing content of sbContent, if any, is cleared and replaced with the downloaded content.

      The response status code is stored in the getLastStatus() property. Additional response details can be found in properties like getLastResponseHeader() , getLastModDate() , and getLastContentType() .

      If the response status code is >= 400, then this method returns false, but the body of the HTTP response is still returned in sbContent. This allows for the application to examine the response body for cases where an error is returned, but the expected content is not received.

      Parameters:
      url - the url argument (not null)
      sbContent - the sbContent argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • quickGetStr

      public String quickGetStr​(String url)
      This function sends an HTTP GET request to a specified URL, which can include query parameters, and returns the text response body.

      The response status code is stored in the getLastStatus() property. Additional response details can be found in properties like getLastResponseHeader() , getLastModDate() , and getLastContentType() .

      A response code of 400 or higher indicates a failure. If the error response is text-based and the getKeepResponseBody() property is true, it will be available in the getLastResponseBody() property.

      Parameters:
      url - the url argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeRequestHeader

      public void removeRequestHeader​(String name)
      Eliminates a header field from being included in all HTTP requests, except for those sent by the httpReq(String, HttpRequest, HttpResponse) and httpSReq(String, int, boolean, HttpRequest, HttpResponse) methods, which rely on header fields provided in an HttpRequest object via method arguments.
      Parameters:
      name - the name argument (not null)

    • renderGet

      public String renderGet​(String url)
      Builds the GET request that would be sent if a method such as quickGetStr(String) was called. Instead of sending the request, it returns the HTTP request that would have been sent.
      Parameters:
      url - the url argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • resumeDownload

      public void resumeDownload​(String url, String targetFilename)
      Resumes downloading content from url and saves it to a partially completed local file at targetFilename. If the file at targetFilename doesn't exist or is empty, this method functions the same as download(String, String) .

      The download succeeds if the HTTP response status code is in the 200s. If unsuccessful, no output file is created. If the getKeepResponseBody() property is set to true, the server's error response will be available in the getLastResponseBody() property.

      The response status code will be available in the getLastStatus() property.

      Parameters:
      url - the url argument (not null)
      targetFilename - the targetFilename argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • resumeDownloadBd

      public void resumeDownloadBd​(String url, BinData binData)
      Resumes a download from where it left off, determined by the number of bytes in binData. This method can be called multiple times until the download is complete.

      The download succeeds if the HTTP response status code is in the 200s. If unsuccessful, no output file is created. If the getKeepResponseBody() property is set to true, the server's error response will be available in the getLastResponseBody() property.

      The response status code will be available in the getLastStatus() property.

      Parameters:
      url - the url argument (not null)
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3CreateBucket

      public void s3CreateBucket​(String bucketPath)
      Creates a new Amazon S3 bucket.

      Note: You can add x-amz-* headers, including metadata, to any S3 request by using setRequestHeader(String, String) for each header. This applies to all S3 methods, even if not explicitly mentioned.

      Parameters:
      bucketPath - the bucketPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3DeleteBucket

      public void s3DeleteBucket​(String bucketPath)
      Deletes an Amazon S3 bucket.

      Note: Ensure the getAwsEndpoint() property is set to the correct region if the bucket is outside us-east-1, for example, eu-central-1. For S3-compatible services like Wasabi, always set the getAwsEndpoint() , such as s3.wasabisys.com or s3.eu-central-1.wasabisys.com.

      Parameters:
      bucketPath - the bucketPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3DeleteObject

      public void s3DeleteObject​(String bucketPath, String objectName)
      Deletes a remote file (object) on the Amazon S3 service.
      Parameters:
      bucketPath - the bucketPath argument (not null)
      objectName - the objectName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3DeleteObjects

      public void s3DeleteObjects​(String bucketName, StringTable objectNames, JsonObject jsonResponse)
      Deletes several objects from a bucket with a single request. objectNames includes the object names (or keys) to be deleted. To delete a specific object version, add a versionId to the object name, like this: SampleDocument.txt; VersionId=OYcLXagmS.WaD..oyH4KRguB95_YhLs7. If successful, jsonResponse will contain the JSON response.
      Parameters:
      bucketName - the bucketName argument (not null)
      objectNames - the objectNames argument (not null)
      jsonResponse - the jsonResponse argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3DownloadBd

      public void s3DownloadBd​(String bucketPath, String objectName, BinData bd)
      Downloads a file from the Amazon S3 service into bd.
      Parameters:
      bucketPath - the bucketPath argument (not null)
      objectName - the objectName argument (not null)
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3DownloadFile

      public void s3DownloadFile​(String bucketPath, String objectName, String localFilePath)
      Downloads a file from the Amazon S3 service.

      Note: Ensure the getAwsEndpoint() property is set to the correct region if the bucket is outside us-east-1, for example, eu-central-1. For S3-compatible services like Wasabi, always set the getAwsEndpoint() , such as s3.wasabisys.com or s3.eu-central-1.wasabisys.com.

      Parameters:
      bucketPath - the bucketPath argument (not null)
      objectName - the objectName argument (not null)
      localFilePath - the localFilePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3DownloadString

      public String s3DownloadString​(String bucketPath, String objectName, String charset)
      Downloads a text file (object) from the Amazon S3 service and returns the content as a string. The charset specifies the character encoding, such as utf-8, of the remote text object.

      Note: Ensure the getAwsEndpoint() property is set to the correct region if the bucket is outside us-east-1, for example, eu-central-1. For S3-compatible services like Wasabi, always set the getAwsEndpoint() , such as s3.wasabisys.com or s3.eu-central-1.wasabisys.com.

      Parameters:
      bucketPath - the bucketPath argument (not null)
      objectName - the objectName argument (not null)
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3FileExists

      public int s3FileExists​(String bucketPath, String objectName)
      Checks the existence of a remote file, returning:
      • 1 if the file exists
      • 0 if the file does not exist
      • -1 if the check failed
      • 2 if in asynchronous mode, indicating the background task started successfully

      Note: Ensure the getAwsEndpoint() property is set to the correct region if the bucket is outside us-east-1, for example, eu-central-1. For S3-compatible services like Wasabi, always set the getAwsEndpoint() , such as s3.wasabisys.com or s3.eu-central-1.wasabisys.com.

      Parameters:
      bucketPath - the bucketPath argument (not null)
      objectName - the objectName argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • s3GenPresignedUrl

      public String s3GenPresignedUrl​(String httpVerb, boolean useHttps, String bucketName, String path, int numSecondsValid, String awsService)
      This method generates a temporary pre-signed URL for Amazon S3. Before calling this method, ensure the following properties are set to valid values: getAwsSecretKey() , getAwsAccessKey() , and getAwsRegion() . If the endpoint differs from s3.amazonaws.com, set the getAwsEndpoint() property accordingly.

      httpVerb is the HTTP verb (e.g., GET, PUT, POST, DELETE). awsService is the name of the AWS service (e.g., s3, s3-accelerate). If useHttps is true, the returned URL will start with https://; otherwise, it will start with http://.

      The generated URL has this format: 

      https://<AwsEndpoint>/<bucket_name>/<path>
 ?X-Amz-Algorithm=AWS4-HMAC-SHA256
 &X-Amz-Credential=<AwsAccessKey>/<currentDate>/<AwsRegion>/<awsService>/aws4_request
 &X-Amz-Date=<currentDateTime>
 &X-Amz-Expires=<numSecondsValid>
 &X-Amz-SignedHeaders=host
 &X-Amz-Signature=<signature-value>
      Parameters:
      httpVerb - the httpVerb argument (not null)
      useHttps - the useHttps argument
      bucketName - the bucketName argument (not null)
      path - the path argument (not null)
      numSecondsValid - the numSecondsValid argument
      awsService - the awsService argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3ListBucketObjects

      public String s3ListBucketObjects​(String bucketPath)
      Retrieve an XML-formatted list of objects in an Amazon S3 bucket, similar to a directory listing.

      bucketPath can include URL-encoded parameters. For example, to list objects in a bucket named ChilkatABC with a max-keys value of 2000 and a marker of xyz, pass the following string as bucketPath to the S3_ListBucketObjects method: ChilkatABC?max-keys=2000&marker=xyz

      This method recognizes all parameters listed in the AWS documentation for bucket object listing: delimiter, marker, max-keys, and prefix. For further details, refer to Amazon's AWS online documentation.

      Parameters:
      bucketPath - the bucketPath argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3ListBuckets

      public String s3ListBuckets()
      Retrieves the XML listing of the buckets for an Amazon S3 account.
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3UploadBd

      public void s3UploadBd​(BinData bd, String contentType, String bucketPath, String objectName)
      Uploads the contents of bd as a file to the Amazon S3 service.

      Note: x-amz-* headers, including metadata, can be added to any S3 request by adding each header with a call to setRequestHeader(String, String) . This applies to all S3 methods, even if not explicitly stated.

      Note: Ensure the getAwsEndpoint() property is set to the correct region if the bucket is outside us-east-1, for example, eu-central-1. For S3-compatible services like Wasabi, always set the getAwsEndpoint() , such as s3.wasabisys.com or s3.eu-central-1.wasabisys.com.

      Parameters:
      bd - the bd argument (not null)
      contentType - the contentType argument (not null)
      bucketPath - the bucketPath argument (not null)
      objectName - the objectName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3UploadFile

      public void s3UploadFile​(String localFilePath, String contentType, String bucketPath, String objectName)
      Uploads a file to the Amazon S3 service.

      Note: x-amz-* headers, including metadata, can be added to any S3 request by adding each header with a call to setRequestHeader(String, String) . This applies to all S3 methods, even if not explicitly stated.

      Note: Ensure the getAwsEndpoint() property is set to the correct region if the bucket is outside us-east-1, for example, eu-central-1. For S3-compatible services like Wasabi, always set the getAwsEndpoint() , such as s3.wasabisys.com or s3.eu-central-1.wasabisys.com.

      Parameters:
      localFilePath - the localFilePath argument (not null)
      contentType - the contentType argument (not null)
      bucketPath - the bucketPath argument (not null)
      objectName - the objectName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • s3UploadString

      public void s3UploadString​(String objectContent, String charset, String contentType, String bucketPath, String objectName)
      Uploads the content of objectContent as a file to Amazon S3. charset specifies the string's character encoding (byte representation).

      Note: x-amz-* headers, including metadata, can be added to any S3 request by adding each header with a call to setRequestHeader(String, String) . This applies to all S3 methods, even if not explicitly stated.

      Note: Ensure the getAwsEndpoint() property is set to the correct region if the bucket is outside us-east-1, for example, eu-central-1. For S3-compatible services like Wasabi, always set the getAwsEndpoint() , such as s3.wasabisys.com or s3.eu-central-1.wasabisys.com.

      Parameters:
      objectContent - the objectContent argument (not null)
      charset - the charset argument (not null)
      contentType - the contentType argument (not null)
      bucketPath - the bucketPath argument (not null)
      objectName - the objectName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthPrivateKey

      public void setAuthPrivateKey​(String publicKeyId, PrivateKey privKey)
      Sets the private key to be used with some forms of authentication. For example, this is used automatically add the Authorization header (Signature) for Amazon Pay requests.
      Parameters:
      publicKeyId - the publicKeyId argument (not null)
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAuthTokenSb

      public void setAuthTokenSb​(StringBuilder sb)
      Sets the getAuthToken() property. The sb contains the OAuth2 access token to be used.
      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setClientAssertionKey

      public void setClientAssertionKey​(PrivateKey privKey, String kid)
      Sets the private key for private_key_jwt client authentication (RFC 7523) in the OAuth2 client credentials flow of the getAuthToken() property. When the AuthToken is set to JSON with the client credentials, Chilkat creates a new client_assertion JWT, signed with this key, for each token request, and sends it with client_assertion_type set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer. The JWT has the claims iss and sub (the client_id from the JSON), aud (the token_endpoint), iat, exp (5 minutes after iat) and a unique jti.

      kid is the key ID, which is put in the JWT header. Pass an empty string if the authorization server does not need one. The key can be an EC key on the P-256, P-384 or P-521 curve (the JWT is signed with ES256, ES384 or ES512), an RSA key of 2048 bits or more (RS256), or an Ed25519 key (EdDSA). For example, load a key in JWK format with PrivateKey.LoadJwk and pass its kid.

      This is typically used with setDPoPKey(PrivateKey), when the authorization server requires both a client assertion and DPoP. The same key may be passed to both methods if the server allows it. A client_assertion or client_assertion_type member in the AuthToken JSON is ignored once this key is set. The JSON must include the client_id.

      Parameters:
      privKey - the privKey argument (not null)
      kid - the kid argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setCookieXml

      public void setCookieXml​(String domain, String cookieXml)
      This method restores cookies for a specified domain. It requires that the cookies, previously obtained using the getCookieXml(String) method, are stored in a persistent storage like a database or file. An application can then restore these cookies using this method.
      Parameters:
      domain - the domain argument (not null)
      cookieXml - the cookieXml argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setDPoPKey

      public void setDPoPKey​(PrivateKey privKey)
      Sets the private key for automatically adding the DPoP header to HTTP requests. Chilkat will generate a JWT (a DPoP proof) for each request and include the DPoP header. Ensure the getAuthToken() property is also set.

      The key can be an EC key on the P-256, P-384 or P-521 curve (the proof is signed with ES256, ES384 or ES512), an RSA key of 2048 bits or more (RS256), or an Ed25519 key (EdDSA). Before v11.7.0, only EC keys were accepted.

      Parameters:
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setOAuthRsaKey

      public void setOAuthRsaKey​(PrivateKey privKey)
      Sets the RSA key to be used with OAuth 1.0a authentication when the getOAuthSigMethod() is RSA-SHA256 or RSA-SHA1.
      Parameters:
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setRequestHeader

      public void setRequestHeader​(String headerFieldName, String headerFieldValue)
      Adds a header field to be included in all HTTP requests, except for those sent by the httpReq(String, HttpRequest, HttpResponse) and httpSReq(String, int, boolean, HttpRequest, HttpResponse) methods, which rely on header fields provided in an HttpRequest object via method arguments. If the header field already exists, it is replaced.

      Use the removeRequestHeader(String) method to delete a specific header. Setting a header field to an empty string will also remove it, unless the AllowEmptyHeaders option in getUncommonOptions() is used.

      Avoid setting the Authorization header manually. Instead, use the appropriate authorization properties such as getPassword() , getAuthToken() , getAuthSignature() , getBasicAuth() , getDigestAuth() , getNtlmAuth() , getOAuth1() , getOAuthToken() , etc.

      To add cookies, use the Cookie header field format: Cookie: name1=value1; name2=value2; name3=value3.

      Do not manually set the Content-Length header. Chilkat will automatically calculate and include Content-Length when sending the HTTP request.

      Parameters:
      headerFieldName - the headerFieldName argument (not null)
      headerFieldValue - the headerFieldValue argument (not null)

    • setSecurePassword

      public void setSecurePassword​(SecureString password)
      Equivalent to setting the getPassword() property but offers a more secure method by using a secure string object.
      Parameters:
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSslCertRequirement

      public void setSslCertRequirement​(String reqName, String reqValue)
      Enforces a requirement on the server's certificate. The reqName can be one of the following:
      • SubjectDN
      • SubjectCN
      • IssuerDN
      • IssuerCN
      • SAN

      The reqName specifies the part of the certificate, and the reqValue is the value that it must match exactly or with a wildcard (*), for example "*.example.com". If the server's certificate does not match, the SSL / TLS connection is aborted.

      Parameters:
      reqName - the reqName argument (not null)
      reqValue - the reqValue argument (not null)

    • setSslClientCert

      public void setSslClientCert​(Cert cert)
      Facilitates the use of a client-side certificate for a TLS connection, enabling mutual authentication. In a standard TLS connection, the server alone presents a certificate during the handshake to verify its identity. With mutual TLS (mTLS), the client also presents a trusted certificate, allowing the server to authenticate the client's identity. This process enhances security by adding a layer of verification beyond just usernames, passwords, or tokens.
      Parameters:
      cert - the cert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSslClientCertPem

      public void setSslClientCertPem​(String pemDataOrPath, String pemPassword)
      This is identical to the setSslClientCert(Cert) method, but it allows the certificate with a private key to be in PEM format.
      Parameters:
      pemDataOrPath - the pemDataOrPath argument (not null)
      pemPassword - the pemPassword argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSslClientCertPfx

      public void setSslClientCertPfx​(String pfxPath, String pfxPassword)
      This is identical to the setSslClientCert(Cert) method, but enables you to provide a certificate with private key directly from a .pfx or .p12 file.
      Parameters:
      pfxPath - the pfxPath argument (not null)
      pfxPassword - the pfxPassword argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setUrlVar

      public void setUrlVar​(String name, String value)
      Sets a variable's value for URL substitutions used in any method. Variables are formatted as {$varName} in URLs, such as: https://graph.microsoft.com/v1.0/users/{$id}.

      Call clearUrlVars() to unset all URL variables.

      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sharePointOnlineAuth

      public void sharePointOnlineAuth​(String siteUrl, String username, SecureString password, JsonObject extraInfo)
      This method authenticates with SharePoint Online and if successful, sets a cookie which is used for all following SharePoint HTTP requests. Before using this method, ensure you configure the getCookieDir() property to either memory or a specific directory path to store the authentication cookie, which will then be automatically used for subsequent HTTP requests.

      Using this method automatically sets the getSaveCookies() and getSendCookies() properties to true, as these settings are necessary for SharePoint Online authentication.

      To use the method, provide the following arguments:

      • siteUrl: The URL, e.g., https://yourdomain.sharepoint.com/
      • username: An email address, e.g., username@yourdomain.com
      • password: The Sharepoint password.
      • extraInfo: Can be an empty JSON object. Reserved for additional information if needed in the future.

      Parameters:
      siteUrl - the siteUrl argument (not null)
      username - the username argument (not null)
      password - the password argument (not null)
      extraInfo - the extraInfo argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sleepMs

      public void sleepMs​(int millisec)
      This method makes the calling process sleep for a specified number of milliseconds.
      Parameters:
      millisec - the millisec argument

    • urlDecode

      public String urlDecode​(String str)
      URL decodes a string.
      Parameters:
      str - the str argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • urlEncode

      public String urlEncode​(String str)
      URL encodes a string.
      Parameters:
      str - the str argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifyTimestampReply

      public int verifyTimestampReply​(BinData timestampReply, Cert tsaCert)
      Verifies a timestamp reply received from a timestamp authority (TSA). Returns the following possible integer values:
      • -1: The timestampReply does not contain a valid timestamp reply.
      • -2: The timestampReply is a valid timestamp reply, but failed verification using the public key of the tsaCert.
      • 0: Granted and verified.
      • 1: Granted and verified, with mods (see RFC 3161)
      • 2: Rejected.
      • 3: Waiting.
      • 4: Revocation Warning
      • 5: Revocation Notification

      If the timestamp reply (timestampReply) is known to be from a trusted source, then the tsaCert may be empty. If tsaCert is empty (never loaded with a certificate), then the verification will use the certificate embedded in the timestamp reply.

      The createTimestampRequest(String, String, String, boolean, boolean, BinData) method is used to create a timestamp request.

      Parameters:
      timestampReply - the timestampReply argument (not null)
      tsaCert - the tsaCert argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener