Chilkat.Upload Class Overview

Chilkat.Upload sends files to a web server using HTTP POST. It supports file references, custom form parameters, custom headers, blocking and asynchronous uploads, progress monitoring, upload throttling, Basic HTTP authentication, proxy settings, HTTPS/TLS configuration, and inspection of the HTTP response returned by the server.

What the Class Is Used For

Use Chilkat.Upload when an application needs to upload one or more files to a server-side HTTP endpoint. The upload is configured by setting the target server properties, adding files with AddFileReference, optionally adding form parameters with AddParam, and then calling either BlockingUpload or BeginUpload.

Upload Files Add one or more files to the next upload using AddFileReference.
Add Form Data Add custom request parameters with AddParam.
Run Blocking or Async Use BlockingUpload for synchronous uploads or BeginUpload for background uploads.
Inspect Server Response Read ResponseStatus, ResponseHeader, and ResponseBodyStr after the upload.

HTTP Uploads Require Server-Side Code

An HTTP upload is an HTTP POST sent to a server URL. The client-side upload code only sends the request. A web server must have a receiving endpoint, script, page, controller, CGI program, API route, or similar server-side handler that accepts the POST, parses the uploaded files and form parameters, saves or processes the data, and returns an HTTP response.

Client-Side Responsibility Server-Side Responsibility
Set Hostname, Path, Port, and Ssl. Expose a matching URL that accepts HTTP POST requests.
Add files with AddFileReference. Read the uploaded file parts and decide where to save or how to process them.
Add request parameters with AddParam. Read the posted form fields and validate them.
Optionally add authentication, custom headers, TLS settings, and proxy settings. Authenticate the request, enforce upload size limits, validate file types, and return an appropriate HTTP response.
Inspect ResponseStatus, ResponseHeader, and ResponseBody. Return an HTTP status code, response headers, and response body describing success or failure.
Practical example: If the target URL is https://www.example.com/upload/receive.asp, then the server must actually provide /upload/receive.asp and that server-side code must know how to receive and process the posted upload.

Typical Workflow: Blocking Upload

  1. Create a Upload object.
  2. Set the target server: Hostname, Path, Port, and Ssl.
  3. Optionally set Login and Password for Basic HTTP authentication.
  4. Optionally add custom headers with AddCustomHeader.
  5. Optionally add form parameters with AddParam.
  6. Add one or more files with AddFileReference.
  7. Call BlockingUpload.
  8. Check the boolean return value, then inspect ResponseStatus, ResponseHeader, and ResponseBodyStr.
  9. If the method fails or behaves unexpectedly, inspect LastErrorText.

Typical Workflow: Asynchronous Upload

  1. Configure the upload target and add files exactly as with a blocking upload.
  2. Call BeginUpload to start the upload on a background thread.
  3. Periodically check UploadInProgress until it becomes false.
  4. Monitor CurrentFilename, NumBytesSent, TotalUploadSize, and PercentUploaded while the upload is running.
  5. To cancel the upload, call AbortUpload or set AbortCurrent.
  6. After completion, check UploadSuccess.
  7. Inspect the HTTP response properties and LastErrorText as needed.
One async upload per object: Only one asynchronous upload may be in progress for a single Upload object. Use multiple object instances for multiple simultaneous asynchronous uploads.

Core Concepts

Concept Meaning Important Members
Target URL Parts The upload target is configured by splitting the URL into host, path, port, and SSL/TLS settings. Hostname, Path, Port, Ssl
Files to Upload Files are added to an internal list before calling the upload method. AddFileReference, ClearFileReferences
Form Parameters Additional name/value request parameters can be included with the upload. AddParam, ClearParams
Blocking Upload The method call does not return until the upload completes or fails. BlockingUpload
Asynchronous Upload The upload runs in the background and can be monitored through progress properties. BeginUpload, UploadInProgress, UploadSuccess
Response Inspection The server returns a normal HTTP response with status, headers, and body. ResponseStatus, ResponseHeader, ResponseBody, ResponseBodyStr

Target Server Properties

Property Purpose Guidance
Hostname Hostname or IP address of the HTTP server. Do not include http:// or https://. Use a hostname such as www.example.com or an IP address.
Path Path part of the upload URL. For https://www.example.com/cgi-bin/upload.exe, use Hostname = www.example.com and Path = /cgi-bin/upload.exe.
Port TCP port for the target server. Default is 80. Use 443 for typical HTTPS uploads.
Ssl Enables HTTPS/TLS. Set true when uploading to an https:// URL.
ClientIpAddress Selects a local IP address on multihomed computers. Usually leave unset. Set only when the computer has multiple network interfaces or IP addresses and a specific source IP is required.
PreferIpv6 Prefers IPv6 over IPv4 when both are supported. Default is false, which chooses IPv4 over IPv6.

Files, Parameters, and Headers

Method Purpose Use When
AddFileReference Adds a file to the internal list of files to upload. Call once for each file before BlockingUpload, BeginUpload, or UploadToMemory.
ClearFileReferences Clears the internal file list. Use before building a new upload request with a different file set.
AddParam Adds a custom HTTP request parameter. Use to include additional form fields with the upload.
ClearParams Clears request parameters added with AddParam. Use before preparing a new upload request with different parameters.
AddCustomHeader Adds a custom HTTP header to the upload request. Use for application-specific headers required by the server.
Request reuse note: File references and parameters remain in the object until cleared. Use ClearFileReferences and ClearParams when reusing the same object for a different upload.

Upload Methods

Method Behavior Use When
BlockingUpload Uploads the files using HTTP and waits until the upload completes or fails. Use for simple synchronous upload workflows.
BeginUpload Starts an asynchronous upload on a background thread. Use when the application must remain responsive or monitor upload progress.
AbortUpload Aborts an asynchronous upload. Use while an upload started by BeginUpload is in progress.
UploadToMemory Builds the complete HTTP POST request in memory. Use for debugging to inspect the exact HTTP POST that would be sent.
SleepMs Sleeps the calling process for a specified number of milliseconds. Useful in languages or environments where short sleep intervals are helpful while polling asynchronous upload status.

Progress, Timeouts, and Abort Control

Member Purpose Guidance
UploadInProgress True while an asynchronous upload is running. Poll this after BeginUpload until it becomes false.
UploadSuccess Indicates success or failure after an asynchronous upload completes. Check after UploadInProgress becomes false.
CurrentFilename Current filename being uploaded during an asynchronous upload. Useful for progress displays.
NumBytesSent Number of bytes sent. Updated during asynchronous uploads and available after completion.
TotalUploadSize Total upload size in bytes. Set at the beginning of an asynchronous upload and also during synchronous uploads.
PercentUploaded Current upload completion percentage from 0 to 100. Useful while an asynchronous upload is in progress.
PercentDoneScale Controls progress callback granularity in event-enabled environments. Default is 100. Larger values allow finer progress resolution.
IdleTimeoutMs Aborts the upload if progress stalls longer than this timeout. Default is 30000 milliseconds.
AbortCurrent Causes the currently running method to abort when set to true. Applies to operations long enough to be aborted. Both synchronous and asynchronous calls can be aborted.
HeartbeatMs Interval between AbortCheck event callbacks. Default is 0, meaning no AbortCheck callbacks.

Bandwidth and Transfer Behavior

Property Purpose Default / Guidance
BandwidthThrottleUp Limits upload bandwidth to approximately the specified bytes per second. Default is 0, meaning no upload throttling.
ChunkSize Chunk size used by the underlying TCP/IP sockets for uploading files. Default is 65535 bytes.
Expect100Continue Adds an Expect: 100-continue request header. Default is true. This lets the server reject the upload based on headers before the client sends the file data.
Upload-size rejection: Expect100Continue can help avoid sending a large body when the server will reject the request based on headers, authentication, or upload size policy.

Authentication and Proxy Settings

Property Purpose Guidance
Login HTTP login for sites requiring authentication. Chilkat Upload supports Basic HTTP authentication.
Password HTTP password for sites requiring authentication. Used with Login for Basic HTTP authentication.
ProxyDomain Hostname or IP address of an HTTP proxy. Do not include http://.
ProxyPort Port number of the HTTP proxy. Set when using an HTTP proxy.
ProxyLogin Proxy authentication login. Set if the proxy requires authentication.
ProxyPassword Proxy authentication password. Set if the proxy requires authentication.

HTTPS and TLS Settings

Property Purpose Guidance
Ssl Enables HTTPS/TLS for the upload. For an https:// target, set Ssl = true and typically Port = 443.
SslProtocol Selects the secure protocol for SSL/TLS connections. Default is default. Prefer flexible values such as TLS 1.2 or higher rather than forcing an exact protocol unless required.
SslAllowedCiphers Restricts the TLS cipher suites and related TLS security requirements. Empty means all implemented ciphers are possible. It can be set to explicit cipher names, RSA key-size restrictions such as rsa1024 or rsa2048, or the best-practices keyword.
TlsPinSet Specifies expected SPKI fingerprints for public key pinning. If the server certificate does not match one of the configured pins, the TLS handshake is aborted.
TLS selection note: The client offers allowed protocols and ciphers, but the server participates in selecting the final protocol and cipher suite during negotiation.

Server Response Properties

Property Contains Use When
ResponseStatus HTTP response status code. Use to determine whether the server returned success, redirect, client error, or server error status.
ResponseHeader Header portion of the HTTP response. Use to inspect server response headers.
ResponseBody Body portion of the HTTP response as bytes. Use when the response body is binary or should be processed as bytes.
ResponseBodyStr Response body as a string. Use when the server returns a text response such as HTML, JSON, XML, or plain text.
HTTP response reminder: An upload is still an HTTP request. The server should return a normal HTTP response containing headers and, optionally, a response body.

Debugging an Upload Request

Method / Property Purpose How It Helps
UploadToMemory Writes the complete HTTP POST request to memory. Shows the request header, custom parameters, and files that would be sent by BlockingUpload or BeginUpload.
LastErrorText Diagnostic text for the last method or property. Provides details when a method fails or behaves unexpectedly.
ResponseHeader HTTP response headers returned by the server. Helps identify server-side behavior, redirects, content type, or error details.
ResponseBodyStr Response body as text. Often contains application-specific success or error messages from the server-side upload handler.

Method Summary by Category

Category Methods / Properties Purpose
Build request AddFileReference, AddParam, AddCustomHeader Add files, form fields, and custom HTTP headers to the upload request.
Clear request state ClearFileReferences, ClearParams Remove previously added files or form parameters before reusing the object.
Execute upload BlockingUpload, BeginUpload Send the HTTP upload synchronously or asynchronously.
Abort / wait AbortUpload, AbortCurrent, SleepMs Cancel uploads or sleep briefly while polling asynchronous progress.
Monitor progress UploadInProgress, UploadSuccess, CurrentFilename, NumBytesSent, TotalUploadSize, PercentUploaded Track asynchronous upload state and progress.
Inspect response ResponseStatus, ResponseHeader, ResponseBody, ResponseBodyStr Read the HTTP response returned by the server.
Debug request UploadToMemory Generate the complete HTTP POST in memory for inspection.
Async workflow LoadTaskCaller Load the caller of a completed async method task.
Diagnostics LastErrorText Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Upload fails immediately Hostname, Path, Port, Ssl, LastErrorText Confirm the target URL was split correctly and inspect diagnostics for DNS, connection, TLS, or request-building errors.
Server returns an error ResponseStatus, ResponseHeader, ResponseBodyStr The request reached the server. Inspect the status code and body returned by the server-side upload handler.
Server does not receive the file AddFileReference, UploadToMemory Confirm the file was added before the upload and use UploadToMemory to inspect the generated HTTP POST.
Server-side script is missing or incorrect Path, ResponseStatus, ResponseBodyStr Verify that the target path maps to real server-side code that accepts and processes HTTP POST uploads.
Asynchronous upload never finishes UploadInProgress, IdleTimeoutMs, AbortUpload Check whether progress has stalled, adjust the idle timeout if needed, or abort the upload.
HTTPS upload fails Ssl, Port, SslProtocol, SslAllowedCiphers, TlsPinSet Confirm HTTPS settings, TLS protocol requirements, allowed ciphers, and any public key pinning configuration.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected upload, connection, TLS, proxy, authentication, or async behavior.

Common Pitfalls

Pitfall Better Approach
Putting http:// or https:// in Hostname. Put only the host name or IP address in Hostname. Use Ssl and Port to indicate HTTP vs HTTPS.
Forgetting that server-side code is required. Make sure the target URL points to code on the server that accepts and processes the HTTP POST upload.
Adding files or parameters once and unintentionally reusing them later. Use ClearFileReferences and ClearParams before preparing a different upload.
Checking only the method return value and ignoring the server response. Also inspect ResponseStatus and ResponseBodyStr to understand what the server actually returned.
Starting multiple async uploads with one object instance. Use one Upload object per asynchronous upload.
Forcing an exact TLS protocol unnecessarily. Prefer the default or an “or higher” setting unless the server requires a specific protocol.
Ignoring diagnostics after failed uploads. Check LastErrorText for details.

Best Practices

Recommendation Reason
Split the upload URL carefully into host, path, port, and SSL settings. Hostname should not include the URL scheme, and Path should identify the server-side upload endpoint.
Confirm the server-side upload handler before debugging the client. HTTP upload success depends on server code that accepts, parses, validates, stores, and responds to the posted data.
Use UploadToMemory when debugging request construction. It shows the exact HTTP POST that would be sent.
Use BeginUpload for large uploads or responsive UI applications. It allows progress monitoring and cancellation while the upload runs in the background.
Use Expect100Continue for large uploads unless the server has trouble with it. It can allow the server to reject the request before file data is sent.
Inspect both Chilkat diagnostics and the HTTP server response. LastErrorText helps diagnose client-side failures, while ResponseStatus and ResponseBodyStr explain server-side results.
Clear file references and parameters when reusing the object. This prevents accidentally sending stale files or form fields in a later upload.

Summary

Chilkat.Upload is a specialized HTTP upload class for sending files and form parameters to a server-side upload endpoint. It supports blocking and asynchronous operation, progress tracking, cancellation, throttling, authentication, proxies, HTTPS/TLS settings, custom headers, and inspection of the server's HTTP response.

The most important practical guidance is to remember that the client sends an HTTP POST, but the server must provide code to receive and process it; configure Hostname, Path, Port, and Ssl correctly; add files before calling the upload method; inspect the server response after the upload; and use LastErrorText whenever the upload fails or behaves unexpectedly.