--- product: Chilkat product_version: 11.7.0 language: delphidll language_label: Delphi DLL class: HttpCurl license: bundle deprecated: false reference_html: https://www.chilkatsoft.com/refdoc/dd_CkHttpCurlRef.html --- # Chilkat HttpCurl — Delphi DLL — v11.7.0 > Chilkat 11.7.0 · language=delphidll · class=HttpCurl > Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0//classes/HttpCurl.md`. > Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/delphidll/guide.md`. ## Purpose curl-style HTTP requests with dependency resolution **Run curl commands and automatically resolve values needed by later requests** The `Chilkat.HttpCurl` class executes HTTP requests expressed as curl commands, with support for variable substitution, reusable curl functions, automatic dependency resolution, response extraction, and structured diagnostics. Variables such as `{{access_token}}`, `{{site_id}}`, or `{{drive_id}}` can appear in URLs, headers, query parameters, request bodies, the JSON paths that extract values from a response, and the local file path a response is written to. If a variable is not yet known, `HttpCurl` can build an execution plan from previously defined curl functions, run the prerequisite requests, extract values from JSON responses, and then execute the final target request. **Define dependencies** Use `AddFunction` with `AddOutput` or `AddOutput2`. **Manage variables** Use `SetVar`, `GetVar`, `ClearVar`, and `GetAllVars`. **Preview execution** Use `ExaminePlan` or `ToRawRequest` before sending. **Read responses** Get text, binary, JSON, XML, or stream directly to a file. After `DoYourThing` completes, check `StatusCode` and retrieve the response using the appropriate getter. If something fails, `FailReason`, `FailedCurl`, and `LastErrorText` help identify the failed step and the reason. **Note:** `Chilkat.HttpCurl` is not derived from curl/libcurl and does not wrap libcurl. It accepts curl-style command text and executes the request using Chilkat’s own HTTP implementation. For an extended overview, see [HttpCurl Class Overview](https://www.chilkatsoft.com/httpcurl_class_overview.asp). **See also:** - [HttpCurl Overview](https://www.chilkatsoft.com/httpcurl_overview.asp) — concepts, variable substitution, dependency resolution, and workflow examples. - [Dependency Engine](https://www.chilkatsoft.com/curl_dependency_engine.asp) — how execution plans are derived, unknown variables are resolved, and cached variables are managed. ## Object creation, unlocking and error handling **Create/Dispose** ```pascal var myObject: HCkHttpCurl; begin myObject := CkHttpCurl_Create(); // ... CkHttpCurl_Dispose(myObject); end; ``` `function CkHttpCurl_Create: HCkHttpCurl; stdcall;` Creates an instance of the HCkHttpCurl object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page. `procedure CkHttpCurl_Dispose(handle: HCkHttpCurl); stdcall;` Objects created by calling CkHttpCurl_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Delphi DLL. ## Members common to every Chilkat class Documented once per language in `common-members.md`; listed here so this page is self-contained. | Property | Signature | Access | Meaning | |---|---|---|---| | `DebugLogFilePath` | `procedure CkHttpCurl_getDebugLogFilePath(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; procedure CkHttpCurl_putDebugLogFilePath(objHandle: HCkHttpCurl; newPropVal: PWideChar); stdcall; function CkHttpCurl__debugLogFilePath(objHandle: HCkHttpCurl): PWideChar; stdcall;` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. | | `LastErrorHtml` | `procedure CkHttpCurl_getLastErrorHtml(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__lastErrorHtml(objHandle: HCkHttpCurl): PWideChar; stdcall;` | read-only | Provides HTML-formatted information about the last called method or property. | | `LastErrorText` | `procedure CkHttpCurl_getLastErrorText(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__lastErrorText(objHandle: HCkHttpCurl): PWideChar; stdcall;` | read-only | Provides plain text information about the last called method or property. | | `LastErrorXml` | `procedure CkHttpCurl_getLastErrorXml(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__lastErrorXml(objHandle: HCkHttpCurl): PWideChar; stdcall;` | read-only | Provides XML-formatted information about the last called method or property. | | `LastMethodSuccess` | `function CkHttpCurl_getLastMethodSuccess(objHandle: HCkHttpCurl): wordbool; stdcall; procedure CkHttpCurl_putLastMethodSuccess(objHandle: HCkHttpCurl; newPropVal: wordbool); stdcall;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. | | `VerboseLogging` | `function CkHttpCurl_getVerboseLogging(objHandle: HCkHttpCurl): wordbool; stdcall; procedure CkHttpCurl_putVerboseLogging(objHandle: HCkHttpCurl; newPropVal: wordbool); stdcall;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. | | `Version` | `procedure CkHttpCurl_getVersion(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__version(objHandle: HCkHttpCurl): PWideChar; stdcall;` | read-only | Version of the component/library, such as "10.1.0" | ## Member index | Member | Kind | Signature | |---|---|---| | `EnableBodyVars` | property, read/write | `function CkHttpCurl_getEnableBodyVars(objHandle: HCkHttpCurl): wordbool; stdcall; procedure CkHttpCurl_putEnableBodyVars(objHandle: HCkHttpCurl; newPropVal: wordbool); stdcall;` | | `FailedCurl` | property, read-only | `procedure CkHttpCurl_getFailedCurl(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__failedCurl(objHandle: HCkHttpCurl): PWideChar; stdcall;` | | `FailReason` | property, read-only | `function CkHttpCurl_getFailReason(objHandle: HCkHttpCurl): Integer; stdcall;` | | `HeartbeatMs` | property, read/write | `function CkHttpCurl_getHeartbeatMs(objHandle: HCkHttpCurl): Integer; stdcall; procedure CkHttpCurl_putHeartbeatMs(objHandle: HCkHttpCurl; newPropVal: Integer); stdcall;` | | `ResponseBodyStr` | property, read-only | `procedure CkHttpCurl_getResponseBodyStr(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__responseBodyStr(objHandle: HCkHttpCurl): PWideChar; stdcall;` | | `ResponseFilePath` | property, read/write | `procedure CkHttpCurl_getResponseFilePath(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; procedure CkHttpCurl_putResponseFilePath(objHandle: HCkHttpCurl; newPropVal: PWideChar); stdcall; function CkHttpCurl__responseFilePath(objHandle: HCkHttpCurl): PWideChar; stdcall;` | | `ResponseHeader` | property, read-only | `procedure CkHttpCurl_getResponseHeader(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__responseHeader(objHandle: HCkHttpCurl): PWideChar; stdcall;` | | `StatusCode` | property, read-only | `function CkHttpCurl_getStatusCode(objHandle: HCkHttpCurl): Integer; stdcall;` | | `UncommonOptions` | property, read/write | `procedure CkHttpCurl_getUncommonOptions(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; procedure CkHttpCurl_putUncommonOptions(objHandle: HCkHttpCurl; newPropVal: PWideChar); stdcall; function CkHttpCurl__uncommonOptions(objHandle: HCkHttpCurl): PWideChar; stdcall;` | | `AddFunction` | method | `function CkHttpCurl_AddFunction(objHandle: HCkHttpCurl;     funcName: PWideChar;     curl: PWideChar): wordbool; stdcall;` | | `AddOutput` | method | `function CkHttpCurl_AddOutput(objHandle: HCkHttpCurl;     funcName: PWideChar;     jsonPath: PWideChar;     varName: PWideChar): wordbool; stdcall;` | | `AddOutput2` | method | `function CkHttpCurl_AddOutput2(objHandle: HCkHttpCurl;     funcName: PWideChar;     arrayPath: PWideChar;     wherePath: PWideChar;     whereValue: PWideChar;     caseSensitive: wordbool;     subPath: PWideChar;     varName: PWideChar): wordbool; stdcall;` | | `AddTargetOutput` | method | `procedure CkHttpCurl_AddTargetOutput(objHandle: HCkHttpCurl;     jsonPath: PWideChar;     varName: PWideChar) stdcall;` | | `ClearTargetOutput` | method | `procedure CkHttpCurl_ClearTargetOutput(objHandle: HCkHttpCurl;     varName: PWideChar) stdcall;` | | `ClearVar` | method | `procedure CkHttpCurl_ClearVar(objHandle: HCkHttpCurl;     varName: PWideChar) stdcall;` | | `DoYourThing` | method | `function CkHttpCurl_DoYourThing(objHandle: HCkHttpCurl;     targetCurl: PWideChar): wordbool; stdcall;` | | `ExaminePlan` | method | `function CkHttpCurl_ExaminePlan(objHandle: HCkHttpCurl;     curl: PWideChar;     json: HCkJsonObject): wordbool; stdcall;` | | `GetAllVars` | method | `procedure CkHttpCurl_GetAllVars(objHandle: HCkHttpCurl;     json: HCkJsonObject) stdcall;` | | `GetResponseBd` | method | `function CkHttpCurl_GetResponseBd(objHandle: HCkHttpCurl;     bd: HCkBinData): wordbool; stdcall;` | | `GetResponseHeaderField` | method | `function CkHttpCurl_GetResponseHeaderField(objHandle: HCkHttpCurl;     name: PWideChar;     outStr: HCkString): wordbool; stdcall; function CkHttpCurl__getResponseHeaderField(objHandle: HCkHttpCurl;     name: PWideChar): PWideChar; stdcall;` | | `GetResponseJarr` | method | `function CkHttpCurl_GetResponseJarr(objHandle: HCkHttpCurl;     jarr: HCkJsonArray): wordbool; stdcall;` | | `GetResponseJson` | method | `function CkHttpCurl_GetResponseJson(objHandle: HCkHttpCurl;     json: HCkJsonObject): wordbool; stdcall;` | | `GetResponseSb` | method | `function CkHttpCurl_GetResponseSb(objHandle: HCkHttpCurl;     sb: HCkStringBuilder): wordbool; stdcall;` | | `GetResponseXml` | method | `function CkHttpCurl_GetResponseXml(objHandle: HCkHttpCurl;     xml: HCkXml): wordbool; stdcall;` | | `GetVar` | method | `function CkHttpCurl_GetVar(objHandle: HCkHttpCurl;     varName: PWideChar;     outStr: HCkString): wordbool; stdcall; function CkHttpCurl__getVar(objHandle: HCkHttpCurl;     varName: PWideChar): PWideChar; stdcall;` | | `SetAuth` | method | `function CkHttpCurl_SetAuth(objHandle: HCkHttpCurl;     json: HCkJsonObject): wordbool; stdcall;` | | `SetVar` | method | `procedure CkHttpCurl_SetVar(objHandle: HCkHttpCurl;     varName: PWideChar;     varValue: PWideChar) stdcall;` | | `ToRawRequest` | method | `function CkHttpCurl_ToRawRequest(objHandle: HCkHttpCurl;     curlCommand: PWideChar;     sb: HCkStringBuilder): wordbool; stdcall;` | | `VarDefined` | method | `function CkHttpCurl_VarDefined(objHandle: HCkHttpCurl;     varName: PWideChar): wordbool; stdcall;` | ## Properties ### HttpCurl.EnableBodyVars `Chilkat 11.7.0 · delphidll · HttpCurl · EnableBodyVars · property · read/write · since 11.5.0` ```pascal function CkHttpCurl_getEnableBodyVars(objHandle: HCkHttpCurl): wordbool; stdcall; procedure CkHttpCurl_putEnableBodyVars(objHandle: HCkHttpCurl; newPropVal: wordbool); stdcall; ``` Enables variable substitution in the body of the request. The default value is `True`. ### HttpCurl.FailedCurl `Chilkat 11.7.0 · delphidll · HttpCurl · FailedCurl · property · read-only · since 11.5.0` ```pascal procedure CkHttpCurl_getFailedCurl(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__failedCurl(objHandle: HCkHttpCurl): PWideChar; stdcall; ``` Set to the specific curl command in the execution plan that failed. ### HttpCurl.FailReason `Chilkat 11.7.0 · delphidll · HttpCurl · FailReason · property · read-only · since 11.5.0` ```pascal function CkHttpCurl_getFailReason(objHandle: HCkHttpCurl): Integer; stdcall; ``` Set to an integer value indicating the reason for failure for the methods `DoYourThing` and `ExaminePlan` Possible values are: 0. No error - the method succeeded or hasn't yet been called. 1. curl command syntax error. 2. HTTP response status code indidcates an authentication (401) or authorization (403) error. 3. HTTP response status code indicates an error, but not an authentication or authorization error. 4. HTTP communications failure. 5. Impossible to derive an execution plan from defined outputs and inputs. 6. A step in the execution plan did not resolve any dependency variables. 7. Failed to get curl data from a local file source **(see the note below)**. 8. If we are within a `Chilkat.Js` context and don't have permission to read the local filesystem. 9. Chilkat has not been successfully unlocked by previously and successfully calling UnlockBundle. 10. Failed to open or create the local output file (if a curl option directed output to a file). 11. The response body is compressed with a Content-Encoding Chilkat cannot decode, such as Brotli (`br`) or zstd, so it is unusable. gzip and deflate are decoded automatically. (Introduced in v11.7.0.) **Note:** `curl` can read data from a local file and send it in a request (usually POST/PUT) using special syntax: - `-d @file.txt` → reads the file and sends it as request body (form-style encoding). - `--data-binary @file.bin` → sends raw file contents exactly as-is. - `-F "file=@file.txt"` → uploads the file as multipart/form-data. The `@` tells `curl` to load the data from a local file instead of using a literal string. ### HttpCurl.HeartbeatMs `Chilkat 11.7.0 · delphidll · HttpCurl · HeartbeatMs · property · read/write · since 11.5.0` ```pascal function CkHttpCurl_getHeartbeatMs(objHandle: HCkHttpCurl): Integer; stdcall; procedure CkHttpCurl_putHeartbeatMs(objHandle: HCkHttpCurl; newPropVal: Integer); stdcall; ``` Specifies the interval, in milliseconds, between `AbortCheck` event callbacks. This allows an application to periodically decide whether a long-running operation should be aborted. The default value is `0`, which means no `AbortCheck` callbacks are generated. ### HttpCurl.ResponseBodyStr `Chilkat 11.7.0 · delphidll · HttpCurl · ResponseBodyStr · property · read-only · since 11.5.0` ```pascal procedure CkHttpCurl_getResponseBodyStr(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__responseBodyStr(objHandle: HCkHttpCurl): PWideChar; stdcall; ``` Returns the HTTP response body from the last call to `DoYourThing` . ### HttpCurl.ResponseFilePath `Chilkat 11.7.0 · delphidll · HttpCurl · ResponseFilePath · property · read/write · since 11.5.0` ```pascal procedure CkHttpCurl_getResponseFilePath(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; procedure CkHttpCurl_putResponseFilePath(objHandle: HCkHttpCurl; newPropVal: PWideChar); stdcall; function CkHttpCurl__responseFilePath(objHandle: HCkHttpCurl): PWideChar; stdcall; ``` Set this property to the path of a file to stream the response body to a file. If the response is streamed to a file, it will not be available in `ResponseBodyStr` , `GetResponseSb` , or `GetResponseBd` . ### HttpCurl.ResponseHeader `Chilkat 11.7.0 · delphidll · HttpCurl · ResponseHeader · property · read-only · since 11.7.0` ```pascal procedure CkHttpCurl_getResponseHeader(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; function CkHttpCurl__responseHeader(objHandle: HCkHttpCurl): PWideChar; stdcall; ``` Returns the HTTP response header from the last call to `DoYourThing`: the status line (such as `HTTP/1.1 200 OK`) followed by the header fields, with CRLF line endings. Empty if no response was received. When redirects were followed (`-L`), this is the header of the final response. To get a single field, use `GetResponseHeaderField`. The curl `-D`/`--dump-header` option writes the header of every response (including redirects) to a file, and `-i`/`--include` writes the header before the body in the `-o`/`-O` output file; neither changes this property or the response body returned in memory. ### HttpCurl.StatusCode `Chilkat 11.7.0 · delphidll · HttpCurl · StatusCode · property · read-only · since 11.5.0` ```pascal function CkHttpCurl_getStatusCode(objHandle: HCkHttpCurl): Integer; stdcall; ``` Returns the HTTP status code from the last call to `DoYourThing`. A value of `0` indicates no response header was received. ### HttpCurl.UncommonOptions `Chilkat 11.7.0 · delphidll · HttpCurl · UncommonOptions · property · read/write · since 11.5.0` ```pascal procedure CkHttpCurl_getUncommonOptions(objHandle: HCkHttpCurl; outPropVal: HCkString); stdcall; procedure CkHttpCurl_putUncommonOptions(objHandle: HCkHttpCurl; newPropVal: PWideChar); stdcall; function CkHttpCurl__uncommonOptions(objHandle: HCkHttpCurl): PWideChar; stdcall; ``` Provides a comma-separated list of uncommon option keywords. This property defaults to an empty string and should normally remain empty. Can be set to a list of the following comma separated keywords: - `IgnoreUnknownCurlOptions` - Introduced in v11.7.0. Starting in v11.7.0, a curl option that HttpCurl does not recognize causes `DoYourThing` to fail with a syntax error (`FailReason` = 1) naming the option in `LastErrorText`, rather than being silently dropped as in earlier versions. (Options that are meaningless to HttpCurl but harmless, such as `--progress-bar` or `--retry`, are accepted and ignored.) This keyword restores the earlier behavior: an unknown option is skipped with a note in `LastErrorText`. Note that the value of an unknown option that takes one is then seen as a stray token. ## Methods ### HttpCurl.AddFunction `Chilkat 11.7.0 · delphidll · HttpCurl · AddFunction · method · since 11.5.0` ```pascal function CkHttpCurl_AddFunction(objHandle: HCkHttpCurl;     funcName: PWideChar;     curl: PWideChar): wordbool; stdcall; ``` Adds a named curl function that can be used in dependency resolution. Inputs required by the curl function are indicated by the variable names enclosed in `{{` and `}}`. Outputs are defined in one or more calls to `AddOutput` . Returns True for success, False for failure. ### HttpCurl.AddOutput `Chilkat 11.7.0 · delphidll · HttpCurl · AddOutput · method · since 11.5.0` ```pascal function CkHttpCurl_AddOutput(objHandle: HCkHttpCurl;     funcName: PWideChar;     jsonPath: PWideChar;     varName: PWideChar): wordbool; stdcall; ``` Adds or updates a defined output for a dependency resolution curl function previously defined by calling `AddFunction`. The `jsonPath` is the JSON path in the JSON response body where the `varName`'s value is located. If either the `funcName` or `jsonPath` already exist for the `funcName`, then the output is updated. Returns True for success, False for failure. ### HttpCurl.AddOutput2 `Chilkat 11.7.0 · delphidll · HttpCurl · AddOutput2 · method · since 11.5.0` ```pascal function CkHttpCurl_AddOutput2(objHandle: HCkHttpCurl;     funcName: PWideChar;     arrayPath: PWideChar;     wherePath: PWideChar;     whereValue: PWideChar;     caseSensitive: wordbool;     subPath: PWideChar;     varName: PWideChar): wordbool; stdcall; ``` Adds or updates an output variable definition for a dependency-resolution curl function previously created by calling `AddFunction`. Use this method when the curl response is JSON containing an array of objects, and a value needs to be extracted from one specific array element. The method searches the array located at `arrayPath`, finds the array element where the value at `wherePath` matches `whereValue`, and then extracts the value at `subPath`. The extracted value is assigned to the variable named by `varName`. The `wherePath` and `subPath` values are paths relative to each individual array element. The comparison between `whereValue` and the JSON value found at `wherePath` is either case-sensitive or case-insensitive depending on the value of `caseSensitive`. **Parameters** - `funcName` — The name of the curl function previously added by calling `AddFunction`. The output definition is associated with this function. - `arrayPath` — The JSON path identifying the array of records within the JSON response. May contain variable references (see below). - `wherePath` — A relative JSON path within each array element used to locate the matching record. May contain variable references (see below). - `whereValue` — The value to match against the JSON value found at `wherePath`. May contain variable references (see below). - `caseSensitive` — If `True`, the comparison between `whereValue` and the JSON value is case-sensitive. If `False`, the comparison is case-insensitive. - `subPath` — A relative JSON path within the matched array element identifying the value to extract. May contain variable references (see below). - `varName` — The name of the variable that will receive the extracted value. **Variable references** Starting in v11.7.0, the `arrayPath`, `wherePath`, `whereValue` and `subPath` may each contain variable names enclosed in `{{` and `}}`, such as `{{site_name}}`, either on their own or within a longer string such as `result.{{list_name}}.items`. Each is stored exactly as passed here, and the references in it are resolved every time this output is evaluated — not when `AddOutput2` is called. A variable whose value is set later by `SetVar`, or that is produced as the output of another curl function, is therefore used with its current value. A variable referenced here is treated as an input of the curl function, exactly like one appearing in the curl command itself, so the execution plan runs whatever produces it first. If a referenced variable has no value and nothing can produce it, the reference is left in place, no array element matches, and the LastErrorText reports the failure with both the resolved and the unresolved form of the record spec. **Example** Given the following JSON response: ``` { "drives": [ { "name": "Documents", "id": "A123" }, { "name": "Shared", "id": "B456" } ] } ``` The following call: ``` AddOutput2("GetDrive","drives","name","shared",false,"id","drive_id") ``` searches the `drives` array for the element whose `name` matches `"shared"` using case-insensitive comparison. The matching element is: ``` { "name": "Shared", "id": "B456" } ``` The value of `id` is extracted and assigned to the variable `drive_id`, resulting in: ``` drive_id = "B456" ``` Returns True for success, False for failure. ### HttpCurl.AddTargetOutput `Chilkat 11.7.0 · delphidll · HttpCurl · AddTargetOutput · method · since 11.5.0` ```pascal procedure CkHttpCurl_AddTargetOutput(objHandle: HCkHttpCurl;     jsonPath: PWideChar;     varName: PWideChar) stdcall; ``` Adds an automatically mapped variable for the target curl command. When a JSON response is received from a curl request, the value at the JSON path specified by `jsonPath` is extracted (if present) and assigned to the variable named by `varName`. This is useful in common workflows where one request returns an identifier (such as an \`id\`) that must be reused in a subsequent curl request. ### HttpCurl.ClearTargetOutput `Chilkat 11.7.0 · delphidll · HttpCurl · ClearTargetOutput · method · since 11.5.0` ```pascal procedure CkHttpCurl_ClearTargetOutput(objHandle: HCkHttpCurl;     varName: PWideChar) stdcall; ``` Clears (undefines) the target output for the specified `varName`. If `varName` equals `"*"`, then all target outputs are cleared. ### HttpCurl.ClearVar `Chilkat 11.7.0 · delphidll · HttpCurl · ClearVar · method · since 11.5.0` ```pascal procedure CkHttpCurl_ClearVar(objHandle: HCkHttpCurl;     varName: PWideChar) stdcall; ``` Undefines the variable with the specified name. If `varName` equals `"*"`, then all variables are cleared. ### HttpCurl.DoYourThing `Chilkat 11.7.0 · delphidll · HttpCurl · DoYourThing · method · since 11.5.0` ```pascal function CkHttpCurl_DoYourThing(objHandle: HCkHttpCurl;     targetCurl: PWideChar): wordbool; stdcall; ``` Runs a the `targetCurl` command specified in `targetCurl`. If the `targetCurl` contains variable names enclosed in `{{` and `}}`, then an execution plan is constructed from defined functions and outputs to resolve unknown variables, and the execution plan is run. The final step in the execution plan is always the `targetCurl` command. Returns success (`True`) if a response was received, in which case the response status code will be available in `StatusCode` and the content of the response body will be available in one of two places: - If `ResponseFilePath` is non-empty, the response body was streamed to the specified file path. - If `ResponseFilePath` is empty, the response body can be retrieved via `ResponseBodyStr` , `GetResponseSb` , or `GetResponseBd` . Binary responses should only be retrieved via `ResponseBodyBd` . Assuming the HTTP response is JSON, the target outputs (variables) specified by prior calls to `AddTargetOutput` will be populated by applying each variable's JSON path to the response JSON. **Writing the response to a local file** A curl command may write the response body to a local file with `-o` / `--output` (an explicit filename), or with `-O` / `--remote-name` (the filename is the final path segment of the URL). Either may be combined with `--output-dir`, which, as in curl, is applied only when the filename itself contains no directory separator. Starting in v11.7.0, the output file path may contain variable names enclosed in `{{` and `}}`, resolved from the current variable values at the time the request is sent. This applies to the path given with `-o`, the directory given with `--output-dir`, and the URL that `-O` derives a filename from. In previous versions the path was used exactly as written, so `-o "{{report_name}}.pdf"` created a file literally named `{{report_name}}.pdf` and reported success. ``` httpCurl.SetVar("customer","acme"); httpCurl.SetVar("report_name","q3-summary"); httpCurl.DoYourThing("curl https://api.example.com/reports/{{report_name}} " "--output-dir \"reports/{{customer}}\" -o \"{{report_name}}.pdf\""); // writes reports/acme/q3-summary.pdf ``` Two conditions cause the request to fail rather than write a file: - The resolved path still contains a `{{varName}}` reference, or a variable in it resolved to an empty string. (Elsewhere -- in a URL or a request body -- an unresolved reference is left in place. In a file path that would silently create a misnamed file.) - A variable substituted into the path has a value containing a `..` directory segment. Because a variable's value can come from a server's response (see `AddOutput` and `AddOutput2`), a response must not be able to move the output file out of the directory the curl command named. A `..` written literally in the curl command itself is the application's own choice and is allowed. The path as it will actually be used is written to `LastErrorText` as `resolvedOutputPath`. This is independent of the `ResponseFilePath` property, which streams the response body to a file for requests whose curl command names no output file. Returns True for success, False for failure. Async variant: `DoYourThingAsync` — same arguments, returns a `Task` (see Async variants below). ### HttpCurl.ExaminePlan `Chilkat 11.7.0 · delphidll · HttpCurl · ExaminePlan · method · since 11.5.0` ```pascal function CkHttpCurl_ExaminePlan(objHandle: HCkHttpCurl;     curl: PWideChar;     json: HCkJsonObject): wordbool; stdcall; ``` Used for debugging. Returns in `json` the plan of execution that would occur for the `curl` based on the variables that are either unknown or already known. The plan of execution is what would occur if `DoYourThing` was called with the current state of knowledge. If no execution plan is possible with the current known inputs and outputs, then `json` provides information about what is missing and the method returns `False`. Returns True for success, False for failure. ### HttpCurl.GetAllVars `Chilkat 11.7.0 · delphidll · HttpCurl · GetAllVars · method · since 11.5.0` ```pascal procedure CkHttpCurl_GetAllVars(objHandle: HCkHttpCurl;     json: HCkJsonObject) stdcall; ``` Returns all defined variables in `json`. ### HttpCurl.GetResponseBd `Chilkat 11.7.0 · delphidll · HttpCurl · GetResponseBd · method · since 11.5.0` ```pascal function CkHttpCurl_GetResponseBd(objHandle: HCkHttpCurl;     bd: HCkBinData): wordbool; stdcall; ``` Appends to `bd` the HTTP response body from the last call to `DoYourThing`. Returns True for success, False for failure. ### HttpCurl.GetResponseHeaderField `Chilkat 11.7.0 · delphidll · HttpCurl · GetResponseHeaderField · method · since 11.7.0` ```pascal function CkHttpCurl_GetResponseHeaderField(objHandle: HCkHttpCurl;     name: PWideChar;     outStr: HCkString): wordbool; stdcall; function CkHttpCurl__getResponseHeaderField(objHandle: HCkHttpCurl;     name: PWideChar): PWideChar; stdcall; ``` Returns the value of the response header field named `name` (case-insensitive) from the last call to `DoYourThing`, such as `"Content-Type"` or `"ETag"`. Returns an empty string if the response has no such field. When redirects were followed (`-L`), the field is from the final response. The full response header is available in `ResponseHeader`. Returns True for success, False for failure. See the notes about [PWideChar memory ownership and validity](https://www.chilkatsoft.com/delphi_pwidechar.asp). ### HttpCurl.GetResponseJarr `Chilkat 11.7.0 · delphidll · HttpCurl · GetResponseJarr · method · since 11.5.0` ```pascal function CkHttpCurl_GetResponseJarr(objHandle: HCkHttpCurl;     jarr: HCkJsonArray): wordbool; stdcall; ``` Writes to `jarr` the HTTP response body from the last call to `DoYourThing`. Returns True for success, False for failure. ### HttpCurl.GetResponseJson `Chilkat 11.7.0 · delphidll · HttpCurl · GetResponseJson · method · since 11.5.0` ```pascal function CkHttpCurl_GetResponseJson(objHandle: HCkHttpCurl;     json: HCkJsonObject): wordbool; stdcall; ``` Writes to `json` the HTTP response body from the last call to `DoYourThing`. Returns True for success, False for failure. ### HttpCurl.GetResponseSb `Chilkat 11.7.0 · delphidll · HttpCurl · GetResponseSb · method · since 11.5.0` ```pascal function CkHttpCurl_GetResponseSb(objHandle: HCkHttpCurl;     sb: HCkStringBuilder): wordbool; stdcall; ``` Appends to `sb` the HTTP response body from the last call to `DoYourThing`. Returns True for success, False for failure. ### HttpCurl.GetResponseXml `Chilkat 11.7.0 · delphidll · HttpCurl · GetResponseXml · method · since 11.5.0` ```pascal function CkHttpCurl_GetResponseXml(objHandle: HCkHttpCurl;     xml: HCkXml): wordbool; stdcall; ``` Writes to `xml` the HTTP response body from the last call to `DoYourThing`. Returns True for success, False for failure. ### HttpCurl.GetVar `Chilkat 11.7.0 · delphidll · HttpCurl · GetVar · method · since 11.5.0` ```pascal function CkHttpCurl_GetVar(objHandle: HCkHttpCurl;     varName: PWideChar;     outStr: HCkString): wordbool; stdcall; function CkHttpCurl__getVar(objHandle: HCkHttpCurl;     varName: PWideChar): PWideChar; stdcall; ``` Retrieves the current value of the variable specified by `varName`. Returns True for success, False for failure. See the notes about [PWideChar memory ownership and validity](https://www.chilkatsoft.com/delphi_pwidechar.asp). ### HttpCurl.SetAuth `Chilkat 11.7.0 · delphidll · HttpCurl · SetAuth · method · since 11.5.0` ```pascal function CkHttpCurl_SetAuth(objHandle: HCkHttpCurl;     json: HCkJsonObject): wordbool; stdcall; ``` Sets authorization information that is applied to all calls to `DoYourThing` . See the examples below for details. Returns True for success, False for failure. ### HttpCurl.SetVar `Chilkat 11.7.0 · delphidll · HttpCurl · SetVar · method · since 11.5.0` ```pascal procedure CkHttpCurl_SetVar(objHandle: HCkHttpCurl;     varName: PWideChar;     varValue: PWideChar) stdcall; ``` Sets the value of a variable to be replaced in curl commands. Variable names are enclosed in `{{` and `}}` and can occur in the path, query params, or the body of the request. Starting in v11.7.0, they can also occur in the `arrayPath`, `wherePath`, `whereValue` and `subPath` passed to `AddOutput2`, and in the local output file path of a curl command -- the path given with `-o` or `--output`, the directory given with `--output-dir`, and the URL that `-O` derives a filename from. See `DoYourThing` . ### HttpCurl.ToRawRequest `Chilkat 11.7.0 · delphidll · HttpCurl · ToRawRequest · method · since 11.5.0` ```pascal function CkHttpCurl_ToRawRequest(objHandle: HCkHttpCurl;     curlCommand: PWideChar;     sb: HCkStringBuilder): wordbool; stdcall; ``` Used for debugging purposes. This method behaves the same as `DoYourThing` , but only converts the `curlCommand` to an HTTP request message in `sb` containing the full structure: - start line - headers - optional body or multipart body It does not actually send the HTTP request. Returns True for success, False for failure. ### HttpCurl.VarDefined `Chilkat 11.7.0 · delphidll · HttpCurl · VarDefined · method · since 11.5.0` ```pascal function CkHttpCurl_VarDefined(objHandle: HCkHttpCurl;     varName: PWideChar): wordbool; stdcall; ``` Returns `True` if the `varName` is defined, otherwise returns `False`. Setting `varName` to `"!"` checks whether all target output variables have been defined. It returns `True` if every target output is set, and `False` if any are missing. ## Events and callbacks ### HttpCurl.AbortCheck (event) `Chilkat 11.7.0 · delphidll · HttpCurl · AbortCheck · event` ```pascal function MyAbortCheck(): Integer; cdecl; ``` 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) ### HttpCurl.PercentDone (event) `Chilkat 11.7.0 · delphidll · HttpCurl · PercentDone · event` ```pascal function MyPercentDone(pctDone: Integer): Integer; cdecl; ``` 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) ### HttpCurl.ProgressInfo (event) `Chilkat 11.7.0 · delphidll · HttpCurl · ProgressInfo · event` ```pascal procedure MyProgressInfo(name: PWideChar; value: PWideChar) cdecl; ``` 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. ### HttpCurl.TaskCompleted (event) `Chilkat 11.7.0 · delphidll · HttpCurl · TaskCompleted · event` ```pascal procedure MyTaskCompleted(task: HCkTask) cdecl; ``` Called from the background thread when an asynchronous task completes. ## Async variants Each returns a `Task` instead of the result and takes the same arguments as the synchronous method; run the task, wait for `Finished`, then read the result from the task. No new Async methods are added from 11.7.0 on. ```pascal function CkHttpCurl_DoYourThingAsync(objHandle: HCkHttpCurl;     targetCurl: PWideChar): HCkTask; stdcall; ``` ## Related classes [`BinData`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/delphidll/classes/BinData.md), [`JsonArray`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/delphidll/classes/JsonArray.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/delphidll/classes/JsonObject.md), [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/delphidll/classes/StringBuilder.md), [`Xml`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/delphidll/classes/Xml.md)