Rest Delphi DLL Reference Documentation
Rest
Current Version: 11.5.0
Chilkat.Rest
Build REST requests with explicit paths, headers, query parameters,
request bodies, content types, and HTTP methods.
Connect once and send multiple requests over the same underlying
connection when appropriate.
Work with bearer tokens, OAuth2, AWS-style signing, Azure and Google
auth helpers, and other service-specific authentication patterns.
Send JSON, XML, text, binary data, form parameters, multipart requests,
streams, and file-based request bodies.
Read response bodies as strings, bytes, streams, JSON, XML, or
Use detailed error text, raw request generation, response headers,
connection state, and verbose diagnostics to troubleshoot API behavior.
For an extended overview, see
Rest Class Overview.
Build, send, authenticate, stream, and inspect REST API requests with precise control.
Chilkat.Rest is a flexible REST client class for applications
that need detailed control over request construction, connection reuse,
authentication, headers, query parameters, multipart bodies, streaming
uploads and downloads, response parsing, and low-level diagnostics. It is
especially useful for APIs where the application must carefully manage
provider-specific signing, request paths, body formats, and server responses.
Precise request construction
Connection reuse
Authentication support
Request bodies and multipart
Response handling
StringBuilder content, and inspect status codes and headers.
Diagnostics and debugging
Chilkat.Rest when you want fine-grained control over the
connection and request construction. For higher-level HTTP convenience
methods that accept full URLs directly, use Chilkat.Http. For
advanced socket routing, create the connection with Chilkat.Socket
and pass it to UseConnection.
Rest object
until they are replaced or cleared. When reusing an object for unrelated requests,
call the applicable Clear* methods rather than assuming request state
is automatically reset.
SendReq* call, call ReadResponseHeader and then read
the response body exactly once when a body is present. Fully consume the body before
sending another request on the same connection. A HEAD response has no
body; a 204 No Content response is represented by an empty body.
Rest class exposes redirect and response-header information but does
not automatically follow redirects or maintain a cookie jar. Applications should
process Location and Set-Cookie values explicitly when needed.
Create/Dispose
var myObject: HCkRest; begin myObject := CkRest_Create(); // ... CkRest_Dispose(myObject); end;
Creates an instance of the HCkRest object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page.
Objects created by calling CkRest_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.
Properties
AllowHeaderFolding
procedure CkRest_putAllowHeaderFolding(objHandle: HCkRest; newPropVal: wordbool); stdcall;
Controls whether long request-header fields may be folded onto continuation lines. The default is False. When set to False, each request header is emitted on a single physical line.
False when the service requires unfolded header lines, as is common for canonicalized request signatures.AllowHeaderQB
procedure CkRest_putAllowHeaderQB(objHandle: HCkRest; newPropVal: wordbool); stdcall;
Controls whether non-ASCII request-header values may be converted to RFC 2047 encoded-word form using Q or Base64 encoding. The default is True.
Encoded words have forms such as =?utf-8?Q?...?= and =?utf-8?B?...?=. When this property is False, Chilkat does not apply this conversion.
Authorization
procedure CkRest_putAuthorization(objHandle: HCkRest; newPropVal: PWideChar); stdcall;
function CkRest__authorization(objHandle: HCkRest): PWideChar; stdcall;
Gets or sets the value sent in the HTTP Authorization request header. Supply only the field value, such as Bearer eyJ..., not the text Authorization:.
SetAuth* method. A configured authentication provider may generate or replace the Authorization header when the request is sent.SetAuth* provider is active, its generated Authorization header takes precedence over this property and over a manually added Authorization header. ClearAuth clears both the provider and this value; clearing top-level headers also clears this property.See the notes about PWideChar memory ownership and validity.
ConnectFailReason
After Connect fails, returns a code identifying the connection stage or TLS handshake stage that failed.
| Code | Meaning |
|---|---|
0 | Success |
1 | Empty hostname |
2 | DNS lookup failed |
3 | DNS timeout |
4 | Aborted by the application |
5 | Internal failure |
6 | Connection timed out |
7 | Connection rejected or otherwise failed |
99 | Chilkat is not unlocked or the trial expired |
TLS-related codes:
| Code | Meaning |
|---|---|
100 | TLS internal error |
101 | Failed to send ClientHello |
102 | Unexpected handshake message |
103 | Failed to read ServerHello |
104 | No server certificate |
105 | Unexpected TLS protocol version |
106 | Server certificate verification failed |
107 | Unacceptable TLS protocol version |
109 | Failed to read handshake messages |
110 | Failed to send the client-certificate handshake message |
111 | Failed to send ClientKeyExchange |
112 | Client certificate private key is inaccessible |
113 | Failed to send CertificateVerify |
114 | Failed to send ChangeCipherSpec |
115 | Failed to send Finished |
116 | The server Finished message is invalid |
LastErrorText for the full failure context.Connect resets this property to 0. HTTP response properties are separate and are not cleared by a later failed connection attempt.ConnectTimeoutMs
procedure CkRest_putConnectTimeoutMs(objHandle: HCkRest; newPropVal: Integer); stdcall;
Gets or sets the maximum number of milliseconds to wait for the remote server to accept the TCP connection. This timeout covers connection establishment, not the later sending or receiving of HTTP data.
IdleTimeoutMs to control how long an established operation may remain without send or receive progress.The default is 30000 milliseconds.
DebugLogFilePath
procedure CkRest_putDebugLogFilePath(objHandle: HCkRest; newPropVal: PWideChar); stdcall;
function CkRest__debugLogFilePath(objHandle: HCkRest): PWideChar; stdcall;
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
See the notes about PWideChar memory ownership and validity.
DebugMode
procedure CkRest_putDebugMode(objHandle: HCkRest; newPropVal: wordbool); stdcall;
When True, calls to the Send* and FullRequest* methods compose the complete request but do not transmit it. Retrieve the generated request with GetLastDebugRequest. The default is False.
In debug mode, a composed full-request call reports a synthetic successful result with ResponseStatusCode equal to 201, ResponseStatusText equal to OK, and no actual response header or response body.
EnableSecrets
procedure CkRest_putEnableSecrets(objHandle: HCkRest; newPropVal: wordbool); stdcall;
Controls automatic resolution of credentials from operating-system secure storage. The default is False.
When set to True, supported credential inputs may contain a secret specification beginning with !! instead of a literal secret. Chilkat resolves the specification from Windows Credential Manager on Windows or Apple Keychain on macOS.
The specification format is:
!![appName|]service[|domain]|username
For this class, secret specifications apply to the username and password supplied to SetAuthBasic.
HeartbeatMs
procedure CkRest_putHeartbeatMs(objHandle: HCkRest; newPropVal: Integer); stdcall;
Controls the interval, in milliseconds, between AbortCheck event callbacks during supported long-running operations. The default is 0, which disables periodic AbortCheck callbacks.
Host
procedure CkRest_putHost(objHandle: HCkRest; newPropVal: PWideChar); stdcall;
function CkRest__host(objHandle: HCkRest): PWideChar; stdcall;
Gets or sets the value of the HTTP Host request header.
Connect or UseConnection. Set this property explicitly only when the request must present a different virtual-host value.An explicitly assigned value overrides the generated HTTP Host field, but it does not change the TCP/TLS destination established by Connect or UseConnection.
See the notes about PWideChar memory ownership and validity.
topIdleTimeoutMs
procedure CkRest_putIdleTimeoutMs(objHandle: HCkRest; newPropVal: Integer); stdcall;
Gets or sets the maximum number of milliseconds to wait when a send or receive operation has stopped making progress. The default is 30000 milliseconds.
A value of 0 disables the inactivity timeout.
LastErrorHtml
function CkRest__lastErrorHtml(objHandle: HCkRest): PWideChar; stdcall;
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
See the notes about PWideChar memory ownership and validity.
topLastErrorText
function CkRest__lastErrorText(objHandle: HCkRest): PWideChar; stdcall;
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
See the notes about PWideChar memory ownership and validity.
LastErrorXml
function CkRest__lastErrorXml(objHandle: HCkRest): PWideChar; stdcall;
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
See the notes about PWideChar memory ownership and validity.
topLastMethodSuccess
procedure CkRest_putLastMethodSuccess(objHandle: HCkRest; newPropVal: wordbool); stdcall;
Indicates the success or failure of the most recent method call: True means success, False means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
LastRedirectUrl
function CkRest__lastRedirectUrl(objHandle: HCkRest): PWideChar; stdcall;
Returns the redirect target from the most recently received response. The value comes from the response Location header. If the most recent response was not a redirect or did not contain a Location header, this property is empty.
Rest does not automatically follow the redirect; send a new request explicitly, reconnecting first if the target host changes.See the notes about PWideChar memory ownership and validity.
topLastRequestHeader
function CkRest__lastRequestHeader(objHandle: HCkRest): PWideChar; stdcall;
Returns the HTTP header fields from the most recently composed request, excluding the request line. The request line is available separately in LastRequestStartLine.
A failed Connect does not clear this value. It continues to describe the last request that was composed and sent.
See the notes about PWideChar memory ownership and validity.
topLastRequestStartLine
function CkRest__lastRequestStartLine(objHandle: HCkRest): PWideChar; stdcall;
Returns the request line from the most recently composed request. It contains the HTTP method, request target, and HTTP version, for example:
GET /v1/items?limit=10 HTTP/1.1
A failed Connect does not clear this value. It continues to describe the last request that was composed and sent.
See the notes about PWideChar memory ownership and validity.
topNumResponseHeaders
Returns the number of response header field occurrences. Enumerate them with zero-based indexes using ResponseHdrName and ResponseHdrValue.
A failed Connect does not reset this count; it remains the count for the last received HTTP response.
PartSelector
procedure CkRest_putPartSelector(objHandle: HCkRest; newPropVal: PWideChar); stdcall;
function CkRest__partSelector(objHandle: HCkRest): PWideChar; stdcall;
Selects the multipart entity or part targeted by multipart-building operations such as AddHeader, RemoveHeader, and the SetMultipartBody* methods.
| Value | Selected target |
|---|---|
| The top-level request entity |
0 | The top-level request entity |
1 | The first multipart subpart |
2 | The second multipart subpart |
1.2 | The second child within the first subpart |
The value 0, like the empty string, selects the top-level request entity. A nonnumeric selector is invalid. A body assignment can create a higher-numbered part even when lower-numbered parts do not yet exist.
See the notes about PWideChar memory ownership and validity.
PercentDoneOnSend
procedure CkRest_putPercentDoneOnSend(objHandle: HCkRest; newPropVal: wordbool); stdcall;
Applies to the full-request methods that both upload a request and download a response. It selects which direction is represented by percent-complete events.
False(default): progress refers to receiving the response body.True: progress refers to sending the request body.
ResponseHeader
function CkRest__responseHeader(objHandle: HCkRest): PWideChar; stdcall;
Returns the HTTP response header fields from the most recently received response, excluding the status line.
ResponseStatusCode and ResponseStatusText.Repeated fields remain separate and in received order. The field-name casing is preserved. A failed Connect does not clear this value; it continues to describe the last received HTTP response.
See the notes about PWideChar memory ownership and validity.
topResponseStatusCode
Returns the numeric HTTP status code from the most recently received response, such as 200, 404, or 503.
400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Connect does not clear this property. It continues to report the status of the last HTTP response that was actually received.ResponseStatusText
function CkRest__responseStatusText(objHandle: HCkRest): PWideChar; stdcall;
Returns the reason phrase associated with the most recently received HTTP status code, such as OK or Not Found.
Connect does not clear this property; it remains associated with the last received HTTP response.See the notes about PWideChar memory ownership and validity.
StreamNonChunked
procedure CkRest_putStreamNonChunked(objHandle: HCkRest; newPropVal: wordbool); stdcall;
Controls whether streaming uploads use a Content-Length header instead of HTTP/1.1 chunked transfer encoding when the total body size is known. The default is True.
When True and the stream length can be determined—for example, a file stream—Chilkat sends a non-chunked request. When False, Chilkat uses Transfer-Encoding: chunked. If the stream length is unknown, chunked transfer may still be required.
UncommonOptions
procedure CkRest_putUncommonOptions(objHandle: HCkRest; newPropVal: PWideChar); stdcall;
function CkRest__uncommonOptions(objHandle: HCkRest): PWideChar; stdcall;
Provides opt-in compatibility settings for uncommon requirements. The default is the empty string. Supply one or more comma-separated keywords:
| Keyword | Effect |
|---|---|
AllowDuplicateQueryParams | Allows AddQueryParam to append another parameter having the same name instead of replacing the existing one. |
AllowInsecureBasicAuth | Allows Basic authentication over a non-TLS remote connection. By default, Basic authentication is allowed only over TLS, an SSH tunnel, or localhost. |
DisableTls13 | Disables TLS 1.3 so negotiation is limited to TLS 1.2 or earlier supported versions. |
ProtectFromVpn | On Android, attempts to bypass an installed or active VPN for this connection. |
See the notes about PWideChar memory ownership and validity.
VerboseLogging
procedure CkRest_putVerboseLogging(objHandle: HCkRest; newPropVal: wordbool); stdcall;
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.
Version
function CkRest__version(objHandle: HCkRest): PWideChar; stdcall;
Version of the component/library, such as "10.1.0"
See the notes about PWideChar memory ownership and validity.
Methods
AddHeader
name: PWideChar;
value: PWideChar): wordbool; stdcall;
Adds an HTTP request header using name as the field name and value as the field value. If a request header with the same name is already present for the selected part, its value is replaced.
name—for example, Content-Type—and not the trailing colon. For multipart requests, PartSelector determines whether the header is added to the top-level request or to a MIME part.Request headers persist across requests until removed or cleared. Adding the same header again replaces its current value.
PartSelector. Use an empty selector or 0 for top-level request headers; select a part before adding that part's headers.Returns True for success, False for failure.
AddMwsSignature
httpVerb: PWideChar;
uriPath: PWideChar;
domain: PWideChar;
mwsSecretKey: PWideChar): wordbool; stdcall;
Computes the Amazon Marketplace Web Service (MWS) request signature using the secret key in mwsSecretKey and adds or replaces the Signature query parameter. Call this after all other MWS request parameters have been added.
httpVerb is the HTTP method, uriPath is the MWS resource path, and domain is the request domain. httpVerb and uriPath should match the values used by the request-sending method. The method also adds or replaces the Timestamp parameter using the current system time.
SetAuthAws.Returns True for success, False for failure.
AddPathParam
name: PWideChar;
value: PWideChar): wordbool; stdcall;
Adds or replaces a path-substitution parameter. Before a request is sent, occurrences of name in the supplied request path are replaced by value.
For example, setting name to fileId and value to abc123 transforms /drive/v3/files/fileId into /drive/v3/files/abc123.
name; braces are not required unless they are part of the placeholder text you choose.Matching is case-sensitive and literal. Every occurrence of name is replaced, substitutions are applied in the order they were added, and replacement applies to the entire uriPath string, including any query portion.
/, ?, and # remain delimiters, and existing percent escapes are preserved. Percent-encode reserved characters before calling this method when they are intended to be data.Path substitutions persist across requests until replaced or removed with ClearAllPathParams.
Returns True for success, False for failure.
AddQueryParam
name: PWideChar;
value: PWideChar): wordbool; stdcall;
Adds or replaces a query-string parameter using name as the parameter name and value as its value. The stored query parameters are incorporated into the request target when a request is sent.
tag=red&tag=blue, include AllowDuplicateQueryParams in UncommonOptions.name and value are unencoded text. Chilkat percent-encodes the parameter name and value when composing the request target. For example, a space becomes %20, a literal plus sign becomes %2B, and a literal percent sign becomes %25. Existing percent escapes supplied to this method are therefore encoded again. Parameters persist across ordinary requests until removed or cleared.Parameter names are case-sensitive. Adding the same exact name again replaces the existing value unless AllowDuplicateQueryParams is enabled in UncommonOptions.
Returns True for success, False for failure.
AddQueryParams
queryString: PWideChar): wordbool; stdcall;
Adds multiple query parameters from the query-string text in queryString. Use the form field1=value1&field2=value2&field3=value3.
queryString must already be percent-encoded as required for a URL query string. Do not include a leading ?. For individual name/value pairs, AddQueryParam is usually clearer.The input is parsed as an already URL-encoded query string and then normalized when the request is composed. A plus sign is interpreted as a space and is emitted as %20; encoded delimiters such as %26 remain data; an item without an equals sign is treated as a parameter with an empty value.
Parameters added by this method persist across ordinary requests. When ARG2 of a request method already contains a query string, those inline parameters appear first, followed by the parameters stored in the Rest object.
Returns True for success, False for failure.
AddQueryParamSb
name: PWideChar;
value: HCkStringBuilder): wordbool; stdcall;
Adds or replaces a query-string parameter named by name. The parameter value is read from the StringBuilder in value.
AllowDuplicateQueryParams in UncommonOptions to retain repeated names.name and the text in value are unencoded text. Chilkat percent-encodes the parameter name and value when composing the request target. For example, a space becomes %20, a literal plus sign becomes %2B, and a literal percent sign becomes %25. Existing percent escapes supplied to this method are therefore encoded again. Parameters persist across ordinary requests until removed or cleared.Parameter names are case-sensitive. Adding the same exact name again replaces the existing value unless AllowDuplicateQueryParams is enabled in UncommonOptions.
Returns True for success, False for failure.
ClearAllHeaders
Removes all HTTP request headers previously added to this object.
The method clears headers only from the entity selected by PartSelector. Clearing top-level headers also clears the Authorization property. Automatically generated fields such as Host and Content-Length may be added again when the next request is composed.
Returns True for success, False for failure.
ClearAllParts
Removes all multipart subparts from the request under construction. This is useful when reusing the same REST object after sending a multipart request.
This also resets PartSelector to the empty string and releases the configured multipart bodies and part streams.
Returns True for success, False for failure.
ClearAllPathParams
Removes all path-substitution parameters previously added with AddPathParam.
After clearing, placeholder text in later request paths is sent unchanged.
Returns True for success, False for failure.
ClearAllQueryParams
Removes all query parameters previously added to this object.
This clears the stored query/form parameter collection. It does not remove a query string written directly in the uriPath argument of a request method.
Returns True for success, False for failure.
ClearAuth
Clears authentication providers and credentials previously configured through this class's SetAuth* methods.
This removes the active authentication provider and clears the manually configured Authorization value.
Returns True for success, False for failure.
ClearResponseBodyStream
Clears the response-stream destination previously configured by SetResponseBodyStream. Subsequent full-request methods return or store the response body normally instead of streaming it to that destination.
Clearing the destination does not alter the Stream object itself.
Connect
hostname: PWideChar;
port: Integer;
tls: wordbool;
autoReconnect: wordbool): wordbool; stdcall;
Establishes the initial TCP connection to the REST server. hostname is a DNS hostname or an IPv4/IPv6 address, port is the server port, and tls specifies whether the connection uses TLS. Common combinations are port 80 with tls set to False, and port 443 with tls set to True.
If autoReconnect is True, subsequent requests may automatically reconnect when the existing connection is no longer usable. If autoReconnect is False, a lost connection causes the request to fail until the application explicitly reconnects.
hostname is not a URL. For https://api.example.com/v1/items, pass api.example.com. The request path is supplied separately to the request method.Connect is intended for a direct connection. For HTTP or SOCKS proxies, SSH tunneling, client certificates, custom socket routing, or other advanced connection setup, establish a connected Socket and pass it to UseConnection.autoReconnect is True, Chilkat can establish a new connection before a later request after the previous connection has closed. This option should not be interpreted as a promise to replay a request that failed after transmission began.ConnectFailReason to 0. A failed Connect does not clear the HTTP response and last-request properties from an earlier completed exchange; those properties continue to describe the last HTTP request/response, not the failed connection attempt.Returns True for success, False for failure.
ConnectAsync (1)
hostname: PWideChar;
port: Integer;
tls: wordbool;
autoReconnect: wordbool): HCkTask; stdcall;
Creates an asynchronous task to call the Connect method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
Disconnect
maxWaitMs: Integer): wordbool; stdcall;
Closes the current HTTP connection, if one is open. maxWaitMs is the maximum number of milliseconds to wait while attempting a clean shutdown.
UseConnection, calling Disconnect also disconnects that Socket. If automatic reconnection was enabled, a later request may reconnect it.Returns True for success, False for failure.
DisconnectAsync (1)
Creates an asynchronous task to call the Disconnect method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestBd
httpVerb: PWideChar;
uriPath: PWideChar;
binData: HCkBinData;
responseBody: HCkStringBuilder): wordbool; stdcall;
Sends a complete request whose binary body is read from the BinData in binData. The text response body replaces the existing contents of the StringBuilder in responseBody.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.responseBody is cleared and replaced with the textual response body.
Returns True for success, False for failure.
FullRequestBdAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
binData: HCkBinData;
responseBody: HCkStringBuilder): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestFormUrlEncoded
httpVerb: PWideChar;
uriPath: PWideChar;
outStr: HCkString): wordbool; stdcall;
function CkRest__fullRequestFormUrlEncoded(objHandle: HCkRest;
httpVerb: PWideChar;
uriPath: PWideChar): PWideChar; stdcall;
Sends a complete application/x-www-form-urlencoded request. The form body is built from the parameters previously added with AddQueryParam or AddQueryParams. The request Content-Type is set to application/x-www-form-urlencoded. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqFormUrlEncoded, ReadResponseHeader, and ReadRespBodyString in sequence.
For full-request methods, PercentDoneOnSend selects whether percent-complete events refer to sending the request body or receiving the response body.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Parameters written directly in uriPath remain in the URL query string. Parameters stored through AddQueryParam, AddQueryParamSb, or AddQueryParams are encoded into the form body. After the form request is sent, this stored parameter collection is cleared.
Content-Type to application/x-www-form-urlencoded. That request-header value remains configured for later requests until it is replaced or cleared.Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
FullRequestFormUrlEncodedAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestFormUrlEncoded method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestMultipart
httpVerb: PWideChar;
uriPath: PWideChar;
outStr: HCkString): wordbool; stdcall;
function CkRest__fullRequestMultipart(objHandle: HCkRest;
httpVerb: PWideChar;
uriPath: PWideChar): PWideChar; stdcall;
Sends a complete multipart request using the parts and part headers configured through PartSelector, AddHeader, and the multipart-body methods. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqMultipart, ReadResponseHeader, and ReadRespBodyString in sequence.
For full-request methods, PercentDoneOnSend selects whether percent-complete events refer to sending the request body or receiving the response body.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.multipart/form-data.The request fails if no multipart subparts are configured.
Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
FullRequestMultipartAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestMultipart method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestNoBody
httpVerb: PWideChar;
uriPath: PWideChar;
outStr: HCkString): wordbool; stdcall;
function CkRest__fullRequestNoBody(objHandle: HCkRest;
httpVerb: PWideChar;
uriPath: PWideChar): PWideChar; stdcall;
Sends a complete request with no request body. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqNoBody, ReadResponseHeader, and ReadRespBodyString in sequence.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
FullRequestNoBodyAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestNoBody method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestNoBodyBd
httpVerb: PWideChar;
uriPath: PWideChar;
binData: HCkBinData): wordbool; stdcall;
Sends a complete request without a request body and stores the binary response body in the BinData in binData, replacing its previous contents.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.binData is cleared and replaced with the binary response body.
Returns True for success, False for failure.
FullRequestNoBodyBdAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
binData: HCkBinData): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestNoBodyBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestNoBodySb
httpVerb: PWideChar;
uriPath: PWideChar;
sb: HCkStringBuilder): wordbool; stdcall;
Sends a complete request without a request body and stores the text response body in the StringBuilder in sb, replacing its previous contents.
This is the StringBuilder form of FullRequestNoBody.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.sb is cleared and replaced with the textual response body.
Returns True for success, False for failure.
FullRequestNoBodySbAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
sb: HCkStringBuilder): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestNoBodySb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestSb
httpVerb: PWideChar;
uriPath: PWideChar;
requestBody: HCkStringBuilder;
responseBody: HCkStringBuilder): wordbool; stdcall;
Sends a complete request whose text body is read from the StringBuilder in requestBody. The text response body replaces the existing contents of the StringBuilder in responseBody.
This is the StringBuilder form of FullRequestString.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.responseBody is cleared and replaced with the response body.
Returns True for success, False for failure.
FullRequestSbAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
requestBody: HCkStringBuilder;
responseBody: HCkStringBuilder): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestSb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestStream
httpVerb: PWideChar;
uriPath: PWideChar;
stream: HCkStream;
outStr: HCkString): wordbool; stdcall;
function CkRest__fullRequestStream(objHandle: HCkRest;
httpVerb: PWideChar;
uriPath: PWideChar;
stream: HCkStream): PWideChar; stdcall;
Sends a complete request whose body is read from the Stream in stream. Streaming is appropriate for large uploads because the entire request body need not be held in memory. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqStreamBody, ReadResponseHeader, and ReadRespBodyString in sequence.
For full-request methods, PercentDoneOnSend selects whether percent-complete events refer to sending the request body or receiving the response body.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
FullRequestStreamAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
stream: HCkStream): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestStream method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestString
httpVerb: PWideChar;
uriPath: PWideChar;
bodyText: PWideChar;
outStr: HCkString): wordbool; stdcall;
function CkRest__fullRequestString(objHandle: HCkRest;
httpVerb: PWideChar;
uriPath: PWideChar;
bodyText: PWideChar): PWideChar; stdcall;
Sends a complete request whose text body is supplied in bodyText, such as JSON, XML, or plain text. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqStringBody, ReadResponseHeader, and ReadRespBodyString in sequence.
For full-request methods, PercentDoneOnSend selects whether percent-complete events refer to sending the request body or receiving the response body.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
FullRequestStringAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
bodyText: PWideChar): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestString method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
GetLastDebugRequest
Copies the fully composed HTTP request generated while DebugMode was True into the BinData in bd. The captured data includes the request line, headers, and body that would have been sent.
bd is cleared and replaced. The captured bytes are the complete composed HTTP/1.1 request, including chunk framing when a streaming request uses Transfer-Encoding: chunked.
Returns True for success, False for failure.
GetLastJsonData
Copies operation-specific diagnostic or result information from the most recently completed method into the JsonObject in json. Many methods do not produce additional JSON details, in which case the object is empty.
LoadTaskCaller
Loads into this object the caller associated with the Task in task. task must be a task returned by an asynchronous method of this class.
Returns True for success, False for failure.
topReadRespBd
Reads the response body as raw bytes into the BinData in responseBody, replacing its previous contents. Call this after ReadResponseHeader.
HEAD response. A 204 No Content response is handled as a successful empty body.Returns True for success, False for failure.
ReadRespBdAsync (1)
Creates an asynchronous task to call the ReadRespBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadRespBodyStream
stream: HCkStream;
autoSetStreamCharset: wordbool): wordbool; stdcall;
Reads the response body into the Stream supplied in stream. Call this after ReadResponseHeader.
If autoSetStreamCharset is True and the response is textual, the stream's StringCharset is set from the charset parameter in the response Content-Type header when one is present. autoSetStreamCharset has no effect for binary responses.
HEAD response. A 204 No Content response is handled as a successful empty body.Returns True for success, False for failure.
ReadRespBodyStreamAsync (1)
stream: HCkStream;
autoSetStreamCharset: wordbool): HCkTask; stdcall;
Creates an asynchronous task to call the ReadRespBodyStream method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadRespBodyString
outStr: HCkString): wordbool; stdcall;
function CkRest__readRespBodyString(objHandle: HCkRest): PWideChar; stdcall;
Reads the response body as text and returns it. Call this only after ReadResponseHeader has returned the response status code.
ReadRespBd or ReadRespBodyStream for binary or very large content.HEAD response. A 204 No Content response is handled as a successful empty body.Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
ReadRespBodyStringAsync (1)
Creates an asynchronous task to call the ReadRespBodyString method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadRespChunkBd
minSize: Integer;
bd: HCkBinData): Integer; stdcall;
After ReadResponseHeader has been called, reads the next chunk of the response body and appends the received bytes to the BinData in bd. The call waits until at least minSize bytes are available, unless the response ends first. The final chunk may contain fewer than minSize bytes, including zero bytes.
| Return value | Meaning |
|---|---|
-1 | The read failed; inspect LastErrorText. |
0 | The remaining response bytes were returned and the response body is complete. |
1 | A chunk was returned and more response bytes remain. |
Returns True for success, False for failure.
ReadRespChunkBdAsync (1)
minSize: Integer;
bd: HCkBinData): HCkTask; stdcall;
Creates an asynchronous task to call the ReadRespChunkBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadResponseHeader
Reads the HTTP response status line and header fields. The returned integer is the HTTP status code, such as 200, 404, or 500. A return value of -1 means that no HTTP response was received because a transport or protocol error occurred.
After this method returns a status code, inspect ResponseHeader, ResponseStatusCode, ResponseStatusText, and the response-header access methods. If the response has a body, read it with ReadRespBodyString, ReadRespBd, ReadRespBodyStream, or another appropriate body-reading method.
HEAD response. A 204 No Content response is handled as a successful empty body.ReadResponseHeaderAsync (1)
Creates an asynchronous task to call the ReadResponseHeader method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadRespSb
Reads the response body as text into the StringBuilder in responseBody, replacing its previous contents. Call this after ReadResponseHeader.
HEAD response. A 204 No Content response is handled as a successful empty body.Returns True for success, False for failure.
ReadRespSbAsync (1)
responseBody: HCkStringBuilder): HCkTask; stdcall;
Creates an asynchronous task to call the ReadRespSb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
RemoveHeader
name: PWideChar): wordbool; stdcall;
Removes all request headers named by name from the request level selected by PartSelector.
Header-name matching is case-insensitive, and all matching occurrences are removed.
Returns True for success, False for failure.
RemoveQueryParam
name: PWideChar): wordbool; stdcall;
Removes all query parameters whose name matches name.
Parameter-name matching is case-sensitive. All parameters having the exact name are removed. A True return value indicates that the operation completed successfully; it does not guarantee that a matching parameter existed.
Returns True for success, False for failure.
ResponseHdrByName
name: PWideChar;
outStr: HCkString): wordbool; stdcall;
function CkRest__responseHdrByName(objHandle: HCkRest;
name: PWideChar): PWideChar; stdcall;
Returns the value of the response header field named by name. HTTP header field names are case-insensitive.
NumResponseHeaders, ResponseHdrName, and ResponseHdrValue to enumerate every field occurrence.If the response contains the same field more than once, this method returns the first matching value. Enumerate the header collection to obtain all occurrences, especially for fields such as Set-Cookie.
Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
ResponseHdrName
index: Integer;
outStr: HCkString): wordbool; stdcall;
function CkRest__responseHdrName(objHandle: HCkRest;
index: Integer): PWideChar; stdcall;
Returns the field name of the response header at zero-based index index. Valid indexes range from 0 through NumResponseHeaders minus one.
Enumeration preserves the response-field order and the field-name casing received from the server. Repeated fields occupy separate indexes.
Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
ResponseHdrValue
index: Integer;
outStr: HCkString): wordbool; stdcall;
function CkRest__responseHdrValue(objHandle: HCkRest;
index: Integer): PWideChar; stdcall;
Returns the field value of the response header at zero-based index index. Use the same index with ResponseHdrName to obtain the corresponding field name.
Repeated response fields occupy separate indexes and are returned in received order.
Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
SendReqBd
httpVerb: PWideChar;
uriPath: PWideChar;
body: HCkBinData): wordbool; stdcall;
Sends a request whose binary body is read from the BinData in body.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Returns True for success, False for failure.
SendReqBdAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
body: HCkBinData): HCkTask; stdcall;
Creates an asynchronous task to call the SendReqBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqFormUrlEncoded
httpVerb: PWideChar;
uriPath: PWideChar): wordbool; stdcall;
Sends an application/x-www-form-urlencoded request. The request body is built from the parameters added with AddQueryParam or AddQueryParams. Any manually supplied Content-Type value is replaced with application/x-www-form-urlencoded.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Parameters written directly in uriPath remain in the URL query string. Parameters stored through AddQueryParam, AddQueryParamSb, or AddQueryParams are encoded into the form body. After the form request is sent, this stored parameter collection is cleared.
Content-Type to application/x-www-form-urlencoded. That request-header value remains configured for later requests until it is replaced or cleared.Returns True for success, False for failure.
SendReqFormUrlEncodedAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar): HCkTask; stdcall;
Creates an asynchronous task to call the SendReqFormUrlEncoded method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqMultipart
httpVerb: PWideChar;
uriPath: PWideChar): wordbool; stdcall;
Sends a multipart request using the parts configured with PartSelector, AddHeader, and the multipart-body methods.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.multipart/form-data.The request fails if no multipart subparts are configured.
Returns True for success, False for failure.
SendReqMultipartAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar): HCkTask; stdcall;
Creates an asynchronous task to call the SendReqMultipart method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqNoBody
httpVerb: PWideChar;
uriPath: PWideChar): wordbool; stdcall;
Sends a request without a request body.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Returns True for success, False for failure.
SendReqNoBodyAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar): HCkTask; stdcall;
Creates an asynchronous task to call the SendReqNoBody method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqSb
httpVerb: PWideChar;
uriPath: PWideChar;
bodySb: HCkStringBuilder): wordbool; stdcall;
Sends a request whose text body is read from the StringBuilder in bodySb. Set the request Content-Type header to identify the body format.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.Returns True for success, False for failure.
SendReqSbAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
bodySb: HCkStringBuilder): HCkTask; stdcall;
Creates an asynchronous task to call the SendReqSb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqStreamBody
httpVerb: PWideChar;
uriPath: PWideChar;
stream: HCkStream): wordbool; stdcall;
Sends a request whose body is read from the Stream in stream. The stream may supply text or binary data; set the request Content-Type header as required by the API.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Returns True for success, False for failure.
SendReqStreamBodyAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
stream: HCkStream): HCkTask; stdcall;
Creates an asynchronous task to call the SendReqStreamBody method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqStringBody
httpVerb: PWideChar;
uriPath: PWideChar;
bodyText: PWideChar): wordbool; stdcall;
Sends a request whose text body is supplied in bodyText, such as JSON, XML, form-independent text, or another textual representation. Set the request Content-Type header to identify the body format expected by the server.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.Returns True for success, False for failure.
SendReqStringBodyAsync (1)
httpVerb: PWideChar;
uriPath: PWideChar;
bodyText: PWideChar): HCkTask; stdcall;
Creates an asynchronous task to call the SendReqStringBody method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SetAuthAws
Associates the AuthAws provider in authProvider with this REST object. Chilkat uses the provider to sign each AWS request after the request method, path, query parameters, headers, and body are known. The application does not need to construct the Authorization header manually.
Returns True for success, False for failure.
SetAuthAzureSas
authProvider: HCkAuthAzureSAS): wordbool; stdcall;
Associates the AuthAzureSAS provider in authProvider with this REST object. Chilkat automatically adds an Authorization: SharedAccessSignature ... header to subsequent requests.
Returns True for success, False for failure.
SetAuthAzureStorage
authProvider: HCkAuthAzureStorage): wordbool; stdcall;
Associates the AuthAzureStorage provider in authProvider with this REST object. Chilkat automatically applies the Azure Storage authorization information required for each request.
Returns True for success, False for failure.
SetAuthBasic
username: PWideChar;
password: PWideChar): wordbool; stdcall;
Configures HTTP Basic authentication using username as the username and password as the password. Chilkat automatically generates an Authorization: Basic ... header for subsequent requests.
AllowInsecureBasicAuth in UncommonOptions exists only for exceptional compatibility needs.Some APIs use an account ID, client ID, API key, token, or secret in place of a traditional username or password; follow the service documentation.
Authorization header when each request is composed and takes precedence over a value set through the Authorization property or AddHeader.Returns True for success, False for failure.
SetAuthBasicSecure
username: HCkSecureString;
password: HCkSecureString): wordbool; stdcall;
Configures HTTP Basic authentication using the SecureString objects in username and password for the username and password. The resulting request behavior is the same as SetAuthBasic.
SecureString reduces unnecessary exposure of the credential text in ordinary application strings. Basic authentication must still be protected by TLS.Authorization header when each request is composed and takes precedence over a manually configured Authorization value.Returns True for success, False for failure.
SetAuthGoogle
Associates the AuthGoogle provider in authProvider with this REST object. Chilkat uses the provider to add the Google authentication information needed by subsequent API requests.
Returns True for success, False for failure.
SetAuthOAuth1
authProvider: HCkOAuth1;
useQueryParams: wordbool): wordbool; stdcall;
Associates the OAuth1 provider in authProvider with this REST object for OAuth 1.0 or OAuth 1.0a request signing.
If useQueryParams is True, the OAuth parameters and signature are placed in the query string. If useQueryParams is False, they are placed in the Authorization header.
Returns True for success, False for failure.
SetAuthOAuth2
Associates the OAuth2 provider in authProvider with this REST object. The provider must contain a valid access token. Chilkat then adds an Authorization: Bearer <access-token> header to each request.
The access token may be obtained through an OAuth flow or loaded from previously saved token data. Token acquisition, refresh, expiration, and scope requirements are determined by the authorization server.
AddHeader. Do not configure both approaches for the same request because they compete for the same Authorization header.OAuth2 object is consulted when each request is composed rather than copied at setup time. Keep it alive while the Rest object uses it. Changing its AccessToken changes the bearer token used by subsequent requests.Authorization value.Returns True for success, False for failure.
SetMultipartBodyBd
Sets the binary body of the multipart part identified by PartSelector from the BinData in bodyData.
Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.
Returns True for success, False for failure.
SetMultipartBodySb
bodySb: HCkStringBuilder): wordbool; stdcall;
Sets the text body of the multipart part identified by PartSelector from the StringBuilder in bodySb.
Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.
Returns True for success, False for failure.
SetMultipartBodyStream
Uses the Stream in stream as the body source for the multipart part identified by PartSelector.
Stream object alive. It is read from its current position and must be reset before reusing it for another upload.Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.
Returns True for success, False for failure.
SetMultipartBodyString
bodyText: PWideChar): wordbool; stdcall;
Sets the text body of the multipart part identified by PartSelector to bodyText.
AddHeader while the part is selected to set its Content-Type, Content-Disposition, and other part headers.Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.
Returns True for success, False for failure.
SetResponseBodyStream
expectedStatus: Integer;
autoSetStreamCharset: wordbool;
responseStream: HCkStream): wordbool; stdcall;
Configures a Stream destination for response bodies received by the full-request convenience methods. The body is written to responseStream only when the response status code matches expectedStatus.
If streaming occurs successfully, a string-returning full-request method returns OK. If streaming was selected but writing the body fails, it returns FAIL. If the status code does not match expectedStatus, the body is not streamed and remains available as the method's normal response text.
If autoSetStreamCharset is True and the response is textual, the destination stream's StringCharset is set from the response Content-Type charset when available. autoSetStreamCharset is ignored for binary responses.
expectedStatus value | Status codes that are streamed |
|---|---|
200 | Only 200 |
-200 | 200 through 299 |
-210 | 210 through 219 |
ClearResponseBodyStream to restore normal response-body handling.For Boolean-returning full-request methods, successful streaming returns True. A StringBuilder response output receives OK; a BinData response output is cleared. If the status does not match expectedStatus, the stream is not written and the method returns the response through its normal output.
The configuration remains active for later full-request calls until ClearResponseBodyStream is called.
Returns True for success, False for failure.
UseConnection
connection: HCkSocket;
autoReconnect: wordbool): wordbool; stdcall;
Uses the already-connected Socket in connection as the transport for REST requests. The socket may represent a direct TCP or TLS connection, an HTTP or SOCKS proxy connection, an SSH-tunneled channel, or another connection configured through the Socket API.
autoReconnect controls automatic reconnection for later requests when the connection is no longer usable.
Connect for ordinary direct connections. Use UseConnection when the connection requires advanced Socket configuration.Rest object retains and operates on the supplied Socket. Keep the Socket object alive while it is attached. Calling Disconnect disconnects it; with autoReconnect set to True, a later request can reconnect the same Socket object.Returns True for success, False for failure.
Events
AbortCheck
Enables a method call to be aborted by triggering the AbortCheck event at intervals defined by the HeartbeatMs property. If HeartbeatMs is set to its default value of 0, no events will occur. For instance, set HeartbeatMs to 200 to trigger 5 AbortCheck events per second. Return True to abort; return False to continue (not abort)
PercentDone
This provides the percentage completion for any method involving network communications or time-consuming processing, assuming the progress can be measured as a percentage. This event is triggered only when it's possible and logical to express the operation's progress as a percentage. The pctDone argument will range from 1 to 100. For methods that finish quickly, the number of PercentDone callbacks may vary, but the final callback will have pctDone equal to 100. For longer operations, callbacks will not exceed one per percentage point (e.g., 1, 2, 3, ..., 98, 99, 100).
The PercentDone callback also acts as an AbortCheck event. For fast methods where PercentDone fires, an AbortCheck event may not trigger since the PercentDone callback already provides an opportunity to abort. For longer operations, where time between PercentDone callbacks is extended, AbortCheck callbacks enable more responsive operation termination.
Return True to abort; return False to continue (not abort)
ProgressInfo
This event callback provides tag name/value pairs that detail what occurs during a method call. To discover existing tag names, create code to handle the event, emit the pairs, and review them. Most tag names are self-explanatory.
Note: Some Chilkat methods don't fire any ProgressInfo events.
TaskCompleted
Called from the background thread when an asynchronous task completes.
Deprecated
FullRequestBinary Deprecated
httpVerb: PWideChar;
uriPath: PWideChar;
bodyBytes: HCkByteData;
outStr: HCkString): wordbool; stdcall;
function CkRest__fullRequestBinary(objHandle: HCkRest;
httpVerb: PWideChar;
uriPath: PWideChar;
bodyBytes: HCkByteData): PWideChar; stdcall;
Sends a complete request whose body is the binary data in bodyBytes. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqBinaryBody, ReadResponseHeader, and ReadRespBodyString in sequence.
For full-request methods, PercentDoneOnSend selects whether percent-complete events refer to sending the request body or receiving the response body.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.FullRequestBd uses BinData and avoids language-specific byte-array limitations.Returns True for success, False for failure.
See the notes about PWideChar memory ownership and validity.
topFullRequestBinaryAsync Deprecated (1)
httpVerb: PWideChar;
uriPath: PWideChar;
bodyBytes: HCkByteData): HCkTask; stdcall;
Creates an asynchronous task to call the FullRequestBinary method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
LastJsonData
Deprecated. Use GetLastJsonData instead.
Returns a JSON object containing operation-specific details from the most recently completed method when such details are available. Many operations produce an empty object.
Returns nil on failure
ReadRespBodyBinary Deprecated
Reads the response body as raw bytes. Call this only after ReadResponseHeader has returned the response status code.
ReadRespBd stores the bytes in BinData.HEAD response. A 204 No Content response is handled as a successful empty body.Returns True for success, False for failure.
topReadRespBodyBinaryAsync Deprecated (1)
Creates an asynchronous task to call the ReadRespBodyBinary method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
RedirectUrl
Deprecated. Use LastRedirectUrl instead.
If the most recent response is a redirect and contains a Location header, returns that redirect URL.
Returns nil on failure
SendReqBinaryBody Deprecated
httpVerb: PWideChar;
uriPath: PWideChar;
body: HCkByteData): wordbool; stdcall;
Sends a request whose body is the binary byte array in body.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.SendReqBd uses BinData.Returns True for success, False for failure.
topSendReqBinaryBodyAsync Deprecated (1)
httpVerb: PWideChar;
uriPath: PWideChar;
body: HCkByteData): HCkTask; stdcall;
Creates an asynchronous task to call the SendReqBinaryBody method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SetMultipartBodyBinary Deprecated
bodyData: HCkByteData): wordbool; stdcall;
Sets the selected multipart part body to the binary bytes in bodyData. The target part is identified by PartSelector.
AddHeader to set fields such as Content-Disposition and Content-Type. For new code, SetMultipartBodyBd uses BinData.Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.
Returns True for success, False for failure.
top