TChilkatGlobal Delphi ActiveX Reference Documentation

TChilkatGlobal

Current Version: 9.5.0.97

Provides a means for updating global settings that affect all types of Chilkat objects across all instances.

Importing the Chilkat ActiveX into Delphi

Important: When upgrading to a new version of Chilkat, make sure to re-imported ActiveX DLL into Delphi to regenerate the files described below.

Two things are required to use an ActiveX in Delphi:

  1. The ActiveX DLL needs to be registered via regsvr32 on the system where the Delphi application runs. See How To Register ActiveX DLLs for detailed information.
  2. See also: ActiveX Registration Tutorial
  3. The ActiveX component needs to be "imported". Use the Delphi Import Component Wizard to import the Chilkat type library. This creates the following files: Chilkat_v9_5_0_TLB.pas and Chilkat_v9_5_0_TLB.dcr. The Chilkat_v9_5_0_TLB.pas should be added to your project.

To import the Chilkat type library, do the following:

  1. In the Delphi RAD Studio, select the menu item "Component" --> "Import a Type Library".
  2. Find "Chilkat ActiveX v9.5.0" in the list and select it. This will only appear in the list if the ChilkatAx-9.5.0-win32.dll (or ChilkatAx-9.5.0-x64.dll) has been registered w/ regsvr32.
  3. Check the "Generate Component Wrappers" checkbox.
  4. Select a directory where the unit files (.pas and .dcr) should be generated.
  5. Select "Create Unit" and then "Finish".
  6. Add the .pas to your Delphi project.

To use a Chilkat ActiveX object in your Delphi code, add "Chilkat_v9_5_0_TLB" to the "uses" statement. For example:

uses
  Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes, Vcl.Graphics,
  Vcl.Controls, Vcl.Forms, Vcl.Dialogs, Vcl.StdCtrls, Chilkat_v9_5_0_TLB;

Object Creation

var
obj: TChilkatGlobal;
...
begin
obj := TChilkatGlobal.Create(Self);
...
// When finished, free the object instance.
obj.Free();

Properties

AnsiCodePage
property AnsiCodePage: Integer
Introduced in version 9.5.0.49

The default ANSI code page is determined at runtime based on the computer where the application happens to be running. For example, the ANSI code page for an application running on a Japanese computer is likely to be Shift_JIS (code page 932), whereas on a US-English computer it would be iso-8859-1 (or Windows-1252 which is essentially a superset of iso-8859-1).

If there is a desire for the Chilkat library to use a specific ANSI code page regardless of locale, then this property should be set to the desired code page. The default value of this property is the ANSI code page of the local computer.

top
DebugLogFilePath
property DebugLogFilePath: WideString

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

top
DefaultNtlmVersion
property DefaultNtlmVersion: Integer
Introduced in version 9.5.0.52

Selects the default NTLM protocol version to use for NTLM authentication for HTTP, POP3, IMAP, SMTP, and HTTP proxies. The default value is 2. This property may optionally be set to 1.

More Information and Examples
top
DefaultUtf8
property DefaultUtf8: Integer
Introduced in version 9.5.0.49

Applies only to programming languages where each class has the Utf8 property, and where strings are passed and returned as multibyte (null-terminated sequences of bytes). This includes the multibyte C/C++ API, Perl, Python 2.* (not Python 3.*), Ruby, and PHP. This does not include Java, Objective-C, or Python 3.* as all strings in these languages are utf-8. This property has no effect in programming languages or APIs that return Unicode or strings as objects (such as .NET).

A Chilkat class's Utf8 property controls whether strings are returned as utf-8 or ANSI. It also controls how Chilkat is to interpret the bytes of passed-in arguments. It must be set to 0 if the application is passing ANSI strings (i.e. the byte representation is ANSI), and must be set to 1 if the application is passing string arguments using the utf-8 representation.

This global Utf8 property controls the default setting of the Utf8 property for all Chilkat objects. Thus it allows for an application to be entirely in "utf-8 mode" or "ANSI mode" without needing to explicity set the Utf8 property of every Chilkat object instance.

More Information and Examples
top
DnsTimeToLive
property DnsTimeToLive: Integer
Introduced in version 9.5.0.49

If DNS caching is enabled, this is the time-to-live (in seconds) for a cached DNS lookup. A DNS lookup result older than this expiration time is discarded, and causes a new DNS lookup to occur. A value of 0 indicates an infinite time-to-live. The default value of this property is 0.

top
EnableDnsCaching
property EnableDnsCaching: Integer
Introduced in version 9.5.0.49

Controls whether DNS domain lookups (to resolve to IP addresses) are cached in memory. The default value is 0, meaning that DNS caching is disabled.

top
KeepBinaryResult
property KeepBinaryResult: Integer
Introduced in version 9.5.0.53

If set to 1, then the binary data returned by any method will be persisted in memory in the LastBinaryResult property. This allows for an ActiveX running in the SQL Server environment to access large varbinary return values via temp tables. The method would be called, and then the LastBinaryResult property would be fetched to get the full contents of the returned string.

top
KeepStringResult
property KeepStringResult: Integer
Introduced in version 9.5.0.52

If set to 1, then the string returned by any method will be persisted in memory in the LastStringResult property. This allows for an ActiveX running in the SQL Server environment to access large string return values via temp tables. The method would be called, and then the LastStringResult property would be fetched to get the full contents of the returned string.

Important: When this property = 1, all Chilkat methods that return strings will return the empty string. The string return value is available in the LastStringResult property.

top
LastBinaryResult
property LastBinaryResult: OleVariant readonly

The binary data returned by the last (binary data returning) method called. Only available if Chilkat.Global.KeepBinaryResult is set to 1. This provides a means for obtaining large varbinary results in the SQL Server environment (where limitations exist in getting large amounts of data returned by method calls, but where temp tables can be used for binary properties).

top
LastErrorHtml
property LastErrorHtml: WideString readonly

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastErrorText
property LastErrorText: WideString readonly

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastErrorXml
property LastErrorXml: WideString readonly

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastMethodSuccess
property LastMethodSuccess: Integer

Indicate whether the last method call succeeded or failed. A value of 1 indicates success, a value of 0 indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = 1 and failure = 0.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to 1. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

top
LastStringResult
property LastStringResult: WideString readonly

The string return value of the last (string returning) method called. Only available if Chilkat.Global.KeepStringResult is set to 1. This provides a means for obtaining large string results in the SQL Server environment (where limitations exist in getting long strings returned by method calls, but where temp tables can be used for string properties).

top
LastStringResultLen
property LastStringResultLen: Integer readonly

The length, in characters, of the string contained in the LastStringResult property.

top
MaxThreads
property MaxThreads: Integer
Introduced in version 9.5.0.52

The maximum number of thread pool threads. The default value is 100. The maximum value is 500. Note: Asynchronous worker threads are created on as needed up to the maximum.

More Information and Examples
top
PreferIpv6
property PreferIpv6: Integer
Introduced in version 9.5.0.70

If 1, then use IPv6 over IPv4 when both are supported for a particular domain. The default value of this property is 0, which will choose IPv4 over IPv6.

Note: Setting this property has the effect of also setting the default value of the PreferIpv6 property for other classes.

top
ThreadPoolLogPath
property ThreadPoolLogPath: WideString
Introduced in version 9.5.0.52

If set, indicates the path of a log file to be used by the thread pool thread and each of the pool worker threads for logging async activity. Chilkat always appends to the log file. If the log file already exists, then new information will be appended.

More Information and Examples
top
UncommonOptions
property UncommonOptions: WideString
Introduced in version 9.5.0.90

This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.

top
UnlockStatus
property UnlockStatus: Integer readonly
Introduced in version 9.5.0.62

Indicates the unlocked status for the last call to UnlockBundle, or any UnlockComponent call. The possible values are:

  1. Not unlocked. (Still in locked state.)
  2. Unlocked with in fully-functional trial mode.
  3. Unlocked using a valid purchased unlock code.

Note: If UnlockComponent or UnlockBundle is called with a purchased unlock code, the UnlockStatus is correctly set to the value 2. This value is intentionally sticky. If a subsequent and redundant call to UnlockComponent (or UnlockBundle) happens, it is effectively a "No-Op" because the library is already unlocked. The UnlockStatus will not change.

If however, if the 1st call resulted in UnlockStatus = 1, and THEN the unlock method is called again with a purchased unlock code, the UnlockStatus should change from 1 to 2.

top
UsePkcsConstructedEncoding
property UsePkcsConstructedEncoding: Integer
Introduced in version 9.5.0.70

This property should typically be left at the default value of 0. If set to 1, then Chilkat will use a constructed ASN.1 encoding for PCKS7 data. (This is an internal implementation option that normally does not matter, and should not matter. Some PKCS7 receiving systems might be picky, and this option can be used to satisfy this requirement.)

top
VerboseLogging
property VerboseLogging: Integer

If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
VerboseTls
property VerboseTls: Integer
Introduced in version 9.5.0.78

If set to 1, then causes extremely verbose logging (in LastErrorText) all TLS connections in any Chilkat class. This property should only be used for troubleshooting TLS problems. The default value is 0.

Note: This property only has effect on Chilkat objects not yet created. Set the property first, then instantiate the Chilkat object.

top
Version
property Version: WideString readonly

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

More Information and Examples
top

Methods

DnsClearCache
function DnsClearCache(): Integer;
Introduced in version 9.5.0.49

Clears the global DNS cache.

Returns 1 for success, 0 for failure.

top
FinalizeThreadPool
function FinalizeThreadPool(): Integer;
Introduced in version 9.5.0.56

Called to stop and finalize all threads in the thread pool, and causes the thread pool thread to exit.

The following behaviors exist in v9.5.0.64 and later:

  • All remaining asynchronous tasks are automatically canceled.
  • Restores the thread pool to it's pristine state where no background threads are running.

It is a good idea to call this method at the very end of a program, just before it exits. This is especially true for programs written in VBScript, VB6, FoxPro, and PowerBuilder.

Returns 1 for success, 0 for failure.

top
ThreadPoolLogLine
function ThreadPoolLogLine(str: WideString): Integer;
Introduced in version 9.5.0.77

Logs a line to the thread pool log file.

Returns 1 for success, 0 for failure.

top
UnlockBundle
function UnlockBundle(bundleUnlockCode: WideString): Integer;
Introduced in version 9.5.0.49

Unlocks the entire Chilkat API for all classes. This should be called once at the beginning of a program. Once unlocked, objects of any Chilkat class may be instantiated and used. To unlock in fully-functional 30-day trial mode, pass any string, such as "Hello", in bundleUnlockCode. If a license is purchased, then replace the "Hello" with the purchased unlock code.

After calling UnlockBundle once, the instance of the TChilkatGlobal object may be discarded/deleted (assuming the programming language requires explicit deletes). Multiple calls to UnlockComponent are harmless. If the Chilkat API is already unlocked, the duplicate calls to UnlockBundle are no-ops.

Important: Unlocking sets a flag in memory to indicate the unlocked status. There are no licensing files, and there is no communication with any Chilkat servers. This means your application, script, etc. must call UnlockBundle once at the start each time it runs. The good thing is that your application can run on any computer -- there are no licensing files to worry about. Also: If an application forgets to call UnlockBundle, Chilkat will automatically unlock in trial mode, and this will eventually fail when the trial runs out. If you purchased a license, it is very important to make sure you call UnlockBundle with the purchased unlock code.

Returns 1 for success, 0 for failure.

top