Global C++ Reference Documentation

CkGlobal

Current Version: 10.1.0

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

Object Creation

// Local variable on the stack
CkGlobal obj;

// Dynamically allocate/delete
CkGlobal *pObj = new CkGlobal();
// ...
delete pObj;

Properties

AnsiCodePage

int get_AnsiCodePage(void);
void put_AnsiCodePage(int newVal);

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.

AutoQBDecode

bool get_AutoQBDecode(void);
void put_AutoQBDecode(bool newVal);

Introduced in version 10.0.0

If set to true, then "Q" or "B" encoded strings can be passed in any string argument to any Chilkat method, and Chilkat will automatically decode the string before using it. This is meant to be a convenient way to use non-usascii literal strings in your source code. See the links below for an example and for a discussion about non-usascii literal strings.

More Information and Examples

Demonstrate the Global.AutoQBDecode property Avoid Non-usascii Literal Strings in Source Code

DebugLogFilePath

void get_DebugLogFilePath(CkString &str);
const char *debugLogFilePath(void);
void put_DebugLogFilePath(const char *ansiOrUtf8Str);

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.

More Information and Examples

Example showing how to use DebugLogFilePath.

DefaultNtlmVersion

int get_DefaultNtlmVersion(void);
void put_DefaultNtlmVersion(int newVal);

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

Set Default NTLM Protocol Version (v1 or v2)

DefaultUtf8

bool get_DefaultUtf8(void);
void put_DefaultUtf8(bool newVal);

Introduced in version 9.5.0.49

This applies to programming languages where each class has a Utf8 property and strings are handled as multibyte, null-terminated byte sequences. Relevant languages include the multibyte C/C++ API, Perl, Python 2.*, Ruby, and PHP, but not Java, Objective-C, or Python 3.*, where strings are inherently UTF-8. Languages that handle strings as Unicode objects, such as .NET, are also excluded.

For Chilkat classes, the Utf8 property determines whether strings are returned as UTF-8 or ANSI and guides how Chilkat interprets incoming string arguments. Set this property to false if passing ANSI strings, and true if using UTF-8 encoded strings.

The global Utf8 property sets the default for all Chilkat objects, allowing an application to run entirely in "UTF-8 mode" or "ANSI mode" without needing to adjust the Utf8 property for each Chilkat object individually.

The default value of this property is false.

Important: In a future major version release, the default value of this property will change to true. It is recommended to explicitly set this property at the start of your application.

More Information and Examples

Set Default to utf-8 instead of ANSI

DnsTimeToLive

int get_DnsTimeToLive(void);
void put_DnsTimeToLive(int newVal);

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.

EnableDnsCaching

bool get_EnableDnsCaching(void);
void put_EnableDnsCaching(bool newVal);

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 false, meaning that DNS caching is disabled.

LastErrorHtml

void get_LastErrorHtml(CkString &str);
const char *lastErrorHtml(void);

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.

LastErrorText

void get_LastErrorText(CkString &str);
const char *lastErrorText(void);

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.

More Information and Examples

Concept of LastErrorText LastErrorText Standard Information

LastErrorXml

void get_LastErrorXml(CkString &str);
const char *lastErrorXml(void);

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.

LastMethodSuccess

bool get_LastMethodSuccess(void);
void put_LastMethodSuccess(bool newVal);

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.

MaxThreads

int get_MaxThreads(void);
void put_MaxThreads(int newVal);

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

Thread Pool Size

PreferIpv6

bool get_PreferIpv6(void);
void put_PreferIpv6(bool newVal);

Introduced in version 9.5.0.70

If true, then use IPv6 over IPv4 when both are supported for a particular domain. The default value of this property is false, 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.

ThreadPoolLogPath

void get_ThreadPoolLogPath(CkString &str);
const char *threadPoolLogPath(void);
void put_ThreadPoolLogPath(const char *ansiOrUtf8Str);

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

Thread Pool Size

UncommonOptions

void get_UncommonOptions(CkString &str);
const char *uncommonOptions(void);
void put_UncommonOptions(const char *ansiOrUtf8Str);

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.

UnlockStatus

int get_UnlockStatus(void);

Introduced in version 9.5.0.62

Indicates the unlocked status for the last call to UnlockBundle. The possible values are:

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

Note: If 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 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.

UsePkcsConstructedEncoding

bool get_UsePkcsConstructedEncoding(void);
void put_UsePkcsConstructedEncoding(bool newVal);

Introduced in version 9.5.0.70

This property should typically be left at the default value of false. If set to true, 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.)

Utf8

bool get_Utf8(void);
void put_Utf8(bool newVal);

When set to true, all "const char *" arguments are interpreted as utf-8 strings. If set to false (the default), then "const char *" arguments are interpreted as ANSI strings. Also, when set to true, and Chilkat method returning a "const char *" is returning the utf-8 representation. If set to false, all "const char *" return values are ANSI strings.

VerboseLogging

bool get_VerboseLogging(void);
void put_VerboseLogging(bool newVal);

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.

VerboseTls

bool get_VerboseTls(void);
void put_VerboseTls(bool newVal);

Introduced in version 9.5.0.78

If set to true, 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 false.

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

Version

void get_Version(CkString &str);
const char *version(void);

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

More Information and Examples

How to get the Chilkat version at runtime.

Methods

DnsClearCache

bool DnsClearCache(void);

Introduced in version 9.5.0.49

Clears the global DNS cache.

Returns true for success, false for failure.

FinalizeThreadPool

bool FinalizeThreadPool(void);

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 true for success, false for failure.

ThreadPoolLogLine

bool ThreadPoolLogLine(const char *str);

Introduced in version 9.5.0.77

Logs a line to the thread pool log file.

Returns true for success, false for failure.

UnlockBundle

bool UnlockBundle(const char *bundleUnlockCode);

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 CkGlobal object may be discarded/deleted (assuming the programming language requires explicit deletes). Multiple calls to UnlockBundle 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 true for success, false for failure.

More Information and Examples

Call UnlockBundle Only Once at the Beginning of a Program Global Unlock