Http Unicode C Reference Documentation

Http

Class for sending HTTP requests and receiving server responses.

  • Supports GET, POST, HEAD, PUT, DELETE, WebDav, and custom HTTP request methods.
  • HTTP Authentication: Basic, NTLM, Digest, Negotiate
  • HTTPS (SSL/TLS) with client-side certificate capabilities.
  • Cookie caching, auto-resend, persisting to XML files.
  • Content caching.
  • Supports HTTP proxies
  • Auto-follow redirects if desired.
  • Amazon S3 methods.
  • XML HTTP Request
  • HTTP file upload capabilities
  • Asynchronous features -- putting HTTP requests in background threads.
  • Supports SOCK5/SOCKS4 proxies.
  • IPv6 capable.

Create/Dispose

HCkHttpW CkHttpW_Create(void);

Creates an instance of the HCkHttpW object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkHttpW_Dispose(HCkHttpW handle);

Objects created by calling CkHttpW_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkHttpW_Dispose.

Callback Functions

Callback Functions are Introduced in Chilkat v9.5.0.56

void CkHttpW_setAbortCheck(HCkHttp cHandle, BOOL (*fnAbortCheck)(void));

Provides the opportunity for a method call to be aborted. If TRUE is returned, the operation in progress is aborted. Return FALSE to allow the current method call to continue. This callback function is called periodically based on the value of the HeartbeatMs property. (If HeartbeatMs is 0, then no callbacks are made.) As an example, to make 5 AbortCheck callbacks per second, set the HeartbeatMs property equal to 200.

C Example using Callback Functions

void CkHttpW_setPercentDone(HCkHttp cHandle, BOOL (*fnPercentDone)(int pctDone));

Provides the percentage completed for any method that involves network communications or time-consuming processing (assuming it is a method where a percentage completion can be measured). This callback is only called when it is possible to know a percentage completion, and when it makes sense to express the operation as a percentage completed. The pctDone argument will have a value from 1 to 100. For methods that complete very quickly, the number of PercentDone callbacks will vary, but the final callback should have a value of 100. For long running operations, no more than one callback per percentage point will occur (for example: 1, 2, 3, ... 98, 99, 100).

This callback counts as an AbortCheck callback, and takes the place of the AbortCheck event when it fires.

The return value indicates whether the method call should be aborted, or whether it should proceed. Return TRUE to abort, and FALSE to proceed.

void CkHttpW_setProgressInfo(HCkHttp cHandle, void (*fnProgressInfo)(const wchar_t *name, const wchar_t *value));

This is a general callback that provides name/value information about what is happening at certain points during a method call. To see the information provided in ProgressInfo callbacks, if any, write code to handle this event and log the name/value pairs. Most are self-explanatory.

void CkHttpW_setTaskCompleted(HCkHttp cHandle, void (*fnTaskCompleted)(HCkTask hTask));

Called in the background thread when an asynchronous task completes. (Note: When an async method is running, all callbacks are in the background thread.)

Properties

BOOL CkHttpW_getAbortCurrent(HCkHttpW cHandle);

void CkHttpW_putAbortCurrent(HCkHttpW cHandle, BOOL newVal);

Introduced in version 9.5.0.58

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

void CkHttpW_getAccept(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putAccept(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_accept(HCkHttpW cHandle);

The Accept header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "*/*".

void CkHttpW_getAcceptCharset(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putAcceptCharset(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_acceptCharset(HCkHttpW cHandle);

The AcceptCharset header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "ISO-8859-1,utf-8;q=0.7,*;q=0.7".

void CkHttpW_getAcceptLanguage(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putAcceptLanguage(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_acceptLanguage(HCkHttpW cHandle);

The AcceptLanguage header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "en-us,en;q=0.5".

BOOL CkHttpW_getAllowGzip(HCkHttpW cHandle);

void CkHttpW_putAllowGzip(HCkHttpW cHandle, BOOL newVal);

Controls whether the "Accept-Encoding: gzip" header is added to HTTP requests sent via any method that sends an HTTP request without using the HttpRequest object (such as QuickGetStr). If FALSE, then the empty Accept-Encoding header is added which means the server response should contain the uncompressed content. The default value is TRUE, which means the server, if it chooses, may send a gzipped response.

BOOL CkHttpW_getAllowHeaderFolding(HCkHttpW cHandle);

void CkHttpW_putAllowHeaderFolding(HCkHttpW cHandle, BOOL newVal);

Introduced in version 9.5.0.63

If this property is set to FALSE, then no MIME header folding will be automatically applied to any request header. The default is TRUE.

void CkHttpW_getAuthToken(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putAuthToken(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_authToken(HCkHttpW cHandle);

Introduced in version 9.5.0.67

If set, then automatically adds the "Authorization: Bearer " header to all requests.

BOOL CkHttpW_getAutoAddHostHeader(HCkHttpW cHandle);

void CkHttpW_putAutoAddHostHeader(HCkHttpW cHandle, BOOL newVal);

If set to true, the "Host" header field will automatically be added to the request header for any QuickGet or QuickGetStr method calls. The value of the Host header field is taken from the hostname part of the URL passed to QuickGet/QuickGetStr.

void CkHttpW_getAwsAccessKey(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putAwsAccessKey(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_awsAccessKey(HCkHttpW cHandle);

The AWS Access Key to be used with the Amazon S3 methods listed below.

void CkHttpW_getAwsEndpoint(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putAwsEndpoint(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_awsEndpoint(HCkHttpW cHandle);

The regional endpoint (domain) to be used for Amazon S3 method calls. The default value is "s3.amazonaws.com". This can be set to any valid Amazon S3 endpoint, such as "s3-eu-west-1.amazonaws.com", or the endpoints for S3-API compatible services from other different providers.

void CkHttpW_getAwsRegion(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putAwsRegion(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_awsRegion(HCkHttpW cHandle);

Introduced in version 9.5.0.56

The AWS (S3) region, such as "us-east-1", "us-west-2", "eu-west-1", "eu-central-1", etc. This propery defaults to "us-east-1". It is only used when the AwsSignatureVersion property is set to 4. When the AwsSignatureVersion property is set to 2, then this property is unused.

void CkHttpW_getAwsSecretKey(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putAwsSecretKey(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_awsSecretKey(HCkHttpW cHandle);

The AWS Secret Key to be used with the Amazon S3 methods listed below.

int CkHttpW_getAwsSignatureVersion(HCkHttpW cHandle);

void CkHttpW_putAwsSignatureVersion(HCkHttpW cHandle, int newVal);

Introduced in version 9.5.0.56

Selects the AWS Signature Version algorithm. The default value is 2. May be set to 4 to select AWS Signature Version 4.

void CkHttpW_getAwsSubResources(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putAwsSubResources(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_awsSubResources(HCkHttpW cHandle);

The AWS sub-resources to be used with the Amazon S3 methods listed below.

If the S3 request needs to address a sub-resource, like ?versioning, ?policy, ?location, ?acl, or ?torrent, or ?versionid append the sub-resource and its value if it has one. Note that in case of multiple sub-resources, sub-resources must be lexicographically sorted by sub-resource name and separated by '&'. e.g. "acl&versionId=value"

The list of sub-resources that can be included are: acl, location, logging, notification, partNumber, policy, requestPayment, torrent, uploadId, uploads, versionId, versioning, versions and website.

int CkHttpW_getBandwidthThrottleDown(HCkHttpW cHandle);

void CkHttpW_putBandwidthThrottleDown(HCkHttpW cHandle, int newVal);

Introduced in version 9.5.0.49

If non-zero, limits (throttles) the download bandwidth to approximately this maximum number of bytes per second. The default value of this property is 0.

int CkHttpW_getBandwidthThrottleUp(HCkHttpW cHandle);

void CkHttpW_putBandwidthThrottleUp(HCkHttpW cHandle, int newVal);

Introduced in version 9.5.0.49

If non-zero, limits (throttles) the upload bandwidth to approximately this maximum number of bytes per second. The default value of this property is 0.

BOOL CkHttpW_getBasicAuth(HCkHttpW cHandle);

void CkHttpW_putBasicAuth(HCkHttpW cHandle, BOOL newVal);

If HTTP basic authentication is needed, this property must be set to TRUE. The HTTP protocol allows for several different types of authentication schemes, such as NTLM, Digest, OAuth1, etc. A given server will support (or allow) certain authentication schemes (also known as authentication methods). Except for the "Basic" authentication method, the other forms of authentication do not involve sending the login and password in plain unencrypted text over the connection. The Basic authentication method is insecure in that it sends the login/password for all to see. If the connection is SSL/TLS, then this might be considered OK. Chilkat takes the safe approach and will not allow Basic authentication unless this property has been explicitly set to TRUE. The default value of this property is FALSE.

Note: It is not required to know the authentication methods accepted by the server beforehand (except for the case of Basic authentication). When authentication is required, Chilkat will first send the request without the Authorization header, receive back the 401 Authorization Required response along with information about what authentication methods are accepted, and then re-send with an accepted authentication method. If the authentication method is known in advance, then an application may set the appropriate property, such as NtlmAuth to TRUE so that the extra (internal) round-trip is not required.

void CkHttpW_getBgLastErrorText(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_bgLastErrorText(HCkHttpW cHandle);

This property is deprecated. It will be removed in a future version.

When a background-enabled method is run asynchronously in a background thread, the last-error information is saved here and not in the LastErrorText property. If the background method fails, this will contain information about what transpired. (This property also contains information when the background method succeeds.)

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

int CkHttpW_getBgPercentDone(HCkHttpW cHandle);

This property is deprecated. It will be removed in a future version.

The integer percent completed for a background HTTP method call. The value will be between 0 and 100 while a background method call is in progress. Otherwise, the value is meaningless. The BgPercentDone only applies in cases where it is possible to track completion by a percentage. If an HTTP response is chunked, then there is no way of knowing how much response data is forthcoming, and therefore it is not possible to track the percentage completed.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

void CkHttpW_getBgResultData(HCkHttpW cHandle, HCkByteData retval);

This property is deprecated. It will be removed in a future version.

If a backgrounded method returns a byte array, the returned data is found here.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

int CkHttpW_getBgResultInt(HCkHttpW cHandle);

This property is deprecated. It will be removed in a future version.

If a backgrounded method returns an integer, the return value is found here.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

void CkHttpW_getBgResultString(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_bgResultString(HCkHttpW cHandle);

This property is deprecated. It will be removed in a future version.

If a backgrounded method returns a string, the return value is found here.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

BOOL CkHttpW_getBgTaskFinished(HCkHttpW cHandle);

This property is deprecated. It will be removed in a future version.

Becomes TRUE when the background method completes. Your application would periodically check for this condition.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

BOOL CkHttpW_getBgTaskRunning(HCkHttpW cHandle);

This property is deprecated. It will be removed in a future version.

If TRUE then the object instance already has a backgrounded method running. Another backgrounded method cannot be started until the 1st completes. (Multiple simultaneous background methods may run by using multiple object instances.)

If FALSE, then no method is currently running in a background thread.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

BOOL CkHttpW_getBgTaskSuccess(HCkHttpW cHandle);

This property is deprecated. It will be removed in a future version.

This property's value is only meaningful (TRUE or FALSE) after a backgrounded method completes.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

void CkHttpW_getClientIpAddress(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putClientIpAddress(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_clientIpAddress(HCkHttpW cHandle);

The IP address to use for computers with multiple network interfaces or IP addresses. For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.

The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124".

Important Bind to Adapter Notes for Windows

int CkHttpW_getConnectFailReason(HCkHttpW cHandle);

Introduced in version 9.5.0.56

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

void CkHttpW_getConnection(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putConnection(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_connection(HCkHttpW cHandle);

The Connection header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "Keep-Alive". To prevent the Connection header from being added to the HTTP header, set this property to the empty string.

int CkHttpW_getConnectTimeout(HCkHttpW cHandle);

void CkHttpW_putConnectTimeout(HCkHttpW cHandle, int newVal);

The amount of time in seconds to wait before timing out when connecting to an HTTP server. The default ConnectTimeout is 30 seconds.

Note: This is the maximum number of seconds to wait for a server to accept a TCP connection. Once the connection is accepted, and bytes begin flowing back-and-forth, then it is the ReadTimeout property that applies. It is the ReadTimeout that applies when receiving data, which includes the reads that occur during a TLS handshake.

void CkHttpW_getCookieDir(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putCookieDir(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_cookieDir(HCkHttpW cHandle);

Specifies a directory where cookies are automatically persisted if the Http.SaveCookies property is turned on. Cookies are stored in XML formatted files, one per domain, to main it easy for other programs to understand and parse. May be set to the string "memory" to cache cookies in memory.

Saving Cookies to XML Files

Caching cookies in-memory.

void CkHttpW_getDebugLogFilePath(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putDebugLogFilePath(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_debugLogFilePath(HCkHttpW cHandle);

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

int CkHttpW_getDefaultFreshPeriod(HCkHttpW cHandle);

void CkHttpW_putDefaultFreshPeriod(HCkHttpW cHandle, int newVal);

The default freshness period (in minutes) for cached documents when the FreshnessAlgorithm property is set to 0. The default value is 10080 (1 week).

BOOL CkHttpW_getDigestAuth(HCkHttpW cHandle);

void CkHttpW_putDigestAuth(HCkHttpW cHandle, BOOL newVal);

Setting this property to TRUE causes the HTTP component to use digest authentication. The default value is FALSE.

HTTP Authentication (Basic, NTLM, Digest, Negotiate/Kerberos)

int CkHttpW_getEventLogCount(HCkHttpW cHandle);

This property is deprecated. It will be removed in a future version.

If the KeepEventLog property is set to TRUE, then this property will contain the number of events that have accumulated in the in-memory event log. The events are indexed from 0 to EventLogCount-1. The ClearEventLog method may be called to clear the event log. The name and value of each event can be retrieved via the EventLogName and EventLogValue methods.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

BOOL CkHttpW_getFetchFromCache(HCkHttpW cHandle);

void CkHttpW_putFetchFromCache(HCkHttpW cHandle, BOOL newVal);

Set to true if pages should be fetched from cache when possible. Only HTTP GET requests are cached. HTTP responses that include Set-Cookie headers are not cached. A page is fetched from the disk cache if it is present and it is "fresh" according to the FreshnessAlgorithm property. If a page exists in cache but is not fresh, the HTTP component will issue a revalidate request and update the cache appropriately according to the response.

void CkHttpW_getFinalRedirectUrl(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_finalRedirectUrl(HCkHttpW cHandle);

If an HTTP GET was redirected (as indicated by the WasRedirected property), this property will contain the final redirect URL, assuming the FollowRedirects property is TRUE.

Note: Starting in v9.5.0.49, this property will contain the redirect URL for 301/302 responses even if FollowRedirects is not set to TRUE.

Tracing HTTP Redirects

BOOL CkHttpW_getFollowRedirects(HCkHttpW cHandle);

void CkHttpW_putFollowRedirects(HCkHttpW cHandle, BOOL newVal);

If true, then 301, 302, 303, and 307 redirects are automatically followed when calling QuickGet and QuickGetStr. FollowRedirects is true by default.

int CkHttpW_getFreshnessAlgorithm(HCkHttpW cHandle);

void CkHttpW_putFreshnessAlgorithm(HCkHttpW cHandle, int newVal);

The freshness algorithm to use when determining the freshness of a cached HTTP GET response. A value of 1 causes an LM-factor algorithm to be used. This is the default. The LMFactor property is a value between 1 and 100 indicating the percentage of time based on the last-modified date of the HTML page. For example, if the LMFactor is 50, and an HTML page was modified 10 days ago, then the page will expire (i.e. no longer be fresh) in 5 days (50% of 10 days). This only applies to HTTP responses that do not have page expiration information. If the FreshnessAlgorithm = 0, then a constant expire time period determined by the DefaultFreshPeriod property is used.

int CkHttpW_getHeartbeatMs(HCkHttpW cHandle);

void CkHttpW_putHeartbeatMs(HCkHttpW cHandle, int newVal);

This property is only valid in programming environment and languages that allow for event callbacks.

Specifies the time interval in milliseconds between AbortCheck events. A value of 0 (the default) indicate that no AbortCheck events will fire. Any HTTP operation can be aborted via the AbortCheck event.

BOOL CkHttpW_getIgnoreMustRevalidate(HCkHttpW cHandle);

void CkHttpW_putIgnoreMustRevalidate(HCkHttpW cHandle, BOOL newVal);

Some HTTP responses contain a "Cache-Control: must-revalidate" header. If this is present, the server is requesting that the client always issue a revalidate HTTP request instead of serving the page directly from cache. If IgnoreMustRevalidate is set to TRUE, then Chilkat HTTP will serve the page directly from cache without revalidating until the page is no longer fresh.

The default value of this property is FALSE.

BOOL CkHttpW_getIgnoreNoCache(HCkHttpW cHandle);

void CkHttpW_putIgnoreNoCache(HCkHttpW cHandle, BOOL newVal);

Some HTTP responses contain headers of various types that indicate that the page should not be cached. Chilkat HTTP will adhere to this unless this property is set to TRUE.

The default value of this property is FALSE.

BOOL CkHttpW_getKeepEventLog(HCkHttpW cHandle);

void CkHttpW_putKeepEventLog(HCkHttpW cHandle, BOOL newVal);

This property is deprecated. It will be removed in a future version.

If TRUE, an in-memory event log is kept for any method that communicates with an HTTP server (such as Download, PostUrlEncoded, QuickGetStr, SynchronousRequest, etc.). When HTTP methods are called asynchronously, the event log can be checked while the HTTP operation is in in progress. This is done by examining the EventLogCount property and then fetching each event's name and value via the EventLogName and EventLogValue methods. See this example: Asynchronous HTTP.

The ClearBgEventLog method may be called to clear the in-memory event log.

Important: If event logging is enabled, make sure to clear the event log after each HTTP method call. Otherwise the log will continue to grow without bounds.

The default value of this property is FALSE.

The following items may be found in the event log:

NameValue
SocketConnecthostname:port, called when initiating a connection.
SocketConnectedhostname:port, called after successfully connected.
HttpProxyConnecthostname:port
SslHandshake "Starting"/"Finished"
HttpGetBeginURL
HttpCacheHit"Returning page from cache."
HttpInfovarious conditions...
"Begin reading response" -- called when beginning to read the response.
"Finished reading response"
"Existing connection with HTTP server no longer open, restarting GET with new connection."
"Reading chunked response."
"UnGzipping response data"
"Connection:close header is present"
GetRequestthe full HTTP GET request to be sent to the server.
ResponseHeaderthe header of the HTTP response.
HttpStatusCodeHTTP response status code (integer)
ChunkSizeSize (in bytes) of next chunk in response.
ResponseContentLengthNon-chunked response size in bytes.
UnGzippedLengthIf the response was gzip compressed, this is the uncompressed size.
HostnameResolvehostname, Called when starting to resolve a hostname (to an IP address)
ResolvedToIpdotted IP address, called after hostname is resolved.
HttpAuthone of the following strings:
"Starting Negotiate Authentication"
"Starting NTLM Authentication"
"Adding Basic Authentication Header"
"Adding Proxy Authentication Header"
"Starting Proxy NTLM Authentication"
"Starting Digest Authentication"
CookieToSendValue of a Set-Cookie header field to be added to the outgoing request.
SavingCookie XML of cookie being persisted.
HttpRedirectRedirect URL
Socks4Connectdomain:port
Socks5Connectdomain:port
HttpRequestBeginVerb (such as POST, GET, PUT), domain:port/path
RequestHeaderThe full HTTP request header to be sent.
StartSendingRequestSize of entire request, including header, in number of bytes. (Not called for QuickGet) For uploads, this is the size of the entire upload (headers and all files combined)
SubPartHeaderThe header for one of the parts within a multipart request.
UploadFilenameThe file about to be uploaded (streamed from file to socket..)

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

BOOL CkHttpW_getKeepResponseBody(HCkHttpW cHandle);

void CkHttpW_putKeepResponseBody(HCkHttpW cHandle, BOOL newVal);

Introduced in version 9.5.0.55

If TRUE, then the response body, if text, is saved to the LastResponseBody property for all methods that do not return an HttpResponse object. The default value of this property is FALSE.

void CkHttpW_getLastContentType(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_lastContentType(HCkHttpW cHandle);

The content-type of the last HTTP response received by the HTTP component.

void CkHttpW_getLastErrorHtml(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_lastErrorHtml(HCkHttpW cHandle);

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

void CkHttpW_getLastErrorText(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_lastErrorText(HCkHttpW cHandle);

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

Concept of LastErrorText

LastErrorText Standard Information

void CkHttpW_getLastErrorXml(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_lastErrorXml(HCkHttpW cHandle);

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

void CkHttpW_getLastHeader(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_lastHeader(HCkHttpW cHandle);

The text of the last HTTP header sent by any of this class's methods. The purpose of this property is to allow the developer to examine the exact HTTP header for debugging purposes.

BOOL CkHttpW_getLastMethodSuccess(HCkHttpW cHandle);

void CkHttpW_putLastMethodSuccess(HCkHttpW cHandle, BOOL newVal);

Introduced in version 9.5.0.52

Indicate whether the last method call succeeded or failed. A value of TRUE indicates success, a value of FALSE indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = TRUE and failure = FALSE.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to TRUE. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

void CkHttpW_getLastModDate(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_lastModDate(HCkHttpW cHandle);

The value of the Last-Modified header in the last HTTP response received by the HTTP component.

void CkHttpW_getLastResponseBody(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_lastResponseBody(HCkHttpW cHandle);

Introduced in version 9.5.0.55

The response body of the last HTTP response received by the HTTP component (for methods that do not return an HttpResponse object). The last response body is only saved to this property IF the KeepResponseBody property is set to TRUE.

void CkHttpW_getLastResponseHeader(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_lastResponseHeader(HCkHttpW cHandle);

The entire response header for the last HTTP response received by the HTTP component (for methods that do not return an HttpResponse object).

int CkHttpW_getLastStatus(HCkHttpW cHandle);

The last HTTP status value received by the HTTP component. This only applies to methods that do not return an HTTP response object. For methods that return an HTTP response object, such as SynchronousRequest, the status code is found in the StatusCode property of the response object.

void CkHttpW_getLastStatusText(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_lastStatusText(HCkHttpW cHandle);

Introduced in version 9.5.0.69

The last HTTP status text received by the HTTP component. This only applies to methods that do not return an HTTP response object. For methods that return an HTTP response object, such as SynchronousRequest, the status text is found in the StatusText property of the response object.

int CkHttpW_getLMFactor(HCkHttpW cHandle);

void CkHttpW_putLMFactor(HCkHttpW cHandle, int newVal);

An integer between 1 and 100 that indicates the percentage of time from the HTTP page's last-modified date that will be used for the freshness period. The default value is 25. For example, if a page is fetched with a last-modified date of 4 weeks ago, and the LMFactor = 25, then the page will be considered fresh in the cache for 1 week (25% of 4 weeks).

void CkHttpW_getLogin(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putLogin(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_login(HCkHttpW cHandle);

The HTTP login 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.

HTTP Authentication (Basic, NTLM, Digest, Negotiate/Kerberos)

void CkHttpW_getLoginDomain(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putLoginDomain(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_loginDomain(HCkHttpW cHandle);

The optional domain name to be used with NTLM / Kerberos / Negotiate authentication.

int CkHttpW_getMaxConnections(HCkHttpW cHandle);

void CkHttpW_putMaxConnections(HCkHttpW cHandle, int newVal);

The maximum number of simultaneous open HTTP connections managed by the HTTP component. The Chilkat HTTP component automatically manages HTTP connections. If the number of open HTTP connections is about to be exceeded, the connection with the least recent activity is automatically closed.

int CkHttpW_getMaxFreshPeriod(HCkHttpW cHandle);

void CkHttpW_putMaxFreshPeriod(HCkHttpW cHandle, int newVal);

Limits the amount of time a document can be kept "fresh" in the cache. The MaxFreshPeriod is specified in minutes, and the default value is 525600 which is equal to 1 year.

unsigned long CkHttpW_getMaxResponseSize(HCkHttpW cHandle);

void CkHttpW_putMaxResponseSize(HCkHttpW cHandle, unsigned long newVal);

The maximum HTTP response size to be accepted by the calling program. A value of 0 (the default) indicates that there is no maximum value.

int CkHttpW_getMaxUrlLen(HCkHttpW cHandle);

void CkHttpW_putMaxUrlLen(HCkHttpW cHandle, int newVal);

The Http class will automatically fail any URL longer than this length. The default MaxUrlLen is 800 characters.

BOOL CkHttpW_getMimicFireFox(HCkHttpW cHandle);

void CkHttpW_putMimicFireFox(HCkHttpW cHandle, BOOL newVal);

If set to TRUE, then the appropriate headers to mimic Mozilla/FireFox are automatically added to requests sent via the QuickGet and QuickGetStr methods.

BOOL CkHttpW_getMimicIE(HCkHttpW cHandle);

void CkHttpW_putMimicIE(HCkHttpW cHandle, BOOL newVal);

If set to TRUE, then the appropriate headers to mimic Internet Explorer are automatically added to requests sent via the QuickGet and QuickGetStr methods.

int CkHttpW_getMinFreshPeriod(HCkHttpW cHandle);

void CkHttpW_putMinFreshPeriod(HCkHttpW cHandle, int newVal);

The freshness period for a document in cache will not be less than this value (in minutes). The default value is 30.

BOOL CkHttpW_getNegotiateAuth(HCkHttpW cHandle);

void CkHttpW_putNegotiateAuth(HCkHttpW cHandle, BOOL newVal);

Set this property equal to TRUE for Negotiate authentication. Negotiate authentication will dynamically select Kerberos or NTLM authentication depending on what the server requires.

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

HTTP Authentication (Basic, NTLM, Digest, Negotiate/Kerberos)

BOOL CkHttpW_getNtlmAuth(HCkHttpW cHandle);

void CkHttpW_putNtlmAuth(HCkHttpW cHandle, BOOL newVal);

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.

HTTP Authentication (Basic, NTLM, Digest, Negotiate/Kerberos)

int CkHttpW_getNumCacheLevels(HCkHttpW cHandle);

void CkHttpW_putNumCacheLevels(HCkHttpW cHandle, int newVal);

The number of directory levels to be used under each cache root. The default is 0, meaning that each cached HTML page is stored in a cache root directory. A value of 1 causes each cached page to be stored in one of 255 subdirectories named "0","1", "2", ..."255" under a cache root. A value of 2 causes two levels of subdirectories ("0..255/0..255") under each cache root. The HTTP control automatically creates subdirectories as needed. The reason for mutliple levels is to alleviate problems that may arise with unrelated software when huge numbers of files are stored in a single directory. For example, Windows Explorer does not behave well when trying to display the contents of directories with thousands of files.

int CkHttpW_getNumCacheRoots(HCkHttpW cHandle);

The number of cache roots to be used for the HTTP cache. This allows the disk cache spread out over multiple disk drives. Each cache root is a string indicating the drive letter and directory path. For example, "E:\Cache". An example of a very large low-cost cache might be four USB external drives. To create a cache with four roots, call AddCacheRoot once for each directory root.

BOOL CkHttpW_getOAuth1(HCkHttpW cHandle);

void CkHttpW_putOAuth1(HCkHttpW cHandle, BOOL newVal);

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.

Twitter OAuth -- Tweet to Your Own Account

Quickbooks OAuth1 Authorization (3-legged)

Twitter OAuth1 Authorization (3-legged)

Xero OAuth1 Authorization (3-legged)

void CkHttpW_getOAuthCallback(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putOAuthCallback(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_oAuthCallback(HCkHttpW cHandle);

Introduced in version 9.5.0.53

The OAuth 1.0 callback URL. Defaults to "oob".

void CkHttpW_getOAuthConsumerKey(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putOAuthConsumerKey(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_oAuthConsumerKey(HCkHttpW cHandle);

The OAuth consumer key to be used in the Authorization header.

void CkHttpW_getOAuthConsumerSecret(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putOAuthConsumerSecret(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_oAuthConsumerSecret(HCkHttpW cHandle);

The OAuth consumer secret to be used in computing the contents of the Authorization header.

void CkHttpW_getOAuthRealm(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putOAuthRealm(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_oAuthRealm(HCkHttpW cHandle);

The OAuth realm to be used in the Authorization header.

void CkHttpW_getOAuthSigMethod(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putOAuthSigMethod(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_oAuthSigMethod(HCkHttpW cHandle);

The OAuth signature method, such as "HMAC-SHA1" to be used in the Authorization header. The default is "HMAC-SHA1". It is also possible to choose "HMAC-SHA256", "RSA-SHA1" or "RSA-SHA2". For RSA algorithms, an RSA private key would need to be provided via the SetOAuthRsaKey method.

Note: RSA-SHA2 is supported starting in Chilkat v9.5.0.56

void CkHttpW_getOAuthToken(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putOAuthToken(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_oAuthToken(HCkHttpW cHandle);

The OAuth token to be used in the Authorization header.

Twitter OAuth -- Tweet to Your Own Account

void CkHttpW_getOAuthTokenSecret(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putOAuthTokenSecret(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_oAuthTokenSecret(HCkHttpW cHandle);

The OAuth token secret to be used in computing the Authorization header.

void CkHttpW_getOAuthVerifier(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putOAuthVerifier(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_oAuthVerifier(HCkHttpW cHandle);

The OAuth verifier to be used in the Authorization header.

void CkHttpW_getPassword(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putPassword(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_password(HCkHttpW cHandle);

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.

int CkHttpW_getPercentDoneScale(HCkHttpW cHandle);

void CkHttpW_putPercentDoneScale(HCkHttpW cHandle, int newVal);

Introduced in version 9.5.0.49

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.

BOOL CkHttpW_getPreferIpv6(HCkHttpW cHandle);

void CkHttpW_putPreferIpv6(HCkHttpW cHandle, BOOL newVal);

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.

void CkHttpW_getProxyAuthMethod(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putProxyAuthMethod(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_proxyAuthMethod(HCkHttpW cHandle);

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.

void CkHttpW_getProxyDomain(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putProxyDomain(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_proxyDomain(HCkHttpW cHandle);

The domain name of a proxy host if an HTTP proxy is used.

void CkHttpW_getProxyLogin(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putProxyLogin(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_proxyLogin(HCkHttpW cHandle);

If an HTTP proxy is used and it requires authentication, this property specifies the HTTP proxy login.

void CkHttpW_getProxyLoginDomain(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putProxyLoginDomain(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_proxyLoginDomain(HCkHttpW cHandle);

The NTLM authentication domain (optional) if NTLM authentication is used.

void CkHttpW_getProxyPassword(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putProxyPassword(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_proxyPassword(HCkHttpW cHandle);

If an HTTP proxy is used and it requires authentication, this property specifies the HTTP proxy password.

int CkHttpW_getProxyPort(HCkHttpW cHandle);

void CkHttpW_putProxyPort(HCkHttpW cHandle, int newVal);

The port number of a proxy server if an HTTP proxy is used.

int CkHttpW_getReadTimeout(HCkHttpW cHandle);

void CkHttpW_putReadTimeout(HCkHttpW cHandle, int newVal);

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 20 seconds.

void CkHttpW_getRedirectVerb(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putRedirectVerb(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_redirectVerb(HCkHttpW cHandle);

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.

void CkHttpW_getReferer(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putReferer(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_referer(HCkHttpW cHandle);

The Referer header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is the empty string which causes the Referer field to be omitted from the request header.

void CkHttpW_getRequiredContentType(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putRequiredContentType(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_requiredContentType(HCkHttpW cHandle);

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.

BOOL CkHttpW_getRequireSslCertVerify(HCkHttpW cHandle);

void CkHttpW_putRequireSslCertVerify(HCkHttpW cHandle, BOOL newVal);

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.

Require that the Web Server's SSL Certificate is Non-Expired and the Signature is Valid

BOOL CkHttpW_getS3Ssl(HCkHttpW cHandle);

void CkHttpW_putS3Ssl(HCkHttpW cHandle, BOOL newVal);

If TRUE, then all S3_* methods will use a secure SSL/TLS connection for communications. (If TRUE, Chilkat uses TLS 1.2) The default value is FALSE.

BOOL CkHttpW_getSaveCookies(HCkHttpW cHandle);

void CkHttpW_putSaveCookies(HCkHttpW cHandle, BOOL newVal);

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.

Caching cookies in-memory.

int CkHttpW_getSendBufferSize(HCkHttpW cHandle);

void CkHttpW_putSendBufferSize(HCkHttpW cHandle, int newVal);

The buffer size to be used with the underlying TCP/IP socket for sending. The default value is 65535.

BOOL CkHttpW_getSendCookies(HCkHttpW cHandle);

void CkHttpW_putSendCookies(HCkHttpW cHandle, BOOL newVal);

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.

Caching cookies in-memory.

void CkHttpW_getSessionLogFilename(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putSessionLogFilename(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_sessionLogFilename(HCkHttpW cHandle);

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.

Debugging HTTP

HTTP Session Logging

void CkHttpW_getSocksHostname(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putSocksHostname(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_socksHostname(HCkHttpW cHandle);

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

HTTP/HTTPS using SOCKS5 Proxy

HTTP/HTTPS using SOCKS4 Proxy

void CkHttpW_getSocksPassword(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putSocksPassword(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_socksPassword(HCkHttpW cHandle);

The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.

int CkHttpW_getSocksPort(HCkHttpW cHandle);

void CkHttpW_putSocksPort(HCkHttpW cHandle, int newVal);

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

void CkHttpW_getSocksUsername(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putSocksUsername(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_socksUsername(HCkHttpW cHandle);

The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).

HTTP/HTTPS using SOCKS5 Proxy

HTTP/HTTPS using SOCKS4 Proxy

int CkHttpW_getSocksVersion(HCkHttpW cHandle);

void CkHttpW_putSocksVersion(HCkHttpW cHandle, int newVal);

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.

HTTP/HTTPS using SOCKS5 Proxy

HTTP/HTTPS using SOCKS4 Proxy

int CkHttpW_getSoRcvBuf(HCkHttpW cHandle);

void CkHttpW_putSoRcvBuf(HCkHttpW cHandle, int newVal);

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.

More Information about TCP performance and Buffer Sizes

int CkHttpW_getSoSndBuf(HCkHttpW cHandle);

void CkHttpW_putSoSndBuf(HCkHttpW cHandle, int newVal);

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.

More Information about TCP performance and Buffer Sizes

void CkHttpW_getSslAllowedCiphers(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putSslAllowedCiphers(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_sslAllowedCiphers(HCkHttpW cHandle);

Introduced in version 9.5.0.48

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_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_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"

void CkHttpW_getSslProtocol(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putSslProtocol(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_sslProtocol(HCkHttpW cHandle);

Introduced in version 9.5.0.46

Selects the secure protocol to be used for secure (SSL/TLS) connections. Possible values are:

default
TLS 1.2
TLS 1.1
TLS 1.0
SSL 3.0
TLS 1.2 or higher
TLS 1.1 or higher
TLS 1.0 or higher
The default value is "default" which will choose the, 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".

void CkHttpW_getStreamResponseBodyPath(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putStreamResponseBodyPath(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_streamResponseBodyPath(HCkHttpW cHandle);

Introduced in version 9.5.0.49

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

void CkHttpW_getTlsCipherSuite(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_tlsCipherSuite(HCkHttpW cHandle);

Introduced in version 9.5.0.49

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.

void CkHttpW_getTlsPinSet(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putTlsPinSet(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_tlsPinSet(HCkHttpW cHandle);

Introduced in version 9.5.0.55

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.

Encodings Supported by Chilkat

HTTP Public Key Pinning

void CkHttpW_getTlsVersion(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_tlsVersion(HCkHttpW cHandle);

Introduced in version 9.5.0.49

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", and "TLS 1.2".

BOOL CkHttpW_getUpdateCache(HCkHttpW cHandle);

void CkHttpW_putUpdateCache(HCkHttpW cHandle, BOOL newVal);

Controls whether the cache is automatically updated with the responses from HTTP GET requests.

BOOL CkHttpW_getUseBgThread(HCkHttpW cHandle);

void CkHttpW_putUseBgThread(HCkHttpW cHandle, BOOL newVal);

This property is deprecated. It will be removed in a future version.

If TRUE, then background-enabled methods will run in a background thread. Normally, a method will return after its work is completed. However, when UseBgThread is true, the method will return immediately and a background thread is started to carry out the method's task.

Background-enabled HTTP methods are:

  • Download
  • DownloadAppend
  • GetHead
  • PostBinary
  • PostMime
  • PostUrlEncoded
  • PostXml
  • PutText
  • QuickDeleteStr
  • QuickGet
  • QuickGetObj
  • QuickGetStr
  • QuickPutStr
  • ResumeDownload
  • SynchronousRequest
  • XmlRpc
  • XmlRpcPut
  • This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

BOOL CkHttpW_getUseIEProxy(HCkHttpW cHandle);

void CkHttpW_putUseIEProxy(HCkHttpW cHandle, BOOL newVal);

If TRUE, the proxy host/port used by Internet Explorer will also be used by Chilkat HTTP.

void CkHttpW_getUserAgent(HCkHttpW cHandle, HCkString retval);

void CkHttpW_putUserAgent(HCkHttpW cHandle, const wchar_t *newVal);

const wchar_t *CkHttpW_userAgent(HCkHttpW cHandle);

The UserAgent header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "Mozilla/5.0 (Windows NT 6.3; WOW64; rv:49.0) Gecko/20100101 Firefox/49.0". The reason for this default is to get the same server behavior for a recent version of a typical and popular browser. Some sites may respond differently depending on the User-Agent, and the goal is to avoid strange responses that are different than what a typical browser would receive.

BOOL CkHttpW_getVerboseLogging(HCkHttpW cHandle);

void CkHttpW_putVerboseLogging(HCkHttpW cHandle, BOOL newVal);

If set to TRUE, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is FALSE. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

void CkHttpW_getVersion(HCkHttpW cHandle, HCkString retval);

const wchar_t *CkHttpW_version(HCkHttpW cHandle);

Version of the component/library, such as "9.5.0.63"

BOOL CkHttpW_getWasRedirected(HCkHttpW cHandle);

Indicates whether the last HTTP GET was redirected.

Methods

void CkHttpW_AddCacheRoot(HCkHttpW cHandle, const wchar_t *dir);

This method must be called at least once if disk caching is to be used. The file path (including drive letter) such as "E:\MyHttpCache\" is passed to AddCacheRoot to specify the root directory. The cache can be spread across multiple disk drives by calling AddCacheRoot multiple times, each with a directory path on a separate disk drive.

BOOL CkHttpW_AddQuickHeader(HCkHttpW cHandle, const wchar_t *headerFieldName, const wchar_t *headerFieldValue);

This method is deprecated. It will be removed in a future version.

Adds a custom header field to any HTTP request sent by a method that does not use the HTTP request object. These methods include Download, DownloadAppend, GetHead, PostBinary, PostMime, PostXml, PutBinary, PutText, QuickDeleteStr, QuickGet, QuickGetObj, QuickGetStr, QuickPutStr, XmlRpc, and XmlRpcPut.

Cookies may be explictly added by calling this method passing "Cookie" for the headerFieldName.

The RemoveQuickHeader method can be called to remove a custom header.

* Note: This method is deprecated. It is identical to the SetRequestHeader method. The SetRequestHeader method should be called instead because AddQuickHeader will be removed in a future version.

Returns TRUE for success, FALSE for failure.

Adding Cookies to an HTTP Request

HCkHttpResponseW CkHttpW_BgResponseObject(HCkHttpW cHandle);

This method is deprecated. It will be removed in a future version.

If a backgrounded method returns an Http response object, it may be retrieved by calling this method.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

Returns NULL on failure

void CkHttpW_BgTaskAbort(HCkHttpW cHandle);

This method is deprecated. It will be removed in a future version.

Call this to force the currently running backgrounded method to abort.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

void CkHttpW_ClearBgEventLog(HCkHttpW cHandle);

This method is deprecated. It will be removed in a future version.

Clears the in-memory event log (which is enabled by setting the KeepEventLog property = TRUE).

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

void CkHttpW_ClearInMemoryCookies(HCkHttpW cHandle);

Clears all cookies cached in memory. Calling this only makes sense if the CookieDir property is set to the string "memory".

void CkHttpW_ClearUrlVars(HCkHttpW cHandle);

Introduced in version 9.5.0.67

Clears all URL variable values previously set by one or more calls to SetUrlVar.

BOOL CkHttpW_CloseAllConnections(HCkHttpW cHandle);

Closes all connections still open from previous HTTP requests.

An HTTP object instance will maintain up to 10 connections. If the HTTP server's response does not include a "Connection: Close" header, the connection will remain open and will be re-used if possible for the next HTTP request to the same hostname:port. (It uses the IP address (in string form) or the domain name, whichever is used in the URL provided by the application.) If 10 connections are already open and another is needed, the object will close the least recently used connection.

Returns TRUE for success, FALSE for failure.

HCkTaskW CkHttpW_CloseAllConnectionsAsync(HCkHttpW cHandle);

Creates an asynchronous task to call the CloseAllConnections method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

void CkHttpW_DnsCacheClear(HCkHttpW cHandle);

Introduced in version 9.5.0.38

Clears the Chilkat-wide in-memory hostname-to-IP address DNS cache. Chilkat automatically maintains this in-memory cache to prevent redundant DNS lookups. If the TTL on the DNS A records being accessed are short and/or these DNS records change frequently, then this method can be called clear the internal cache. Note: The DNS cache is used/shared among all Chilkat objects in a program, and clearing the cache affects all Chilkat objects.

BOOL CkHttpW_Download(HCkHttpW cHandle, const wchar_t *url, const wchar_t *localFilePath);

Retrieves the content at a URL and saves to a file. All content is saved in streaming mode such that the memory footprint is small and steady. HTTPS is fully supported, as it is with all the methods of this class.

Returns TRUE for success, FALSE for failure.

HTTP Download any Type of File (binary or text)

Debugging HTTP

HCkTaskW CkHttpW_DownloadAsync(HCkHttpW cHandle, const wchar_t *url, const wchar_t *localFilePath);

Creates an asynchronous task to call the Download method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_DownloadAppend(HCkHttpW cHandle, const wchar_t *url, const wchar_t *filename);

Same as the Download method, but the output file is open for append.

Returns TRUE for success, FALSE for failure.

HCkTaskW CkHttpW_DownloadAppendAsync(HCkHttpW cHandle, const wchar_t *url, const wchar_t *filename);

Creates an asynchronous task to call the DownloadAppend method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_DownloadBd(HCkHttpW cHandle, const wchar_t *url, HCkBinDataW binData);

Introduced in version 9.5.0.63

Downloads the content at the url into a BinData object.

Returns TRUE for success, FALSE for failure.

Upload In-Memory Binary Data to Google Cloud Storage

HCkTaskW CkHttpW_DownloadBdAsync(HCkHttpW cHandle, const wchar_t *url, HCkBinDataW binData);

Introduced in version 9.5.0.63

Creates an asynchronous task to call the DownloadBd method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_DownloadHash(HCkHttpW cHandle, const wchar_t *url, const wchar_t *hashAlgorithm, const wchar_t *encoding, const wchar_t *outStr);

const wchar_t *CkHttpW_downloadHash(HCkHttpW cHandle, const wchar_t *url, const wchar_t *hashAlgorithm, const wchar_t *encoding);

Retrieves the content at a URL and computes and returns a hash of the content. The hash is returned as an encoded string according to the encoding, which may be "Base64", "modBase64", "Base32", "UU", "QP" (for quoted-printable), "URL" (for url-encoding), "Hex", "Q", "B", "url_oath", "url_rfc1738", "url_rfc2396", and "url_rfc3986". The hashAlgorithm may be "sha1", "sha256", "sha384", "sha512", "md2", "md5", "haval", "ripemd128", "ripemd160","ripemd256", or "ripemd320".

Returns TRUE for success, FALSE for failure.

HCkTaskW CkHttpW_DownloadHashAsync(HCkHttpW cHandle, const wchar_t *url, const wchar_t *hashAlgorithm, const wchar_t *encoding);

Creates an asynchronous task to call the DownloadHash method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_DownloadSb(HCkHttpW cHandle, const wchar_t *url, const wchar_t *charset, HCkStringBuilderW sb);

Introduced in version 9.5.0.63

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.

Returns TRUE for success, FALSE for failure.

HCkTaskW CkHttpW_DownloadSbAsync(HCkHttpW cHandle, const wchar_t *url, const wchar_t *charset, HCkStringBuilderW sb);

Introduced in version 9.5.0.63

Creates an asynchronous task to call the DownloadSb method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_EventLogName(HCkHttpW cHandle, int index, const wchar_t *outStr);

const wchar_t *CkHttpW_eventLogName(HCkHttpW cHandle, int index);

This method is deprecated. It will be removed in a future version.

Returns the name of the Nth event in the in-memory event log. Refer to the documentation for the KeepEventLog property for the full list of event names. Indexing is from 0 to EventLogCount-1.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_EventLogValue(HCkHttpW cHandle, int index, const wchar_t *outStr);

const wchar_t *CkHttpW_eventLogValue(HCkHttpW cHandle, int index);

This method is deprecated. It will be removed in a future version.

Returns the value of the Nth event in the in-memory event log. Indexing is from 0 to EventLogCount-1.

This functionality is replaced by the new model for asynchronous programming introduced in Chilkat v9.5.0.52. Applications should use the new model, which is identified by methods having names ending with "Async" and return a task object.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_ExtractMetaRefreshUrl(HCkHttpW cHandle, const wchar_t *htmlContent, const wchar_t *outStr);

const wchar_t *CkHttpW_extractMetaRefreshUrl(HCkHttpW cHandle, const wchar_t *htmlContent);

Convenience method for extracting the META refresh URL from HTML. For example, if the htmlContent contains a META refresh tag, such as:

<meta http-equiv="refresh" content="5;URL='http://example.com/'">
Then the return value of this method would be "http://example.com/".

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_G_SvcOauthAccessToken(HCkHttpW cHandle, const wchar_t *iss, const wchar_t *scope, const wchar_t *subEmail, int numSec, HCkCertW cert, const wchar_t *outStr);

const wchar_t *CkHttpW_g_SvcOauthAccessToken(HCkHttpW cHandle, const wchar_t *iss, const wchar_t *scope, const wchar_t *subEmail, int numSec, HCkCertW cert);

Introduced in version 9.5.0.44

Makes an access token request to obtain a Google API OAuth2 access token for a service account. Access tokens issued by the Google OAuth 2.0 Authorization Server expire one hour after they are issued. When an access token expires, then the application should generate another JWT, sign it, and request another access token. The iss is the service account email address of the application making the access token request. The scope is a space-delimited list of the permissions that the application requests. (See https://developers.google.com/accounts/docs/OAuth2ServiceAccount )

The subEmail is the email address of the user for which the application is requesting delegated access. The subEmail may be left empty if there is no such email address.

Returns TRUE for success, FALSE for failure.

Get XOAUTH2 Access Token from Google OAuth 2.0 Authorization Server

HCkTaskW CkHttpW_G_SvcOauthAccessTokenAsync(HCkHttpW cHandle, const wchar_t *iss, const wchar_t *scope, const wchar_t *subEmail, int numSec, HCkCertW cert);

Introduced in version 9.5.0.44

Creates an asynchronous task to call the G_SvcOauthAccessToken method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_G_SvcOauthAccessToken2(HCkHttpW cHandle, HCkHashtableW claimParams, int numSec, HCkCertW cert, const wchar_t *outStr);

const wchar_t *CkHttpW_g_SvcOauthAccessToken2(HCkHttpW cHandle, HCkHashtableW claimParams, int numSec, HCkCertW cert);

Introduced in version 9.5.0.51

The same as the G_SvcOauthAccessToken method, but with added flexibility for more customization. The 1st three args of the G_SvcOauthAccessToken are replaced with claimParams allowing for future expansion of name-value params. See the example below.

Returns TRUE for success, FALSE for failure.

Get OAuth 2.0 Access Token using G_SvcOauthAccessToken2

HCkTaskW CkHttpW_G_SvcOauthAccessToken2Async(HCkHttpW cHandle, HCkHashtableW claimParams, int numSec, HCkCertW cert);

Introduced in version 9.5.0.51

Creates an asynchronous task to call the G_SvcOauthAccessToken2 method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_GenTimeStamp(HCkHttpW cHandle, const wchar_t *outStr);

const wchar_t *CkHttpW_genTimeStamp(HCkHttpW cHandle);

Returns the current GMT (also known as UTC) date/time in a string that is compliant with RFC 2616 format.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_GetCacheRoot(HCkHttpW cHandle, int index, const wchar_t *outStr);

const wchar_t *CkHttpW_getCacheRoot(HCkHttpW cHandle, int index);

Returns the Nth cache root (indexing begins at 0). Cache roots are set by calling AddCacheRoot one or more times.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_GetCookieXml(HCkHttpW cHandle, const wchar_t *domain, const wchar_t *outStr);

const wchar_t *CkHttpW_getCookieXml(HCkHttpW cHandle, const wchar_t *domain);

Returns the cookies in XML format for a specific domain. Cookies are only persisted if the SaveCookies property is set to TRUE. If the CookieDir property is set to the keyword "memory", then cookies are saved in-memory.

Returns TRUE for success, FALSE for failure.

Demonstrates how to Get Cookies Sent by the HTTP Server

BOOL CkHttpW_GetDomain(HCkHttpW cHandle, const wchar_t *url, const wchar_t *outStr);

const wchar_t *CkHttpW_getDomain(HCkHttpW cHandle, const wchar_t *url);

Utility method for extracting the domain name from a full URL. For example, if "http://www.chilkatsoft.com/default.asp" is the URL passed in, then "www.chilkatsoft.com" is returned.

Returns TRUE for success, FALSE for failure.

HCkHttpResponseW CkHttpW_GetHead(HCkHttpW cHandle, const wchar_t *url);

Sends an HTTP HEAD request for a URL and returns a response object. (Note: HEAD requests will never automatically follow redirects.)

Returns NULL on failure

HTTP HEAD Request

HCkTaskW CkHttpW_GetHeadAsync(HCkHttpW cHandle, const wchar_t *url);

Creates an asynchronous task to call the GetHead method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

BOOL CkHttpW_GetRequestHeader(HCkHttpW cHandle, const wchar_t *name, const wchar_t *outStr);

const wchar_t *CkHttpW_getRequestHeader(HCkHttpW cHandle, const wchar_t *name);

Returns the value of a header field that has been pre-defined to be sent with all HTTP GET requests issued by the QuickGet and QuickGetStr methods. By default, this includes header fields such as Accept, AcceptCharset, AcceptLanguage, Connection, UserAgent, etc.

Returns TRUE for success, FALSE for failure.

HCkCertW CkHttpW_GetServerSslCert(HCkHttpW cHandle, const wchar_t *domain, int port);

Establishes an SSL/TLS connection with a web server for the purpose of retrieving the server's SSL certificate (public-key only of course...). Nothing is retrieved from the web server. This method simply makes a connection, gets the certificate information, and closes the connection.

Returns NULL on failure

Get the Server Certificate, Certificate Chain, and Root CA Certificate

Get Web Server's SPKI Fingerprint

HCkTaskW CkHttpW_GetServerSslCertAsync(HCkHttpW cHandle, const wchar_t *domain, int port);

Creates an asynchronous task to call the GetServerSslCert method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

BOOL CkHttpW_GetUrlPath(HCkHttpW cHandle, const wchar_t *url, const wchar_t *outStr);

const wchar_t *CkHttpW_getUrlPath(HCkHttpW cHandle, const wchar_t *url);

Returns the path part of a URL. The syntax of a URL is <scheme>://<user>:<password>@<host>:<port>/<path>;<params>?<query>#<frag>. This method returns the "path" part.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_HasRequestHeader(HCkHttpW cHandle, const wchar_t *name);

Returns true if the specified header field is defined such that it will be sent with all GET requests issued by the QuickGet and QuickGetStr methods.

BOOL CkHttpW_IsUnlocked(HCkHttpW cHandle);

Returns true if the Http class has been unlocked. It is necessary to call Http.UnlockComponent before calling any other methods. Passing any string to UnlockComponent will automatically activate a 30-day trial period.

HCkHttpResponseW CkHttpW_PBinary(HCkHttpW cHandle, const wchar_t *verb, const wchar_t *url, const unsigned char * byteData, const wchar_t *contentType, BOOL md5, BOOL gzip);

Introduced in version 9.5.0.45

Sends an HTTP request to the url. The verb can be "POST", "PUT", "PATCH", etc. The body of the HTTP request contains the bytes passed in byteData. The contentType is a content type such as "image/gif", "application/pdf", etc. If md5 is TRUE, then a Content-MD5 header is added with the base64 MD5 hash of the byteData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is TRUE, the byteData is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

Returns NULL on failure

HCkTaskW CkHttpW_PBinaryAsync(HCkHttpW cHandle, const wchar_t *verb, const wchar_t *url, const unsigned char * byteData, const wchar_t *contentType, BOOL md5, BOOL gzip);

Introduced in version 9.5.0.45

Creates an asynchronous task to call the PBinary method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

HCkHttpResponseW CkHttpW_PBinaryBd(HCkHttpW cHandle, const wchar_t *verb, const wchar_t *url, HCkBinDataW data, const wchar_t *contentType, BOOL md5, BOOL gzip);

Introduced in version 9.5.0.69

The same as PBinary, but the data to be uploaded is passed in data.

Returns NULL on failure

Upload In-Memory Binary Data to Google Cloud Storage

HCkTaskW CkHttpW_PBinaryBdAsync(HCkHttpW cHandle, const wchar_t *verb, const wchar_t *url, HCkBinDataW data, const wchar_t *contentType, BOOL md5, BOOL gzip);

Introduced in version 9.5.0.69

Creates an asynchronous task to call the PBinaryBd method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

BOOL CkHttpW_PostBinary(HCkHttpW cHandle, const wchar_t *url, const unsigned char * byteData, const wchar_t *contentType, BOOL md5, BOOL gzip, const wchar_t *outStr);

const wchar_t *CkHttpW_postBinary(HCkHttpW cHandle, const wchar_t *url, const unsigned char * byteData, const wchar_t *contentType, BOOL md5, BOOL gzip);

Sends an HTTP POST request to the url. The body of the HTTP request contains the bytes passed in byteData. The contentType is a content type such as "image/gif", "application/pdf", etc. If md5 is TRUE, then a Content-MD5 header is added with the base64 MD5 hash of the byteData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is TRUE, the byteData is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

Returns the text body of the HTTP response if the HTTP response has a success status code. Otherwise the method is considered to have failed. If more details of the HTTP response are required, call PBinary instead (which returns the HTTP response object).

Note: The HTTP response code is available in the LastStatus property. Other properties having information include LastResponseHeader, LastResponseBody, LastModDate, LastContentType, etc.

Returns TRUE for success, FALSE for failure.

HCkTaskW CkHttpW_PostBinaryAsync(HCkHttpW cHandle, const wchar_t *url, const unsigned char * byteData, const wchar_t *contentType, BOOL md5, BOOL gzip);

Creates an asynchronous task to call the PostBinary method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

HCkHttpResponseW CkHttpW_PostJson(HCkHttpW cHandle, const wchar_t *url, const wchar_t *jsonText);

A simplified way of sending a JSON POST and receiving the JSON response. The HTTP response is returned in an HTTP response object. The content type of the HTTP request is "applicatoin/jsonrequest". To send a JSON POST using "application/json", call the PostJson2 method where the content type can be explicitly provided.

Returns NULL on failure

HTTP POST JSON

HCkTaskW CkHttpW_PostJsonAsync(HCkHttpW cHandle, const wchar_t *url, const wchar_t *jsonText);

Creates an asynchronous task to call the PostJson method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

HCkHttpResponseW CkHttpW_PostJson2(HCkHttpW cHandle, const wchar_t *url, const wchar_t *contentType, const wchar_t *jsonText);

The same as PostJson,except it allows for the content type to be explicitly provided. The PostJson method automatically uses "application/jsonrequest". If the application needs for the content type to be "application/json", or some other content type, then PostJson2 provides the means.

Returns NULL on failure

HTTP POST JSON (application/json)

HCkTaskW CkHttpW_PostJson2Async(HCkHttpW cHandle, const wchar_t *url, const wchar_t *contentType, const wchar_t *jsonText);

Creates an asynchronous task to call the PostJson2 method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

HCkHttpResponseW CkHttpW_PostJson3(HCkHttpW cHandle, const wchar_t *url, const wchar_t *contentType, HCkJsonObjectW json);

Introduced in version 9.5.0.68

The same as PostJson2,except a JSON object is passed in for the request body.

Returns NULL on failure

Auth0 Server-to-Server Access Token (Client Credentials flow)

HCkTaskW CkHttpW_PostJson3Async(HCkHttpW cHandle, const wchar_t *url, const wchar_t *contentType, HCkJsonObjectW json);

Introduced in version 9.5.0.68

Creates an asynchronous task to call the PostJson3 method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

HCkHttpResponseW CkHttpW_PostUrlEncoded(HCkHttpW cHandle, const wchar_t *url, HCkHttpRequestW req);

Sends a simple URL encoded POST. The form parameters are sent in the body of the HTTP request in x-www-form-urlencoded format. The content-type is "application/x-www-form-urlencoded".

Returns NULL on failure

Duplicating a Simple HTML Form Submission (POST)

HTTP POST x-www-form-urlencoded

Debugging HTTP

PostUrlEncoded Clarified

HCkTaskW CkHttpW_PostUrlEncodedAsync(HCkHttpW cHandle, const wchar_t *url, HCkHttpRequestW req);

Creates an asynchronous task to call the PostUrlEncoded method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

HCkHttpResponseW CkHttpW_PostXml(HCkHttpW cHandle, const wchar_t *endpointUrl, const wchar_t *xmlContent, const wchar_t *xmlCharset);

A simplified way of posting XML content to a web server. This method is good for making SOAP calls using HTTP POST. The xmlCharset should match the character encoding used in the xmlContent, which is typically "utf-8". The HTTP response is returned in an HTTP response object.

Important: This method sends the POST with a "Content-Type" header value of "text/xml". Sometimes a server might require the Content-Type header to be "application/xml". To use "application/xml" instead of the default "text/xml", call SetRequestHeader("Content-Type","application/xml") prior to calling this method.

To use HTTPS simply pass an endpointUrl beginning with "https://" instead of "http://". This applies to any Chilkat method where a URL is passed as an argument.

Returns NULL on failure

Send XMLHttpRequest and Get Response

Calling a SOAP Web Service using PostXml

Debugging HTTP

Send SOAP 1.2 Request to Web Service Requiring Authentication

HCkTaskW CkHttpW_PostXmlAsync(HCkHttpW cHandle, const wchar_t *endpointUrl, const wchar_t *xmlContent, const wchar_t *xmlCharset);

Creates an asynchronous task to call the PostXml method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

HCkHttpResponseW CkHttpW_PText(HCkHttpW cHandle, const wchar_t *verb, const wchar_t *url, const wchar_t *textData, const wchar_t *charset, const wchar_t *contentType, BOOL md5, BOOL gzip);

Introduced in version 9.5.0.46

Sends an HTTP request to the url. The verb can be "POST", "PUT", "PATCH", etc. The body of the HTTP request contains the text passed in textData. The contentType is a content type such as "text/xml", "application/json", etc. If md5 is TRUE, then a Content-MD5 header is added with the base64 MD5 hash of the textData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is TRUE, the contentType is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

Returns NULL on failure

HCkTaskW CkHttpW_PTextAsync(HCkHttpW cHandle, const wchar_t *verb, const wchar_t *url, const wchar_t *textData, const wchar_t *charset, const wchar_t *contentType, BOOL md5, BOOL gzip);

Introduced in version 9.5.0.46

Creates an asynchronous task to call the PText method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

HCkHttpResponseW CkHttpW_PTextSb(HCkHttpW cHandle, const wchar_t *verb, const wchar_t *url, HCkStringBuilderW textData, const wchar_t *charset, const wchar_t *contentType, BOOL md5, BOOL gzip);

Introduced in version 9.5.0.69

The same as PText, but the data to be uploaded is passed in textData.

Returns NULL on failure

Upload String to Google Cloud Storage

HCkTaskW CkHttpW_PTextSbAsync(HCkHttpW cHandle, const wchar_t *verb, const wchar_t *url, HCkStringBuilderW textData, const wchar_t *charset, const wchar_t *contentType, BOOL md5, BOOL gzip);

Introduced in version 9.5.0.69

Creates an asynchronous task to call the PTextSb method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

BOOL CkHttpW_PutBinary(HCkHttpW cHandle, const wchar_t *url, const unsigned char * byteData, const wchar_t *contentType, BOOL md5, BOOL gzip, const wchar_t *outStr);

const wchar_t *CkHttpW_putBinary(HCkHttpW cHandle, const wchar_t *url, const unsigned char * byteData, const wchar_t *contentType, BOOL md5, BOOL gzip);

Sends an HTTP PUT request to the url. The body of the HTTP request is byteData. The contentType is a content type such as "image/gif", "application/pdf", etc. If md5 is TRUE, then a Content-MD5 header is added with the base64 MD5 hash of the byteData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is TRUE, the byteData is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

Returns the text body of the HTTP response if the HTTP response has a success status code. Otherwise the method is considered to have failed. If more details of the HTTP response are required, call PBinary instead (which returns the HTTP response object).

Returns TRUE for success, FALSE for failure.

HCkTaskW CkHttpW_PutBinaryAsync(HCkHttpW cHandle, const wchar_t *url, const unsigned char * byteData, const wchar_t *contentType, BOOL md5, BOOL gzip);

Creates an asynchronous task to call the PutBinary method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_PutText(HCkHttpW cHandle, const wchar_t *url, const wchar_t *textData, const wchar_t *charset, const wchar_t *contentType, BOOL md5, BOOL gzip, const wchar_t *outStr);

const wchar_t *CkHttpW_putText(HCkHttpW cHandle, const wchar_t *url, const wchar_t *textData, const wchar_t *charset, const wchar_t *contentType, BOOL md5, BOOL gzip);

Sends an HTTP PUT request to the url. The body of the HTTP request is textData. The charset should be set to a charset name such as "iso-8859-1", "windows-1252", "Shift_JIS", "utf-8", etc. The string "ansi" may also be used as a charset name. The contentType is a content type such as "text/plain", "text/xml", etc. If md5 is TRUE, then a Content-MD5 header is added with the base64 MD5 hash of the textData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is TRUE, the textData is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

Returns the text body of the HTTP response if the HTTP response has a success status code. Otherwise the method is considered to have failed. If more details of the HTTP response are required, call PText instead (which returns the HTTP response object).

Returns TRUE for success, FALSE for failure.

HTTP PUT JSON

HCkTaskW CkHttpW_PutTextAsync(HCkHttpW cHandle, const wchar_t *url, const wchar_t *textData, const wchar_t *charset, const wchar_t *contentType, BOOL md5, BOOL gzip);

Creates an asynchronous task to call the PutText method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_QuickDeleteStr(HCkHttpW cHandle, const wchar_t *url, const wchar_t *outStr);

const wchar_t *CkHttpW_quickDeleteStr(HCkHttpW cHandle, const wchar_t *url);

Same as QuickGetStr, but uses the HTTP DELETE method instead of the GET method.

Note: The HTTP response code is available in the LastStatus property. Other properties having information include LastResponseHeader, LastResponseBody, LastModDate, LastContentType, etc.

Returns TRUE for success, FALSE for failure.

Debugging HTTP

HCkTaskW CkHttpW_QuickDeleteStrAsync(HCkHttpW cHandle, const wchar_t *url);

Creates an asynchronous task to call the QuickDeleteStr method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_QuickGet(HCkHttpW cHandle, const wchar_t *url, const unsigned char * outData);

Sends an HTTP GET request for a URL and returns the response body as a byte array. The URL may contain query parameters. If the SendCookies property is true, matching cookies previously persisted to the CookiesDir are automatically included in the request. If the FetchFromCache property is true, the page may be fetched directly from cache. Because the URL can specify any type of resource (HTML page, GIF image, etc.) the return value is a byte array. If the resource is known to be a string, such as with an HTML page, you may call QuickGetStr instead. If the HTTP request fails, a zero-length byte array is returned and error information can be found in the LastErrorText, LastErrorXml, or LastErrorHtml properties.

Note: The HTTP response code is available in the LastStatus property. Other properties having information include LastResponseHeader, LastResponseBody, LastModDate, LastContentType, etc.

Returns TRUE for success, FALSE for failure.

Facebook Download all Photos to Local Files

Download a Zip from a URL and OpenFromMemory. (No .zip fie is created)

HCkTaskW CkHttpW_QuickGetAsync(HCkHttpW cHandle, const wchar_t *url);

Creates an asynchronous task to call the QuickGet method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_QuickGetBd(HCkHttpW cHandle, const wchar_t *url, HCkBinDataW binData);

Introduced in version 9.5.0.64

The same as QuickGet, but returns the content in a Chilkat BinData object. The existing content of binData, if any, is cleared and replaced with the downloaded content.

Returns TRUE for success, FALSE for failure.

Create Enveloping XML Digital Signature

HCkTaskW CkHttpW_QuickGetBdAsync(HCkHttpW cHandle, const wchar_t *url, HCkBinDataW binData);

Introduced in version 9.5.0.64

Creates an asynchronous task to call the QuickGetBd method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

HCkHttpResponseW CkHttpW_QuickGetObj(HCkHttpW cHandle, const wchar_t *url);

Sends an HTTP GET request for a URL and returns the response object. If the SendCookies property is TRUE, matching cookies previously persisted to the CookiesDir are automatically included in the request. If the FetchFromCache property is TRUE, the page could be fetched directly from cache.

Returns NULL on failure

Getting the HTTP Response after an Asynchronous HTTP Request Completes

HCkTaskW CkHttpW_QuickGetObjAsync(HCkHttpW cHandle, const wchar_t *url);

Creates an asynchronous task to call the QuickGetObj method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

BOOL CkHttpW_QuickGetSb(HCkHttpW cHandle, const wchar_t *url, HCkStringBuilderW sbContent);

Introduced in version 9.5.0.64

The same as QuickGetStr, but returns the content in a Chilkat StringBuilder object. The existing content of sbContent, if any, is cleared and replaced with the downloaded content.

Returns TRUE for success, FALSE for failure.

HCkTaskW CkHttpW_QuickGetSbAsync(HCkHttpW cHandle, const wchar_t *url, HCkStringBuilderW sbContent);

Introduced in version 9.5.0.64

Creates an asynchronous task to call the QuickGetSb method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_QuickGetStr(HCkHttpW cHandle, const wchar_t *url, const wchar_t *outStr);

const wchar_t *CkHttpW_quickGetStr(HCkHttpW cHandle, const wchar_t *url);

Sends an HTTP GET request for a URL and returns the response body as a string. The URL may contain query parameters. If the SendCookies property is TRUE, matching cookies previously persisted to the CookiesDir are automatically included in the request. If the FetchFromCache property is TRUE, the page could be fetched directly from cache. If the HTTP request fails, a NULL value is returned and error information can be found in the LastErrorText, LastErrorXml, or LastErrorHtml properties.

Note: The HTTP response code is available in the LastStatus property. Other properties having information include LastResponseHeader, LastResponseBody, LastModDate, LastContentType, etc.

Returns TRUE for success, FALSE for failure.

HTTP GET - Download HTML or any Text Content to a String

HTTPS GET using SSL/TLS

HCkTaskW CkHttpW_QuickGetStrAsync(HCkHttpW cHandle, const wchar_t *url);

Creates an asynchronous task to call the QuickGetStr method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_QuickPutStr(HCkHttpW cHandle, const wchar_t *url, const wchar_t *outStr);

const wchar_t *CkHttpW_quickPutStr(HCkHttpW cHandle, const wchar_t *url);

Same as QuickGetStr, but uses the HTTP PUT method instead of the GET method.

Note: The HTTP response code is available in the LastStatus property. Other properties having information include LastResponseHeader, LastResponseBody, LastModDate, LastContentType, etc.

Returns TRUE for success, FALSE for failure.

Debugging HTTP

HCkTaskW CkHttpW_QuickPutStrAsync(HCkHttpW cHandle, const wchar_t *url);

Creates an asynchronous task to call the QuickPutStr method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_RemoveQuickHeader(HCkHttpW cHandle, const wchar_t *headerFieldName);

Removes a header from the internal list of custom header field name/value pairs to be automatically added when HTTP requests are sent via methods that do not use the HTTP request object. (The AddQuickHeader method is called to add custom header fields.)

* Note: This method is deprecated. It is identical to the RemoveRequestHeader method. The RemoveRequestHeader method should be called instead because this method will be removed in a future version.

Returns TRUE for success, FALSE for failure.

void CkHttpW_RemoveRequestHeader(HCkHttpW cHandle, const wchar_t *name);

Removes a header from the internal list of custom header field name/value pairs to be automatically added when HTTP requests are sent via methods that do not use the HTTP request object. (The SetRequestHeader method is called to add custom header fields.)

BOOL CkHttpW_RenderGet(HCkHttpW cHandle, const wchar_t *url, const wchar_t *outStr);

const wchar_t *CkHttpW_renderGet(HCkHttpW cHandle, const wchar_t *url);

Same as QuickGet, but does not send the HTTP GET. Instead, it builds the HTTP request that would've been sent and returns it.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_ResumeDownload(HCkHttpW cHandle, const wchar_t *url, const wchar_t *targetFilename);

Same as the Download method, except a failed download may be resumed. The targetFilename is automatically checked and if it exists, the download will resume at the point where it previously failed. ResumeDownload may be called any number of times until the full download is complete.

Returns TRUE for success, FALSE for failure.

HCkTaskW CkHttpW_ResumeDownloadAsync(HCkHttpW cHandle, const wchar_t *url, const wchar_t *targetFilename);

Creates an asynchronous task to call the ResumeDownload method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_CreateBucket(HCkHttpW cHandle, const wchar_t *bucketPath);

Creates a new Amazon S3 bucket.

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

Returns TRUE for success, FALSE for failure.

S3 Create Bucket Example

HCkTaskW CkHttpW_S3_CreateBucketAsync(HCkHttpW cHandle, const wchar_t *bucketPath);

Creates an asynchronous task to call the S3_CreateBucket method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_DeleteBucket(HCkHttpW cHandle, const wchar_t *bucketPath);

Deletes an Amazon S3 bucket.

Returns TRUE for success, FALSE for failure.

S3 Delete Bucket

HCkTaskW CkHttpW_S3_DeleteBucketAsync(HCkHttpW cHandle, const wchar_t *bucketPath);

Creates an asynchronous task to call the S3_DeleteBucket method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

HCkHttpResponseW CkHttpW_S3_DeleteMultipleObjects(HCkHttpW cHandle, const wchar_t *bucketName, HCkStringArrayW objectNames);

Introduced in version 9.5.0.47

Deletes multiple objects from a bucket using a single HTTP request. The bucketName contains the names (also known as "keys") of the objects to be deleted. To delete a specific version of an object, append a versionId attribute to the object name. For example: "SampleDocument.txt; VersionId="OYcLXagmS.WaD..oyH4KRguB95_YhLs7""

Returns NULL on failure

Delete Multiple Objects Example

HCkTaskW CkHttpW_S3_DeleteMultipleObjectsAsync(HCkHttpW cHandle, const wchar_t *bucketName, HCkStringArrayW objectNames);

Introduced in version 9.5.0.47

Creates an asynchronous task to call the S3_DeleteMultipleObjects method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

How to Return an Object from an Async Task

BOOL CkHttpW_S3_DeleteObject(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName);

Deletes a remote file (object) on the Amazon S3 service.

Returns TRUE for success, FALSE for failure.

S3 Delete File

HCkTaskW CkHttpW_S3_DeleteObjectAsync(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName);

Creates an asynchronous task to call the S3_DeleteObject method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_DownloadBytes(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName, const unsigned char * outBytes);

The same as DownloadFile, except the file data is returned directly in-memory instead of being written to a local file.

Returns TRUE for success, FALSE for failure.

Demonstrate S3_DownloadBytes

HCkTaskW CkHttpW_S3_DownloadBytesAsync(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName);

Creates an asynchronous task to call the S3_DownloadBytes method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_DownloadFile(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName, const wchar_t *localFilePath);

Downloads a file from the Amazon S3 service.

Returns TRUE for success, FALSE for failure.

S3 Download File Example

HCkTaskW CkHttpW_S3_DownloadFileAsync(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName, const wchar_t *localFilePath);

Creates an asynchronous task to call the S3_DownloadFile method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_DownloadString(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName, const wchar_t *charset, const wchar_t *outStr);

const wchar_t *CkHttpW_s3_DownloadString(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName, const wchar_t *charset);

Downloads a text file (object) from the Amazon S3 service directly into a string variable. The charset specifies the character encoding, such as "utf-8", of the remote text object.

Returns TRUE for success, FALSE for failure.

S3 Download String Object

HCkTaskW CkHttpW_S3_DownloadStringAsync(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName, const wchar_t *charset);

Creates an asynchronous task to call the S3_DownloadString method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

int CkHttpW_S3_FileExists(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName);

Determines if a remote object (file) exists. Returns 1 if the file exists, 0 if it does not exist, -1 if there was a failure in checking, or 2 if using in asynchronous mode to indicate that the background task was successfully started.

Read S3 Object Metadata of File Already Uploaded to S3

HCkTaskW CkHttpW_S3_FileExistsAsync(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *objectName);

Creates an asynchronous task to call the S3_FileExists method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_GenerateUrl(HCkHttpW cHandle, const wchar_t *bucket, const wchar_t *path, HCkDateTimeW expire, const wchar_t *outStr);

const wchar_t *CkHttpW_s3_GenerateUrl(HCkHttpW cHandle, const wchar_t *bucket, const wchar_t *path, HCkDateTimeW expire);

Introduced in version 9.5.0.46

Generates a temporary pre-signed URL for Amazon S3 using AWS Signature V2. (Call S3_GenerateUrlV4 to generate AWS Signature V4 pre-signed URLs.) Requires that the AwsSecretKey and AwsAccessKey be set to valid values prior to calling this method.

Note: This method can only generate URLs that are for HTTP GET requests (i.e. URLs you can paste into a browser address bar). This method does not generate URLs for POST, PUT, DELETE, etc.

Returns TRUE for success, FALSE for failure.

Generate S3 Signed URL

BOOL CkHttpW_S3_GenerateUrlV4(HCkHttpW cHandle, BOOL useHttps, const wchar_t *bucketName, const wchar_t *path, int numSecondsValid, const wchar_t *awsService, const wchar_t *outStr);

const wchar_t *CkHttpW_s3_GenerateUrlV4(HCkHttpW cHandle, BOOL useHttps, const wchar_t *bucketName, const wchar_t *path, int numSecondsValid, const wchar_t *awsService);

Introduced in version 9.5.0.66

Generates a temporary pre-signed URL for Amazon S3 using AWS Signature V4. (Call S3_GenerateUrl to generate AWS Signature V2 pre-signed URLs.) Requires that the AwsSecretKey, AwsAccessKey, and AwsRegion properties be set to valid values prior to calling this method. Also requires the AwsEndpoint property to be set if the endpoint is different than "s3.amazonaws.com".

The URL that is generated has this format:

https:////
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=////aws4_request
&X-Amz-Date=
&X-Amz-Expires=
&X-Amz-SignedHeaders=host
&X-Amz-Signature=  

The awsService is a string naming the AWS service, such as "s3". If useHttps is TRUE, then the URL begins with "https://", otherwise it begins with "http://".

Note: This method can only generate URLs that are for HTTP GET requests (i.e. URLs you can paste into a browser address bar). This method does not generate URLs for POST, PUT, DELETE, etc.

Returns TRUE for success, FALSE for failure.

Generate an AWS (S3) Pre-Signed URL using Signature V4

BOOL CkHttpW_S3_ListBucketObjects(HCkHttpW cHandle, const wchar_t *bucketPath, const wchar_t *outStr);

const wchar_t *CkHttpW_s3_ListBucketObjects(HCkHttpW cHandle, const wchar_t *bucketPath);

Retrieves the XML listing of the objects contained within an Amazon S3 bucket. (This is like a directory listing, but in XML format.)

The bucketPath name may be qualified with URL-encoded params. For example, to list the objects in a bucket named "ChilkatABC" with max-keys = 2000 and marker = "xyz", call S3_ListBucketObject passing the following string for bucketPath: "ChilkatABC?max-keys=2000&marker=xyz"

The S3_ListBucketObjects method recognized all params listed in the AWS documentation for listing objects in a bucket: delimiter, marker, max-keys, and prefix. See Amazon's AWS online documentation for more information.

Returns TRUE for success, FALSE for failure.

S3 List Objects in Bucket

HCkTaskW CkHttpW_S3_ListBucketObjectsAsync(HCkHttpW cHandle, const wchar_t *bucketPath);

Creates an asynchronous task to call the S3_ListBucketObjects method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_ListBuckets(HCkHttpW cHandle, const wchar_t *outStr);

const wchar_t *CkHttpW_s3_ListBuckets(HCkHttpW cHandle);

Retrieves the XML listing of the buckets for an Amazon S3 account.

Returns TRUE for success, FALSE for failure.

S3 List Buckets Example

HCkTaskW CkHttpW_S3_ListBucketsAsync(HCkHttpW cHandle);

Creates an asynchronous task to call the S3_ListBuckets method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_UploadBytes(HCkHttpW cHandle, const unsigned char * contentBytes, const wchar_t *contentType, const wchar_t *bucketPath, const wchar_t *objectName);

The same as S3_UploadFile, except the contents of the file come from contentBytes instead of a local file.

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

Returns TRUE for success, FALSE for failure.

Demonstrate S3_UploadBytes

HCkTaskW CkHttpW_S3_UploadBytesAsync(HCkHttpW cHandle, const unsigned char * contentBytes, const wchar_t *contentType, const wchar_t *bucketPath, const wchar_t *objectName);

Creates an asynchronous task to call the S3_UploadBytes method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_UploadFile(HCkHttpW cHandle, const wchar_t *localFilePath, const wchar_t *contentType, const wchar_t *bucketPath, const wchar_t *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. This applies to all S3 methods, even if not explicitly stated.

Returns TRUE for success, FALSE for failure.

S3 Upload File

HCkTaskW CkHttpW_S3_UploadFileAsync(HCkHttpW cHandle, const wchar_t *localFilePath, const wchar_t *contentType, const wchar_t *bucketPath, const wchar_t *objectName);

Creates an asynchronous task to call the S3_UploadFile method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_S3_UploadString(HCkHttpW cHandle, const wchar_t *objectContent, const wchar_t *charset, const wchar_t *contentType, const wchar_t *bucketPath, const wchar_t *objectName);

Uploads an in-memory string to the Amazon S3 service. This is the same as UploadFile, except that the file contents are from an in-memory string instead of a local file. Internal to this method, the objectContent is converted to the character encoding specified by charset prior to uploading.

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

Returns TRUE for success, FALSE for failure.

S3 Upload String

HCkTaskW CkHttpW_S3_UploadStringAsync(HCkHttpW cHandle, const wchar_t *objectContent, const wchar_t *charset, const wchar_t *contentType, const wchar_t *bucketPath, const wchar_t *objectName);

Creates an asynchronous task to call the S3_UploadString method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_SaveLastError(HCkHttpW cHandle, const wchar_t *path);

Saves the last-error information (the contents of LastErrorXml) to an XML formatted file.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_SetCookieXml(HCkHttpW cHandle, const wchar_t *domain, const wchar_t *cookieXml);

Restores cookies for a particular domain. It is assumed that the cookie XML was previously retrieved via the GetCookieXml method, and saved to some sort of persistent storage, such as within a database table. It is then possible for an application to restore the cookies by calling this method.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_SetOAuthRsaKey(HCkHttpW cHandle, HCkPrivateKeyW privKey);

Introduced in version 9.5.0.39

Sets the RSA key to be used with OAuth authentication when the RSA-SHA1 OAuth signature method is used (see the OAuthSigMethod property).

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_SetPassword(HCkHttpW cHandle, HCkSecureStringW password);

Introduced in version 9.5.0.71

Equivalent to setting the Password property, but provides for a more secure way of passing the password in a secure string object.

Returns TRUE for success, FALSE for failure.

HTTP Basic Auth with Secure Strings

void CkHttpW_SetRequestHeader(HCkHttpW cHandle, const wchar_t *headerFieldName, const wchar_t *headerFieldValue);

Adds a custom header field to any HTTP request sent by a method that does not use the HTTP request object. These methods include Download, DownloadAppend, GetHead, PostBinary, PostMime, PostXml, PutBinary, PutText, QuickDeleteStr, QuickGet, QuickGetObj, QuickGetStr, QuickPutStr, XmlRpc, and XmlRpcPut.

Cookies may be explictly added by calling this method passing "Cookie" for the headerFieldName.

The RemoveRequestHeader method can be called to remove a custom header.

Note: Never explicitly set the Content-Length header field. Chilkat will automatically compute the correct length and add the Content-Length header to all POST, PUT, or any other request where the Content-Length needs to be specified. (GET requests always have a 0 length body, and therefore never need a Content-Length header field.)

Note: To add more than one header, call this method once per header field.

Add Custom Header to HTTP GET

BOOL CkHttpW_SetSslClientCert(HCkHttpW cHandle, HCkCertW cert);

Allows for a client-side certificate to be used for an SSL connection.

Returns TRUE for success, FALSE for failure.

HTTP TLS Mutual Authentication (Client-Side Certificate)

BOOL CkHttpW_SetSslClientCertPem(HCkHttpW cHandle, const wchar_t *pemDataOrPath, const wchar_t *pemPassword);

Allows for a client-side certificate + private key to be used for the SSL / TLS connection (often called 2-way SSL).

Returns TRUE for success, FALSE for failure.

How to Create a PEM that Contains Certificates and a Private Key

HTTP TLS Mutual Authentication (Client-Side Certificate)

BOOL CkHttpW_SetSslClientCertPfx(HCkHttpW cHandle, const wchar_t *pfxPath, const wchar_t *pfxPassword);

Allows for a client-side certificate + private key to be used for the SSL / TLS connection (often called 2-way SSL).

Returns TRUE for success, FALSE for failure.

HTTP TLS Mutual Authentication (Client-Side Certificate)

BOOL CkHttpW_SetUrlVar(HCkHttpW cHandle, const wchar_t *name, const wchar_t *value);

Introduced in version 9.5.0.67

Sets the value of a variable for substitutions in URLs passed to any method. Variables can appear in URLs in the following format: {$varName}. For example: https://graph.microsoft.com/v1.0/users/{$id}

Returns TRUE for success, FALSE for failure.

void CkHttpW_SleepMs(HCkHttpW cHandle, int millisec);

Convenience method to force the calling process to sleep for a number of milliseconds.

HCkHttpResponseW CkHttpW_SynchronousRequest(HCkHttpW cHandle, const wchar_t *domain, int port, BOOL ssl, HCkHttpRequestW req);

Sends an explicit HttpRequest to an HTTP server and returns an HttpResponse object. The HttpResponse object provides full access to the response including all headers and the response body. This method may be used to send POST requests, as well as GET, HEAD, file uploads, and XMLHTTP. To send via HTTPS (i.e. TLS), set the ssl property = TRUE. Otherwise set it to FALSE.

Returns NULL on failure

How URL Syntax Relates to SynchronousRequest

WebDAV PROPFIND using SynchronousRequest

Simple HTTP POST

Debugging HTTP

Send XMLHttpRequest using PUT, GET, DELETE, or any HTTP Request Method

Adding Cookies to an HTTP Request

HTTP multipart/form-data Upload

Parse a URL into its Component Parts

SOAP with MTOM XOP Attachment

HCkTaskW CkHttpW_SynchronousRequestAsync(HCkHttpW cHandle, const wchar_t *domain, int port, BOOL ssl, HCkHttpRequestW req);

Creates an asynchronous task to call the SynchronousRequest method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

Asynchronous HTTP SOAP 1.2 Request and Response using POST

BOOL CkHttpW_UnlockComponent(HCkHttpW cHandle, const wchar_t *unlockCode);

Unlocks the Http class/component. It is necessary to call Http.UnlockComponent before calling any other methods. Passing any string to UnlockComponent will automatically activate a 30-day trial period.

Returns TRUE for success, FALSE for failure.

Diagnosing UnlockComponent Problems

UnlockComponent LastErrorText shows exact string passed to it.

Verify UnlockComponent Success w/ Purchased Unlock Code

LastErrorText Standard Information

BOOL CkHttpW_UrlDecode(HCkHttpW cHandle, const wchar_t *str, const wchar_t *outStr);

const wchar_t *CkHttpW_urlDecode(HCkHttpW cHandle, const wchar_t *str);

URL decodes a string.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_UrlEncode(HCkHttpW cHandle, const wchar_t *str, const wchar_t *outStr);

const wchar_t *CkHttpW_urlEncode(HCkHttpW cHandle, const wchar_t *str);

URL encodes a string.

Returns TRUE for success, FALSE for failure.

BOOL CkHttpW_XmlRpc(HCkHttpW cHandle, const wchar_t *urlEndpoint, const wchar_t *xmlIn, const wchar_t *outStr);

const wchar_t *CkHttpW_xmlRpc(HCkHttpW cHandle, const wchar_t *urlEndpoint, const wchar_t *xmlIn);

Makes an XML RPC call to a URL endpoint. The XML string is passed in an HTTP POST, and the XML response is returned.

Returns TRUE for success, FALSE for failure.

HTTP XMLRPC Example

HCkTaskW CkHttpW_XmlRpcAsync(HCkHttpW cHandle, const wchar_t *urlEndpoint, const wchar_t *xmlIn);

Creates an asynchronous task to call the XmlRpc method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task

BOOL CkHttpW_XmlRpcPut(HCkHttpW cHandle, const wchar_t *urlEndpoint, const wchar_t *xmlIn, const wchar_t *outStr);

const wchar_t *CkHttpW_xmlRpcPut(HCkHttpW cHandle, const wchar_t *urlEndpoint, const wchar_t *xmlIn);

Same as XmlRpc, but uses the HTTP PUT method instead of the POST method.

Returns TRUE for success, FALSE for failure.

HCkTaskW CkHttpW_XmlRpcPutAsync(HCkHttpW cHandle, const wchar_t *urlEndpoint, const wchar_t *xmlIn);

Creates an asynchronous task to call the XmlRpcPut method with the arguments provided. (Async methods are available starting in Chilkat v9.5.0.52.)

Returns NULL on failure

How to Run an Asynchronous Task