Rest Unicode C Reference Documentation

Rest

Current Version: 9.5.0.97

API for implementing RESTful Web API's.

Create/Dispose

HCkRestW instance = CkRestW_Create();
// ...
CkRestW_Dispose(instance);
HCkRestW CkRestW_Create(void);

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

void CkRestW_Dispose(HCkRestW handle);

Objects created by calling CkRestW_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 CkRestW_Dispose.

Callback Functions

Callback Functions introduced in Chilkat v9.5.0.56
void CkRestW_setAbortCheck(HCkRestW 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.

void CkRestW_setPercentDone(HCkRestW 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 CkRestW_setProgressInfo(HCkRestW 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 CkRestW_setTaskCompleted(HCkRestW cHandle, void (*fnTaskCompleted)(HCkTaskW 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

AllowHeaderFolding
BOOL CkRestW_getAllowHeaderFolding(HCkRestW cHandle);
void CkRestW_putAllowHeaderFolding(HCkRestW 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. This property is provided to satisfy certain providers, such as Quickbooks, that require all MIME headers to be single unfolded lines regardless of length.

top
AllowHeaderQB
BOOL CkRestW_getAllowHeaderQB(HCkRestW cHandle);
void CkRestW_putAllowHeaderQB(HCkRestW cHandle, BOOL newVal);
Introduced in version 9.5.0.59

Controls whether non us-ascii HTTP request headers are automatically Q/B encoded. The default value is TRUE.

Q/B encoded headers explicitly indicate the charset and byte representation, and appear as such: =?utf-8?Q?...?= or =?utf-8?B?...?=, where the charset may be "utf-8" or any other possible charset.

If this property is set to FALSE, then no Q/B encoding is applied to any request header.

top
Authorization
void CkRestW_getAuthorization(HCkRestW cHandle, HCkString retval);
void CkRestW_putAuthorization(HCkRestW cHandle, const wchar_t *newVal);
const wchar_t *CkRestW_authorization(HCkRestW cHandle);
Introduced in version 9.5.0.58

The value of the Authorization HTTP request header (if needed).

top
ConnectFailReason
int CkRestW_getConnectFailReason(HCkRestW cHandle);
Introduced in version 9.5.0.58

If the Connect method fails, this property can be checked to determine the reason for failure.

Possible values are:

0 = success

Normal (non-SSL) 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)
99 = Chilkat not unlocked / trial expired.

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.

top
ConnectTimeoutMs
int CkRestW_getConnectTimeoutMs(HCkRestW cHandle);
void CkRestW_putConnectTimeoutMs(HCkRestW cHandle, int newVal);
Introduced in version 9.5.0.71

The maximum amount of time to wait for the connection to be accepted by the HTTP server.

top
DebugLogFilePath
void CkRestW_getDebugLogFilePath(HCkRestW cHandle, HCkString retval);
void CkRestW_putDebugLogFilePath(HCkRestW cHandle, const wchar_t *newVal);
const wchar_t *CkRestW_debugLogFilePath(HCkRestW 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.

top
DebugMode
BOOL CkRestW_getDebugMode(HCkRestW cHandle);
void CkRestW_putDebugMode(HCkRestW cHandle, BOOL newVal);
Introduced in version 9.5.0.77

If TRUE then all calls to Send* or FullRequest* methods will not actually send a request. Instead, the request will be written to a memory buffer which can then be retrieved by calling GetLastDebugRequest.

More Information and Examples
top
HeartbeatMs
int CkRestW_getHeartbeatMs(HCkRestW cHandle);
void CkRestW_putHeartbeatMs(HCkRestW cHandle, int newVal);
Introduced in version 9.5.0.58

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 REST method can be aborted via the AbortCheck event.

top
Host
void CkRestW_getHost(HCkRestW cHandle, HCkString retval);
void CkRestW_putHost(HCkRestW cHandle, const wchar_t *newVal);
const wchar_t *CkRestW_host(HCkRestW cHandle);
Introduced in version 9.5.0.58

The value of the Host HTTP request header.

top
IdleTimeoutMs
int CkRestW_getIdleTimeoutMs(HCkRestW cHandle);
void CkRestW_putIdleTimeoutMs(HCkRestW cHandle, int newVal);
Introduced in version 9.5.0.58

The maximum amount of time to wait for additional incoming data when receiving, or the max time to wait to send additional data. The default value is 30000 (30 seconds). This is not an overall max timeout. Rather, it is the maximum time to wait when receiving or sending has halted.

top
LastErrorHtml
void CkRestW_getLastErrorHtml(HCkRestW cHandle, HCkString retval);
const wchar_t *CkRestW_lastErrorHtml(HCkRestW 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.

top
LastErrorText
void CkRestW_getLastErrorText(HCkRestW cHandle, HCkString retval);
const wchar_t *CkRestW_lastErrorText(HCkRestW 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.

top
LastErrorXml
void CkRestW_getLastErrorXml(HCkRestW cHandle, HCkString retval);
const wchar_t *CkRestW_lastErrorXml(HCkRestW 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.

top
LastMethodSuccess
BOOL CkRestW_getLastMethodSuccess(HCkRestW cHandle);
void CkRestW_putLastMethodSuccess(HCkRestW cHandle, BOOL newVal);

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.

top
LastRequestHeader
void CkRestW_getLastRequestHeader(HCkRestW cHandle, HCkString retval);
const wchar_t *CkRestW_lastRequestHeader(HCkRestW cHandle);
Introduced in version 9.5.0.58

The full MIME header (not including the HTTP start line which contains the status code and status text), of the last request sent.

top
LastRequestStartLine
void CkRestW_getLastRequestStartLine(HCkRestW cHandle, HCkString retval);
const wchar_t *CkRestW_lastRequestStartLine(HCkRestW cHandle);
Introduced in version 9.5.0.58

The full start line of the last request sent. (The start line begins with the HTTP verb, such as GET, POST, etc., is followed by the URI path, and ends with the HTTP version.)

top
NumResponseHeaders
int CkRestW_getNumResponseHeaders(HCkRestW cHandle);
Introduced in version 9.5.0.58

The number of response header fields. The first response header field is at index 0.

top
PartSelector
void CkRestW_getPartSelector(HCkRestW cHandle, HCkString retval);
void CkRestW_putPartSelector(HCkRestW cHandle, const wchar_t *newVal);
const wchar_t *CkRestW_partSelector(HCkRestW cHandle);
Introduced in version 9.5.0.58

Only used for multipart requests. Selects the target MIME part for calls to AddHeader, RemoveHeader, SetMultipartBodyBinary, SetMultipartBodyString, SetMultipartBodyStream, etc. The default is an empty string and indicates the top-level header. A string value of "1" would indicate the 1st sub-part in a multipart request. A string value of "1.2" would indicate the 2nd sub-part under the 1st sub-part.

It is unlikely you'll ever encounter the need for nested multipart requests (i.e. part selectors such as "1.2") Also, most REST requests are NOT multipart, and therefore this feature is rarely used. An example of a multipart REST request would be for a Google Drive upload, where the top-level Content-Type is multipart/related, the1st sub-part contains the JSON meta-data, and the 2nd sub-part contains the file data.

top
PercentDoneOnSend
BOOL CkRestW_getPercentDoneOnSend(HCkRestW cHandle);
void CkRestW_putPercentDoneOnSend(HCkRestW cHandle, BOOL newVal);
Introduced in version 9.5.0.58

This property only applies to the FullRequest* methods, which are methods that both send an HTTP request and receive the response. (It also only applies to programming languages that support event callbacks.) It determines whether percentage completion is tracked for the sending of the HTTP request, or for the downloading the HTTP response. The default value is FALSE, which is to measure the percent completion when receiving the response.

For example: If the REST request is to download a file, then this property should remain at the default value of FALSE. If the REST request is to upload a file (using a Full* method), then set this property to TRUE. Also note if a server sends an HTTP response in the chunked encoding, it is not possible to measure percent completion because the HTTP client has no way of knowing the total size of the HTTP response.

top
ResponseHeader
void CkRestW_getResponseHeader(HCkRestW cHandle, HCkString retval);
const wchar_t *CkRestW_responseHeader(HCkRestW cHandle);
Introduced in version 9.5.0.58

The full response MIME header (not including the HTTP start line which contains the status code and status text).

top
ResponseStatusCode
int CkRestW_getResponseStatusCode(HCkRestW cHandle);
Introduced in version 9.5.0.58

The response status code.

More Information and Examples
top
ResponseStatusText
void CkRestW_getResponseStatusText(HCkRestW cHandle, HCkString retval);
const wchar_t *CkRestW_responseStatusText(HCkRestW cHandle);
Introduced in version 9.5.0.58

The status message corresponding to the response status code.

More Information and Examples
top
StreamNonChunked
BOOL CkRestW_getStreamNonChunked(HCkRestW cHandle);
void CkRestW_putStreamNonChunked(HCkRestW cHandle, BOOL newVal);
Introduced in version 9.5.0.58

If TRUE, then methods that upload data are sent non-chunked if possible. For example, if the FullRequestStream method is called where the stream is a file stream, then the size of the content is known and the HTTP request will be sent using a Content-Length header instead of using a Transfer-Encoding: chunked upload. If FALSE, then the chunked transfer encoding is used. The default value of this property is TRUE.

top
UncommonOptions
void CkRestW_getUncommonOptions(HCkRestW cHandle, HCkString retval);
void CkRestW_putUncommonOptions(HCkRestW cHandle, const wchar_t *newVal);
const wchar_t *CkRestW_uncommonOptions(HCkRestW cHandle);
Introduced in version 9.5.0.80

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string and should typically remain empty. Can be set to a list of the following comma separated keywords:

  • AllowDuplicateQueryParams - Affects the AddQueryParam method. If the query parameter to be added already exists, it is not replaced and instead an additional param with the same name is added.
  • AllowInsecureBasicAuth - Introduced in v9.5.0.80. Allows HTTP Basic authentication over non-TLS connections. (HTTP Basic authentication puts the login:password in the Authorization header field in base64 encoding. If transmitted over an insecure connection, it is potentially visible to anything sniffing the traffic. By default, Chilkat disallows HTTP Basic authentication except for SSL/TLS connections, SSH tunneled connections, or connections to localhost.)
  • DisableTls13 Disables TLS 1.3 so that only TLS 1.2 or lower is used.
  • ProtectFromVpn - Introduced in v9.5.0.80. On Android systems, will bypass any VPN that may be installed or active.

More Information and Examples
top
VerboseLogging
BOOL CkRestW_getVerboseLogging(HCkRestW cHandle);
void CkRestW_putVerboseLogging(HCkRestW 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.

top
Version
void CkRestW_getVersion(HCkRestW cHandle, HCkString retval);
const wchar_t *CkRestW_version(HCkRestW cHandle);

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

More Information and Examples
top

Methods

AddHeader
BOOL CkRestW_AddHeader(HCkRestW cHandle, const wchar_t *name, const wchar_t *value);
Introduced in version 9.5.0.58

Adds an HTTP request header. If the header field already exists, then it is replaced.

Returns TRUE for success, FALSE for failure.

top
AddMwsSignature
BOOL CkRestW_AddMwsSignature(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, const wchar_t *domain, const wchar_t *mwsSecretKey);
Introduced in version 9.5.0.66

Computes the Amazon MWS signature using the mwsSecretKey and adds the "Signature" parameter to the request. This method should be called for all Amazon Marketplace Web Service (Amazon MWS) HTTP requests. It should be called after all request parameters have been added.

Important: The Chilkat v9.5.0.75 release accidentally breaks Amazon MWS (not AWS) authentication. If you need MWS with 9.5.0.75, send email to support@chilkatsoft.com for a hotfix, or revert back to v9.5.0.73, or update to a version after 9.5.0.75.

The domain should be the domain of the request, such as one of the following:

  • mws.amazonservices.com
  • mws-eu.amazonservices.com
  • mws.amazonservices.in
  • mws.amazonservices.com.cn
  • mws.amazonservices.jp

The httpVerb should be the HTTP verb, such as "GET", "POST", etc. The uriPath is the URI path, such as "/Feeds/2009-01-01". In general, the httpVerb and uriPath should be identical to the 1st two args passed to methods such as FullRequestFormUrlEncoded.

Note: This method also automatically adds or replaces the existing Timestamp parameter to the current system date/time.

Returns TRUE for success, FALSE for failure.

top
AddPathParam
BOOL CkRestW_AddPathParam(HCkRestW cHandle, const wchar_t *name, const wchar_t *value);
Introduced in version 9.5.0.70

Adds or replaces a path parameter. A path parameter is a string that will be replaced in any uriPath string passed to a method. For example, if name is "fileId" and value is "1R_70heIyzIAu1_u0prXbYcaIiJRVkgBl", then a uriPath argument of "/drive/v3/files/fileId" will be transformed to "/drive/v3/files/1R_70heIyzIAu1_u0prXbYcaIiJRVkgBl" in a method call.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
AddQueryParam
BOOL CkRestW_AddQueryParam(HCkRestW cHandle, const wchar_t *name, const wchar_t *value);
Introduced in version 9.5.0.58

Adds a query parameter. If the query parameter already exists, then it is replaced.

To allow duplicates, you can add the keyword "AllowDuplicateQueryParams" to the UncommonOptions property value. In other words, if the query parameter already exists, it is not replaced and instead an additional param with the same name is added.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
AddQueryParams
BOOL CkRestW_AddQueryParams(HCkRestW cHandle, const wchar_t *queryString);
Introduced in version 9.5.0.58

Adds the query parameters from the queryString. The queryString is a query string of the format field1=value1&field2=value2&field3=value3... where each value is URL encoded.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
AddQueryParamSb
BOOL CkRestW_AddQueryParamSb(HCkRestW cHandle, const wchar_t *name, HCkStringBuilderW value);
Introduced in version 9.5.0.62

Adds a query parameter. If the query parameter already exists, then it is replaced. The parameter value is passed in a StringBuilder object.

Returns TRUE for success, FALSE for failure.

top
ClearAllHeaders
BOOL CkRestW_ClearAllHeaders(HCkRestW cHandle);
Introduced in version 9.5.0.58

Removes all HTTP request headers.

Returns TRUE for success, FALSE for failure.

top
ClearAllParts
BOOL CkRestW_ClearAllParts(HCkRestW cHandle);
Introduced in version 9.5.0.64

Removes all sub-parts from a request. This is useful when preparing the REST object to send a new request after a multipart request has just been sent.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
ClearAllPathParams
BOOL CkRestW_ClearAllPathParams(HCkRestW cHandle);
Introduced in version 9.5.0.70

Clears all path parameters.

Returns TRUE for success, FALSE for failure.

top
ClearAllQueryParams
BOOL CkRestW_ClearAllQueryParams(HCkRestW cHandle);
Introduced in version 9.5.0.58

Clears all query parameters.

Returns TRUE for success, FALSE for failure.

top
ClearAuth
BOOL CkRestW_ClearAuth(HCkRestW cHandle);
Introduced in version 9.5.0.69

Clears all authentication settings.

Returns TRUE for success, FALSE for failure.

top
ClearResponseBodyStream
void CkRestW_ClearResponseBodyStream(HCkRestW cHandle);
Introduced in version 9.5.0.58

Clears the response body stream.

top
Connect
BOOL CkRestW_Connect(HCkRestW cHandle, const wchar_t *hostname, int port, BOOL tls, BOOL autoReconnect);
Introduced in version 9.5.0.58

Establishes an initial connection to a REST server. The hostname can be a domain name or an IP address. Both IPv4 and IPv6 addresses are supported. The port is the port, which is typically 80 or 443. If SSL/TLS is required, then tls should be set to TRUE. The autoReconnect indicates whether connection should automatically be established as needed for subsequent REST requests.

Note: This method is for simple connections that do not require any proxies (HTTP or SOCKS), or SSH tunneling. If a proxy, SSH tunnel, or any other advanced socket feature is required, the Chilkat Socket API can be used to establish the connection. The UseConnection method can then be called to use the pre-established socket connection.

IMPORTANT: The hostname argument should be just the domain or IP address. It is NOT the full URL. If your URL is "https://www.example.com/something/123", then pass "www.example.com" in the 1st argument.

Returns TRUE for success, FALSE for failure.

top
ConnectAsync (1)
HCkTaskW CkRestW_ConnectAsync(HCkRestW cHandle, const wchar_t *hostname, int port, BOOL tls, BOOL autoReconnect);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
Disconnect
BOOL CkRestW_Disconnect(HCkRestW cHandle, int maxWaitMs);
Introduced in version 9.5.0.58

Closes the connection with the HTTP server if one is open. This method can be called to ensure the connection is closed. The maxWaitMs is the maximum time in milliseconds to wait for a clean close. If the connection is through an SSH tunnel, this closes the logical channel within the SSH tunnel, and not the connection with the SSH server itself.

Returns TRUE for success, FALSE for failure.

top
DisconnectAsync (1)
HCkTaskW CkRestW_DisconnectAsync(HCkRestW cHandle, int maxWaitMs);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
FullRequestBd
BOOL CkRestW_FullRequestBd(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkBinDataW binData, HCkStringBuilderW responseBody);
Introduced in version 9.5.0.64

Sends a complete REST request (header + binary body) and receives the full response. The binary body of the request is passed in binData. The response body is returned in responseBody (replacing whatever contents responseBody may have previously held).

Note: If your application wishes to receive percent-done callbacks, make sure the PercentDoneOnSend property is set to indicate whether percent-done applies to sending or receiving.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
FullRequestBdAsync (1)
HCkTaskW CkRestW_FullRequestBdAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkBinDataW binData, HCkStringBuilderW responseBody);
Introduced in version 9.5.0.64

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

Returns NULL on failure

top
FullRequestBinary
BOOL CkRestW_FullRequestBinary(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkByteData bodyBytes, const wchar_t *outStr);
const wchar_t *CkRestW_fullRequestBinary(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkByteData bodyBytes);
Introduced in version 9.5.0.58

Sends a complete REST request (header + body) and receives the full response. It is assumed that the request body is binary, and the response body is a string (such as JSON or XML). The response body is returned.

This method is the equivalent of making the following calls in sequence: SendReqBinaryBody, ReadResponseHeader, ReadRespBodyString.

Note: If your application wishes to receive percent-done callbacks, make sure the PercentDoneOnSend property is set to indicate whether percent-done applies to sending or receiving.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
FullRequestBinaryAsync (1)
HCkTaskW CkRestW_FullRequestBinaryAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkByteData bodyBytes);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
FullRequestFormUrlEncoded
BOOL CkRestW_FullRequestFormUrlEncoded(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, const wchar_t *outStr);
const wchar_t *CkRestW_fullRequestFormUrlEncoded(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

Sends a complete application/x-www-form-urlencoded HTTP request and receives the full response. The request body is composed of the URL encoded query params. It is assumed that the response body is a string (such as JSON or XML). The response body is returned.

This method is the equivalent of making the following calls in sequence: SendReqFormUrlEncoded, ReadResponseHeader, ReadRespBodyString.

Note: If your application wishes to receive percent-done callbacks, make sure the PercentDoneOnSend property is set to indicate whether percent-done applies to sending or receiving.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
FullRequestFormUrlEncodedAsync (1)
HCkTaskW CkRestW_FullRequestFormUrlEncodedAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
FullRequestMultipart
BOOL CkRestW_FullRequestMultipart(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, const wchar_t *outStr);
const wchar_t *CkRestW_fullRequestMultipart(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

Sends a complete multipart REST request (header + multipart body) and receives the full response. It is assumed that the response body is a string (such as JSON or XML). The response body is returned.

This method is the equivalent of making the following calls in sequence: SendReqMultipart, ReadResponseHeader, ReadRespBodyString.

Note: If your application wishes to receive percent-done callbacks, make sure the PercentDoneOnSend property is set to indicate whether percent-done applies to sending or receiving.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
FullRequestMultipartAsync (1)
HCkTaskW CkRestW_FullRequestMultipartAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
FullRequestNoBody
BOOL CkRestW_FullRequestNoBody(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, const wchar_t *outStr);
const wchar_t *CkRestW_fullRequestNoBody(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

Sends a complete REST request and receives the full response. It is assumed that the response body is a string (such as JSON or XML). The response body is returned.

This method is the equivalent of making the following calls in sequence: SendReqNoBody, ReadResponseHeader, ReadRespBodyString.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
FullRequestNoBodyAsync (1)
HCkTaskW CkRestW_FullRequestNoBodyAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
FullRequestNoBodyBd
BOOL CkRestW_FullRequestNoBodyBd(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkBinDataW binData);
Introduced in version 9.5.0.64

The same as FullRequestNoBody, except returns the response body in the binData. This method is useful for downloading binary files.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
FullRequestNoBodyBdAsync (1)
HCkTaskW CkRestW_FullRequestNoBodyBdAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkBinDataW binData);
Introduced in version 9.5.0.64

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

Returns NULL on failure

top
FullRequestNoBodySb
BOOL CkRestW_FullRequestNoBodySb(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStringBuilderW sb);
Introduced in version 9.5.0.64

The same as FullRequestNoBody, except returns the response body in the sb.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
FullRequestNoBodySbAsync (1)
HCkTaskW CkRestW_FullRequestNoBodySbAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStringBuilderW sb);
Introduced in version 9.5.0.64

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

Returns NULL on failure

top
FullRequestSb
BOOL CkRestW_FullRequestSb(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStringBuilderW requestBody, HCkStringBuilderW responseBody);
Introduced in version 9.5.0.62

Sends a complete REST request (header + body string) and receives the full response. The body of the request is passed in requestBody. The response body is returned in responseBody (replacing whatever contents responseBody may have previously held).

Note: If your application wishes to receive percent-done callbacks, make sure the PercentDoneOnSend property is set to indicate whether percent-done applies to sending or receiving.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
FullRequestSbAsync (1)
HCkTaskW CkRestW_FullRequestSbAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStringBuilderW requestBody, HCkStringBuilderW responseBody);
Introduced in version 9.5.0.62

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

Returns NULL on failure

top
FullRequestStream
BOOL CkRestW_FullRequestStream(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStreamW stream, const wchar_t *outStr);
const wchar_t *CkRestW_fullRequestStream(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStreamW stream);
Introduced in version 9.5.0.58

Sends a complete REST request and receives the full response. It is assumed that the response body is a string (such as JSON or XML). The response body is returned.

This method is the equivalent of making the following calls in sequence: SendReqStream, ReadResponseHeader, ReadRespBodyString.

Note: If your application wishes to receive percent-done callbacks, make sure the PercentDoneOnSend property is set to indicate whether percent-done applies to sending or receiving.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
FullRequestStreamAsync (1)
HCkTaskW CkRestW_FullRequestStreamAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStreamW stream);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
FullRequestString
BOOL CkRestW_FullRequestString(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, const wchar_t *bodyText, const wchar_t *outStr);
const wchar_t *CkRestW_fullRequestString(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, const wchar_t *bodyText);
Introduced in version 9.5.0.58

Sends a complete REST request (header + body string) and receives the full response. It is assumed that both the request and response bodies are strings (such as JSON or XML). The response body is returned.

This method is the equivalent of making the following calls in sequence: SendReqStringBody, ReadResponseHeader, ReadRespBodyString.

Note: If your application wishes to receive percent-done callbacks, make sure the PercentDoneOnSend property is set to indicate whether percent-done applies to sending or receiving.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
FullRequestStringAsync (1)
HCkTaskW CkRestW_FullRequestStringAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, const wchar_t *bodyText);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
GetLastDebugRequest
BOOL CkRestW_GetLastDebugRequest(HCkRestW cHandle, HCkBinDataW bd);
Introduced in version 9.5.0.77

Returns the fully composed HTTP request that would've been sent had the DebugMode been turned off. The request is returned in bd.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
LastJsonData
HCkJsonObjectW CkRestW_LastJsonData(HCkRestW cHandle);
Introduced in version 9.5.0.79

Provides information about what transpired in the last method called on this object instance. For many methods, there is no information. However, for some methods, details about what occurred can be obtained by getting the LastJsonData right after the method call returns.

Returns NULL on failure

top
LoadTaskCaller
BOOL CkRestW_LoadTaskCaller(HCkRestW cHandle, HCkTaskW task);
Introduced in version 9.5.0.80

Loads the caller of the task's async method.

Returns TRUE for success, FALSE for failure.

top
ReadRespBd
BOOL CkRestW_ReadRespBd(HCkRestW cHandle, HCkBinDataW responseBody);
Introduced in version 9.5.0.62

Reads the response body. Should only be called after ReadResponseHeader has been called, and should only be called when it is already known that the response body is binary, such as for JPG images or other non-text binary file types. The response body is received into responseBody (replacing whatever contents responseBody may have previously held).

Returns TRUE for success, FALSE for failure.

top
ReadRespBdAsync (1)
HCkTaskW CkRestW_ReadRespBdAsync(HCkRestW cHandle, HCkBinDataW responseBody);
Introduced in version 9.5.0.62

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

Returns NULL on failure

top
ReadRespBodyBinary
BOOL CkRestW_ReadRespBodyBinary(HCkRestW cHandle, const unsigned char * outBytes);
Introduced in version 9.5.0.58

Reads the response body. Should only be called after ReadResponseHeader has been called, and should only be called when it is already known that the response body is binary, such as for JPG images or other non-text binary file types.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
ReadRespBodyBinaryAsync (1)
HCkTaskW CkRestW_ReadRespBodyBinaryAsync(HCkRestW cHandle);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
ReadRespBodyStream
BOOL CkRestW_ReadRespBodyStream(HCkRestW cHandle, HCkStreamW stream, BOOL autoSetStreamCharset);
Introduced in version 9.5.0.58

Reads the response body to the stream. If autoSetStreamCharset is TRUE, then the stream's StringCharset property will automatically get set based on the charset, if any, indicated in the response header. If the response is binary, then autoSetStreamCharset is ignored.

Returns TRUE for success, FALSE for failure.

top
ReadRespBodyStreamAsync (1)
HCkTaskW CkRestW_ReadRespBodyStreamAsync(HCkRestW cHandle, HCkStreamW stream, BOOL autoSetStreamCharset);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
ReadRespBodyString
BOOL CkRestW_ReadRespBodyString(HCkRestW cHandle, const wchar_t *outStr);
const wchar_t *CkRestW_readRespBodyString(HCkRestW cHandle);
Introduced in version 9.5.0.58

Reads the response body. Should only be called after ReadResponseHeader has been called, and should only be called when it is already known that the response body will be a string (such as XML, JSON, etc.)

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
ReadRespBodyStringAsync (1)
HCkTaskW CkRestW_ReadRespBodyStringAsync(HCkRestW cHandle);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
ReadResponseHeader
int CkRestW_ReadResponseHeader(HCkRestW cHandle);
Introduced in version 9.5.0.58

Reads the HTTP response header. If the HTTP response includes a body, then the application must call the desired method to read the response body. Otherwise, the HTTP request / response is finished after reading the response header (such as for a GET request). The contents of the response header are available in various properties and methods.

The HTTP response status code is returned (such as 200 for a typical success response). If an error occurred such that no response was received, then a value of -1 is returned.

More Information and Examples
top
ReadResponseHeaderAsync (1)
HCkTaskW CkRestW_ReadResponseHeaderAsync(HCkRestW cHandle);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
ReadRespSb
BOOL CkRestW_ReadRespSb(HCkRestW cHandle, HCkStringBuilderW responseBody);
Introduced in version 9.5.0.62

Reads the response body. Should only be called after ReadResponseHeader has been called, and should only be called when it is already known that the response body will be a string (such as XML, JSON, etc.) The response body is stored in responseBody. (replacing whatever contents responseBody may have previously held).

Returns TRUE for success, FALSE for failure.

top
ReadRespSbAsync (1)
HCkTaskW CkRestW_ReadRespSbAsync(HCkRestW cHandle, HCkStringBuilderW responseBody);
Introduced in version 9.5.0.62

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

Returns NULL on failure

top
RedirectUrl
HCkUrlW CkRestW_RedirectUrl(HCkRestW cHandle);
Introduced in version 9.5.0.58

If the response was a redirect and contains a Location header field, this method returns the redirect URL.

Returns NULL on failure

More Information and Examples
top
RemoveHeader
BOOL CkRestW_RemoveHeader(HCkRestW cHandle, const wchar_t *name);
Introduced in version 9.5.0.58

Removes all headers having the given name.

Returns TRUE for success, FALSE for failure.

top
RemoveQueryParam
BOOL CkRestW_RemoveQueryParam(HCkRestW cHandle, const wchar_t *name);
Introduced in version 9.5.0.58

Removes all query params having the given name.

Returns TRUE for success, FALSE for failure.

top
ResponseHdrByName
BOOL CkRestW_ResponseHdrByName(HCkRestW cHandle, const wchar_t *name, const wchar_t *outStr);
const wchar_t *CkRestW_responseHdrByName(HCkRestW cHandle, const wchar_t *name);
Introduced in version 9.5.0.58

Returns the value of the response header indicated by name.

Returns TRUE for success, FALSE for failure.

top
ResponseHdrName
BOOL CkRestW_ResponseHdrName(HCkRestW cHandle, int index, const wchar_t *outStr);
const wchar_t *CkRestW_responseHdrName(HCkRestW cHandle, int index);
Introduced in version 9.5.0.58

Returns the name of the Nth response header field. (Chilkat always uses 0-based indexing. The first header field is at index 0.)

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
ResponseHdrValue
BOOL CkRestW_ResponseHdrValue(HCkRestW cHandle, int index, const wchar_t *outStr);
const wchar_t *CkRestW_responseHdrValue(HCkRestW cHandle, int index);
Introduced in version 9.5.0.58

Returns the value of the Nth response header field. (Chilkat always uses 0-based indexing. The first header field is at index 0.)

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SendReqBd
BOOL CkRestW_SendReqBd(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkBinDataW body);
Introduced in version 9.5.0.62

Sends a REST request that cotnains a binary body. The httpVerb is the HTTP verb (also known as the HTTP method), such as "PUT". The uriPath is the path of the resource URI. The body contains the bytes of the HTTP request body.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
SendReqBdAsync (1)
HCkTaskW CkRestW_SendReqBdAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkBinDataW body);
Introduced in version 9.5.0.62

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

Returns NULL on failure

top
SendReqBinaryBody
BOOL CkRestW_SendReqBinaryBody(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkByteData body);
Introduced in version 9.5.0.58

Sends a REST request that cotnains a binary body. The httpVerb is the HTTP verb (also known as the HTTP method), such as "PUT". The uriPath is the path of the resource URI. The body contains the bytes of the HTTP request body.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
SendReqBinaryBodyAsync (1)
HCkTaskW CkRestW_SendReqBinaryBodyAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkByteData body);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
SendReqFormUrlEncoded
BOOL CkRestW_SendReqFormUrlEncoded(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

Sends an application/x-www-form-urlencoded HTTP request where the body is composed of the URL encoded query params. The httpVerb is the HTTP verb (also known as the HTTP method), such as "POST". The uriPath is the path of the resource URI. If the Content-Type header was set, it is ignored and instead the Content-Type of the request will be "application/x-www-form-urlencoded".

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
SendReqFormUrlEncodedAsync (1)
HCkTaskW CkRestW_SendReqFormUrlEncodedAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
SendReqMultipart
BOOL CkRestW_SendReqMultipart(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

Sends a multipart REST request. The httpVerb is the HTTP verb (also known as the HTTP method), such as "GET". The uriPath is the path of the resource URI.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
SendReqMultipartAsync (1)
HCkTaskW CkRestW_SendReqMultipartAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
SendReqNoBody
BOOL CkRestW_SendReqNoBody(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

Sends a REST request that cotnains no body. The httpVerb is the HTTP verb (also known as the HTTP method), such as "GET". The uriPath is the path of the resource URI.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
SendReqNoBodyAsync (1)
HCkTaskW CkRestW_SendReqNoBodyAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
SendReqSb
BOOL CkRestW_SendReqSb(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStringBuilderW bodySb);
Introduced in version 9.5.0.62

Sends a REST request that cotnains a text body, such as XML or JSON. The httpVerb is the HTTP verb (also known as the HTTP method), such as "PUT". The uriPath is the path of the resource URI. The bodySb contains the text of the HTTP request body.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

top
SendReqSbAsync (1)
HCkTaskW CkRestW_SendReqSbAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStringBuilderW bodySb);
Introduced in version 9.5.0.62

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

Returns NULL on failure

top
SendReqStreamBody
BOOL CkRestW_SendReqStreamBody(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStreamW stream);
Introduced in version 9.5.0.58

Sends a REST request that cotnains a binary or text body that is obtained by reading from the stream. The httpVerb is the HTTP verb (also known as the HTTP method), such as "PUT". The uriPath is the path of the resource URI.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SendReqStreamBodyAsync (1)
HCkTaskW CkRestW_SendReqStreamBodyAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, HCkStreamW stream);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
SendReqStringBody
BOOL CkRestW_SendReqStringBody(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, const wchar_t *bodyText);
Introduced in version 9.5.0.58

Sends a REST request that cotnains a text body, such as XML or JSON. The httpVerb is the HTTP verb (also known as the HTTP method), such as "PUT". The uriPath is the path of the resource URI. The bodyText contains the text of the HTTP request body.

IMPORTANT: The uriPath argument should be just the path part of the URL. It is NOT the full URL. If your URL is "https://www.example.com/something/123?xyz=1", then the uriPath is "/something/123?xyz=1".

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SendReqStringBodyAsync (1)
HCkTaskW CkRestW_SendReqStringBodyAsync(HCkRestW cHandle, const wchar_t *httpVerb, const wchar_t *uriPath, const wchar_t *bodyText);
Introduced in version 9.5.0.58

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

Returns NULL on failure

top
SetAuthAws
BOOL CkRestW_SetAuthAws(HCkRestW cHandle, HCkAuthAwsW authProvider);
Introduced in version 9.5.0.58

Sets the authorization service provider for Amazon AWS REST requests. An application that sets an AWS authentication provider need not explicitly set the Authorization property. Each REST request is automatically signed and authenticated using the authProvider.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SetAuthAzureAD
BOOL CkRestW_SetAuthAzureAD(HCkRestW cHandle, HCkAuthAzureADW authProvider);
Introduced in version 9.5.0.58

Sets the Azure AD (Active Directory) authorization service provider.

Returns TRUE for success, FALSE for failure.

top
SetAuthAzureSas
BOOL CkRestW_SetAuthAzureSas(HCkRestW cHandle, HCkAuthAzureSASW authProvider);
Introduced in version 9.5.0.65

Provides the information for Azure SAS (Shared Access Signature) authorization. Calling this method will cause the "Authorization: SharedAccessSignature ..." header to be automatically added to all requests.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SetAuthAzureStorage
BOOL CkRestW_SetAuthAzureStorage(HCkRestW cHandle, HCkAuthAzureStorageW authProvider);
Introduced in version 9.5.0.58

Sets the authorization service provider for Azure Storage Service requests.

Returns TRUE for success, FALSE for failure.

top
SetAuthBasic
BOOL CkRestW_SetAuthBasic(HCkRestW cHandle, const wchar_t *username, const wchar_t *password);
Introduced in version 9.5.0.58

Sets the username and password to be used for Basic authentication. This method should be called when Basic authentication is required. It should only be used with secure SSL/TLS connections. Calling this method will cause the "Authorization: Basic ..." header to be automatically added to all requests. In many cases, a REST API will support Basic authentication where the username is a client ID or account ID, and the password is a client secret or token.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SetAuthBasicSecure
BOOL CkRestW_SetAuthBasicSecure(HCkRestW cHandle, HCkSecureStringW username, HCkSecureStringW password);
Introduced in version 9.5.0.71

The same as SetAuthBasic, but provides a more secure means for passing the arguments as secure string objects.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SetAuthGoogle
BOOL CkRestW_SetAuthGoogle(HCkRestW cHandle, HCkAuthGoogleW authProvider);
Introduced in version 9.5.0.58

Sets the authorization service provider for Google API requests.

Returns TRUE for success, FALSE for failure.

top
SetAuthOAuth1
BOOL CkRestW_SetAuthOAuth1(HCkRestW cHandle, HCkOAuth1W authProvider, BOOL useQueryParams);
Introduced in version 9.5.0.58

Sets the authentication provider for REST API requests needing OAuth 1.0 (and OAuth 1.0a) authentication. If useQueryParams is TRUE, then the OAuth1 authentication information and signature is passed in query parameters. Otherwise it is passed in an Authorization header.

Returns TRUE for success, FALSE for failure.

top
SetAuthOAuth2
BOOL CkRestW_SetAuthOAuth2(HCkRestW cHandle, HCkOAuth2W authProvider);
Introduced in version 9.5.0.59

Causes the "Authorization: Bearer <access_token>" header to be added to each request. The authProvider should have been loaded with an OAuth2 access token, which is JSON that looks similar to this:

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 14400,
  "scope": "...",
  "token_type": "bearer",
  "expires_on": "1611099058"
}

Your access token may contain different JSON members, but it should contain the two required members "access_token" and "token_type". The "token_type" should be "bearer" (case-insensitive).

Note: It is also possible to manually add the Authorization header in the same way as any other header by calling the AddHeader method. If the Authorization header is added via AddHeader, then don't use this method.

Returns TRUE for success, FALSE for failure.

top
SetMultipartBodyBd
BOOL CkRestW_SetMultipartBodyBd(HCkRestW cHandle, HCkBinDataW bodyData);
Introduced in version 9.5.0.62

Only used for multipart requests. Sets the binary content of the multipart body indicated by the PartSelector.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SetMultipartBodyBinary
BOOL CkRestW_SetMultipartBodyBinary(HCkRestW cHandle, HCkByteData bodyData);
Introduced in version 9.5.0.58

Only used for multipart requests. Sets the binary content of the multipart body indicated by the PartSelector.

Returns TRUE for success, FALSE for failure.

top
SetMultipartBodySb
BOOL CkRestW_SetMultipartBodySb(HCkRestW cHandle, HCkStringBuilderW bodySb);
Introduced in version 9.5.0.62

Only used for multipart requests. Sets the text content of the multipart body indicated by the PartSelector.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SetMultipartBodyStream
BOOL CkRestW_SetMultipartBodyStream(HCkRestW cHandle, HCkStreamW stream);
Introduced in version 9.5.0.58

Only used for multipart requests. Sets the stream source of the multipart body indicated by the PartSelector.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
SetMultipartBodyString
BOOL CkRestW_SetMultipartBodyString(HCkRestW cHandle, const wchar_t *bodyText);
Introduced in version 9.5.0.58

Only used for multipart requests. Sets the text content of the multipart body indicated by the PartSelector.

Returns TRUE for success, FALSE for failure.

top
SetResponseBodyStream
BOOL CkRestW_SetResponseBodyStream(HCkRestW cHandle, int expectedStatus, BOOL autoSetStreamCharset, HCkStreamW responseStream);
Introduced in version 9.5.0.58

Only applies to the Full* methods, such as FullRequestNoBody, FullRequestBinary, FullRequestStream, etc. When set, the response body is streamed directly to responseStream, if (and only if) the HTTP response status code equals expectedStatus.

If the response body was streamed to responseStream, then the string return value of the Full* method instead becomes "OK" for success. If an attempt was made to stream the response body but it failed, then "FAIL" is returned. If the response body was not streamed because the response status code was not equal to expectedStatus, then the returned string contains the server's error response.

If autoSetStreamCharset is TRUE, then the expectedStatus's StringCharset property will automatically get set based on the charset, if any, indicated in the response header. If the response is binary, then autoSetStreamCharset is ignored.

Starting in v9.5.0.75, the expectedStatus may be passed as a negative number to specify a range of expected (success) status codes. For example:

  • -200: Allow status codes 200 - 299
  • -210: Allow status codes 210 - 219
  • -220: Allow status codes 220 - 229
  • etc.

Returns TRUE for success, FALSE for failure.

top
UseConnection
BOOL CkRestW_UseConnection(HCkRestW cHandle, HCkSocketW connection, BOOL autoReconnect);
Introduced in version 9.5.0.58

Sets the connection to be used for sending the REST request. The connection should be an already-connected socket. It may be a TLS connection, an unencrypted connection, through an HTTP proxy, a SOCKS proxy, or even through SSH tunnels. All of the connection related functionality is handled by the Chilkat Socket API.

The autoReconnect indicates whether connection should automatically be established as needed for subsequent REST requests.

Important: The UseConnection method is provided as a means for handling more complicated connections -- such as connections through proxies, tunnels, etc. If your application is connecting directly to the HTTP server, then simply call this class's Connect method.

Returns TRUE for success, FALSE for failure.

top