Chilkat.HttpCurl Class Overview

Chilkat.HttpCurl executes HTTP requests expressed as curl commands, with support for variable substitution, reusable curl functions, automatic dependency resolution, response extraction, target output variables, request debugging, authorization settings, response streaming, and structured failure diagnostics. It is designed for workflows where one HTTP request returns values needed by later requests.

What the Class Is Used For

Use Chilkat.HttpCurl when an application wants to represent HTTP requests as curl commands, substitute variables such as {{site_id}}, and optionally let Chilkat build and run a dependency plan to resolve missing values. The final request is always the target curl command passed to DoYourThing.

Run curl-style HTTP requests Execute a target curl command and retrieve the response as text, StringBuilder, BinData, JSON, XML, or a file.
Resolve dependencies Define named curl functions and outputs so unknown variables can be resolved automatically before the target request runs.
Capture output variables Extract values from JSON responses and store them as variables for later requests.
Debug before sending Examine the planned execution or convert a curl command to a raw HTTP request without actually sending it.

Typical Workflow: Execute a Single curl Command

  1. Create an HttpCurl object.
  2. Optionally call SetAuth to apply authorization to all requests.
  3. Optionally set variables with SetVar if the curl command contains placeholders such as {{drive_id}}.
  4. Optionally set ResponseFilePath if the response body should be streamed directly to a local file.
  5. Call DoYourThing with the target curl command.
  6. Check StatusCode, then retrieve the response with ResponseBodyStr, GetResponseSb, GetResponseBd, GetResponseJson, GetResponseJarr, or GetResponseXml.
  7. If the call fails, inspect FailReason, FailedCurl, and LastErrorText.

Typical Workflow: Dependency Resolution

  1. Define one or more reusable curl functions with AddFunction. Inputs are represented by {{variable}} placeholders.
  2. Define each function’s outputs with AddOutput or AddOutput2, mapping JSON response values to variable names.
  3. Define any known starting variables with SetVar.
  4. Optionally call ExaminePlan to see the execution plan that would be used to resolve missing variables.
  5. Call DoYourThing with the target curl command.
  6. Chilkat runs dependency functions as needed, resolves missing variables, and executes the target curl command as the final step.
Dependency model: If the target curl contains unknown variables, Chilkat uses the defined functions and output mappings to derive a plan for resolving them before running the final request.

Core Concepts

Concept Meaning Important Members
Target curl The curl command passed to DoYourThing. It is always the final step of the execution plan. DoYourThing, AddTargetOutput
Variable A named value substituted into curl commands using {{name}} syntax. SetVar, GetVar, ClearVar, VarDefined
Function A named curl command used to resolve dependency variables for other curl commands. AddFunction
Function output A mapping from a JSON response value to a variable name. AddOutput, AddOutput2
Target output A variable populated from the JSON response of the final target curl command. AddTargetOutput, ClearTargetOutput, VarDefined("!")
Execution plan Ordered list of dependency curl functions needed to resolve unknown variables, followed by the target curl. ExaminePlan, DoYourThing

Key Properties

Property Purpose Guidance
EnableBodyVars Enables variable substitution in the body of the HTTP request. Default is true. Disable only when body text should not be scanned for {{variable}} placeholders.
ResponseFilePath Streams the response body directly to a local file. When set, the response body is not available from ResponseBodyStr, GetResponseSb, or GetResponseBd.
StatusCode HTTP status code from the last DoYourThing call. A value of 0 means no response header was received.
ResponseBodyStr Response body from the last DoYourThing call as a string. Use for text responses when ResponseFilePath was not set.
FailReason Numeric reason for failure from DoYourThing or ExaminePlan. Use with FailedCurl and LastErrorText to diagnose failures.
FailedCurl The specific curl command in the execution plan that failed. Especially useful when dependency resolution executes multiple curl commands.
HeartbeatMs Interval in milliseconds between AbortCheck callbacks. Default is 0, meaning no callbacks.
UncommonOptions Comma-separated keywords for uncommon needs. Defaults to empty and should normally remain empty.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Variable Management

Method Purpose Notes
SetVar Defines or updates a variable value. Variables are replaced in curl paths, query parameters, and request bodies.
GetVar Retrieves the current value of a variable. Use after dependency resolution or target output extraction.
ClearVar Undefines one variable or all variables. Pass * to clear all variables.
GetAllVars Returns all currently defined variables in a JsonObject. Useful for debugging the current state of known values.
VarDefined Checks whether a variable is defined. Pass ! to check whether all target output variables have been defined.
Variable syntax: Variables are referenced in curl commands using double braces, such as {{site_id}} or {{drive_id}}.

Dependency Functions and Outputs

Method Purpose Use When
AddFunction Adds a named curl function for dependency resolution. Use when one request can produce variables needed by later requests.
AddOutput Maps a JSON path in a function response to a variable name. Use when the needed value is directly available at a known JSON path.
AddOutput2 Searches an array of JSON objects, finds a matching element, and extracts a value from it. Use when a response contains an array and the desired value belongs to the object matching a condition.
AddOutput2 example: If a JSON response contains a drives array, an output rule can find the object whose name equals Shared and extract its id into drive_id.

Target Outputs

Method Purpose Typical Use
AddTargetOutput Defines a variable to be populated from the JSON response of the target curl command. Use when the final request returns an identifier or value that should be reused by a later request.
ClearTargetOutput Clears a target output definition. Pass * to clear all target outputs.
VarDefined("!") Checks whether every target output variable has been defined. Useful after DoYourThing to confirm expected target values were extracted.

Executing Requests and Reading Responses

Method / Property Purpose Best For
DoYourThing Runs the target curl command, including dependency resolution if needed. Main execution method.
ResponseBodyStr Gets the last response body as a string. Text responses.
GetResponseSb Appends the last response body to a StringBuilder. Text responses where a mutable string buffer is preferred.
GetResponseBd Appends the last response body to BinData. Binary responses or raw bytes.
GetResponseJson Loads the last response body into a JsonObject. JSON object responses.
GetResponseJarr Loads the last response body into a JsonArray. JSON array responses.
GetResponseXml Loads the last response body into an Xml object. XML responses.
ResponseFilePath Streams the response body directly to a file. Large downloads or file output.
File streaming note: When ResponseFilePath is set, the response body is streamed to that file and is not also available through the in-memory response getters.

Debugging and Planning Methods

Method Purpose Does It Send the Request?
ExaminePlan Returns the execution plan that would be used for a curl command based on currently known variables and defined outputs. No.
ToRawRequest Converts a curl command into the raw HTTP request message, including start line, headers, and optional body or multipart body. No.
GetAllVars Returns all currently defined variables as JSON. No.
Debug first: Use ExaminePlan to understand dependency resolution and ToRawRequest to inspect the exact HTTP request structure before sending.

Authorization and Request Customization

Member Purpose Guidance
SetAuth Sets authorization information applied to all DoYourThing calls. Use when a common authorization model should be applied across target and dependency requests.
EnableBodyVars Controls whether variables are substituted in request bodies. Leave enabled for JSON or form bodies that contain {{variable}} placeholders.
UncommonOptions Provides uncommon option keywords. Normally leave empty unless a documented special behavior is needed.

Failure Reasons

FailReason Meaning Typical Next Step
0 No error, or the method has not yet been called. No action needed.
1 curl command syntax error. Inspect the curl command and use ToRawRequest.
2 HTTP response status indicates authentication or authorization error. Check credentials, tokens, scopes, permissions, or authorization headers.
3 HTTP response status indicates an error other than auth/authz. Check StatusCode and response body.
4 HTTP communications failure. Check network, TLS, DNS, proxy, endpoint URL, and LastErrorText.
5 Impossible to derive an execution plan from defined outputs and inputs. Use ExaminePlan and define missing functions or outputs.
6 A step in the execution plan did not resolve any dependency variables. Check JSON paths and output mappings for the failed function.
7 Failed to get curl data from a local file source. Check local file paths used with curl @file syntax.
8 Inside Chilkat.Js without permission to read the local filesystem. Grant filesystem permission or avoid local file input.
9 Chilkat has not been successfully unlocked. Call UnlockBundle successfully before using the class.
10 Failed to open or create the local output file. Check ResponseFilePath, directory existence, and permissions.

Local File Input in curl Commands

Some curl command forms read request data from local files. When this fails, FailReason may be 7, or 8 in a restricted Chilkat.Js context.

curl Syntax Behavior
-d @file.txt Reads the file and sends it as the request body using 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.
Important: The @ marker means curl should read from a local file rather than use a literal string.

Method Summary by Category

Category Methods / Properties Purpose
Execute HTTP requests DoYourThing, StatusCode, ResponseBodyStr, ResponseFilePath Run the target curl command and access the HTTP result.
Read response body GetResponseSb, GetResponseBd, GetResponseJson, GetResponseJarr, GetResponseXml Retrieve the response as text, bytes, JSON object, JSON array, or XML.
Variables SetVar, GetVar, ClearVar, GetAllVars, VarDefined Define, inspect, clear, and test variables used in curl commands.
Dependency functions AddFunction, AddOutput, AddOutput2 Define curl functions and map their JSON responses to variables.
Target outputs AddTargetOutput, ClearTargetOutput Extract variables from the final target curl response.
Planning and debugging ExaminePlan, ToRawRequest Inspect the dependency plan or raw HTTP request without sending the request.
Authorization SetAuth Apply authorization information to all calls to DoYourThing.
Diagnostics FailReason, FailedCurl, LastErrorText Identify failure type, failed curl command, and detailed diagnostic text.

Diagnostics and Troubleshooting

Problem Area Member What to Check
curl command does not parse FailReason, ToRawRequest Check curl syntax, quoting, data arguments, headers, and multipart options.
Dependency plan cannot be derived ExaminePlan, AddFunction, AddOutput, AddOutput2 Confirm that every unknown variable can be produced by a defined function output.
Dependency step runs but no variable is resolved FailReason, FailedCurl Check that the function returned JSON and that the configured JSON paths match the actual response.
Authentication or authorization failure SetAuth, StatusCode, FailReason A 401 or 403 is reported as an authentication/authorization failure. Check tokens, credentials, scopes, roles, and permissions.
Response body is missing from memory ResponseFilePath If response streaming was enabled, the body was written to the specified file and is not available through the in-memory getters.
Binary response appears corrupted as text GetResponseBd Use GetResponseBd for binary responses instead of string-based response access.
Local file upload or request body file fails FailReason Check @file paths, file permissions, and filesystem access in restricted runtime environments.
Need operation details after failure LastErrorText, FailedCurl Inspect the failed curl command and diagnostic text after failed execution, planning, parsing, HTTP communication, response extraction, or file output.

Common Pitfalls

Pitfall Better Approach
Expecting dependency resolution without defining functions and outputs. Use AddFunction plus AddOutput or AddOutput2 so Chilkat knows how to obtain missing variables.
Using incorrect JSON paths for outputs. Inspect the actual response with GetResponseJson or debugging output, then adjust the JSON path.
Assuming DoYourThing success means HTTP status 2xx. Always check StatusCode. The request may receive an HTTP response with an error status.
Trying to read response text after setting ResponseFilePath. Read the response from the file. In-memory response properties/getters are not populated when streaming to a file.
Retrieving binary data with ResponseBodyStr. Use GetResponseBd for binary data.
Forgetting to clear stale variables between unrelated workflows. Use ClearVar("*") and ClearTargetOutput("*") when starting a new, unrelated request chain.
Using local @file curl syntax in a restricted environment. Ensure filesystem access is allowed, especially when running inside Chilkat.Js.

Best Practices

Recommendation Reason
Use clear variable names such as site_id or drive_id. Descriptive variables make execution plans and troubleshooting easier.
Call ExaminePlan before complex chained requests. It confirms whether Chilkat can resolve all dependencies before actually sending HTTP requests.
Use AddOutput2 for array lookup scenarios. It avoids relying on fixed array indexes when the correct object should be found by matching a property value.
Use ToRawRequest when curl behavior is unclear. It shows the exact HTTP start line, headers, and body that would be sent.
Stream large downloads with ResponseFilePath. This avoids holding large response bodies in memory.
Use response getters that match the expected content type. Use GetResponseJson for JSON objects, GetResponseJarr for JSON arrays, GetResponseXml for XML, and GetResponseBd for binary.
Check FailReason, FailedCurl, and LastErrorText after failure. Together they identify the failure category, the failed command, and the detailed diagnostic information.

Summary

Chilkat.HttpCurl is the Chilkat class for executing HTTP requests described as curl commands, with optional variable substitution and automatic dependency resolution. It can run a target curl command directly, or derive and execute a sequence of supporting curl functions needed to resolve variables used by the target request.

The most important practical guidance is to define variables and outputs clearly, use ExaminePlan for complex request chains, use ToRawRequest to debug request construction, choose the correct response getter for the response type, stream large responses to a file with ResponseFilePath, and inspect FailReason, FailedCurl, and LastErrorText whenever execution fails.