Global C Reference Documentation

Global

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

Create/Dispose

HCkGlobal CkGlobal_Create(void);

Creates an instance of the HCkGlobal object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkGlobal_Dispose(HCkGlobal handle);

Objects created by calling CkGlobal_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkGlobal_Dispose.

Properties

int CkGlobal_getAnsiCodePage(HCkGlobal cHandle);

void CkGlobal_putAnsiCodePage(HCkGlobal cHandle, 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.

void CkGlobal_getDebugLogFilePath(HCkGlobal cHandle, HCkString retval);

void CkGlobal_putDebugLogFilePath(HCkGlobal cHandle, const char *newVal);

const char *CkGlobal_debugLogFilePath(HCkGlobal cHandle);

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.

int CkGlobal_getDefaultNtlmVersion(HCkGlobal cHandle);

void CkGlobal_putDefaultNtlmVersion(HCkGlobal cHandle, 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.

Set Default NTLM Protocol Version (v1 or v2)

BOOL CkGlobal_getDefaultUtf8(HCkGlobal cHandle);

void CkGlobal_putDefaultUtf8(HCkGlobal cHandle, BOOL newVal);

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 FALSE if the application is passing ANSI strings (i.e. the byte representation is ANSI), and must be set to TRUE 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.

int CkGlobal_getDnsTimeToLive(HCkGlobal cHandle);

void CkGlobal_putDnsTimeToLive(HCkGlobal cHandle, 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.

BOOL CkGlobal_getEnableDnsCaching(HCkGlobal cHandle);

void CkGlobal_putEnableDnsCaching(HCkGlobal cHandle, 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.

void CkGlobal_getLastErrorHtml(HCkGlobal cHandle, HCkString retval);

const char *CkGlobal_lastErrorHtml(HCkGlobal cHandle);

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.

void CkGlobal_getLastErrorText(HCkGlobal cHandle, HCkString retval);

const char *CkGlobal_lastErrorText(HCkGlobal cHandle);

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.

Concept of LastErrorText

LastErrorText Standard Information

void CkGlobal_getLastErrorXml(HCkGlobal cHandle, HCkString retval);

const char *CkGlobal_lastErrorXml(HCkGlobal cHandle);

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.

BOOL CkGlobal_getLastMethodSuccess(HCkGlobal cHandle);

void CkGlobal_putLastMethodSuccess(HCkGlobal cHandle, BOOL newVal);

Introduced in version 9.5.0.52

Indicate whether the last method call succeeded or failed. A value of TRUE indicates success, a value of FALSE 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 = TRUE and failure = FALSE.
  • 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 TRUE. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

int CkGlobal_getMaxThreads(HCkGlobal cHandle);

void CkGlobal_putMaxThreads(HCkGlobal cHandle, 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.

Thread Pool Size

BOOL CkGlobal_getPreferIpv6(HCkGlobal cHandle);

void CkGlobal_putPreferIpv6(HCkGlobal cHandle, 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.

void CkGlobal_getThreadPoolLogPath(HCkGlobal cHandle, HCkString retval);

void CkGlobal_putThreadPoolLogPath(HCkGlobal cHandle, const char *newVal);

const char *CkGlobal_threadPoolLogPath(HCkGlobal cHandle);

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.

Thread Pool Size

int CkGlobal_getUnlockStatus(HCkGlobal cHandle);

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.

BOOL CkGlobal_getUsePkcsConstructedEncoding(HCkGlobal cHandle);

void CkGlobal_putUsePkcsConstructedEncoding(HCkGlobal cHandle, 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.)

BOOL CkGlobal_getUtf8(HCkGlobal cHandle);

void CkGlobal_putUtf8(HCkGlobal cHandle, 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.

BOOL CkGlobal_getVerboseLogging(HCkGlobal cHandle);

void CkGlobal_putVerboseLogging(HCkGlobal cHandle, 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.

void CkGlobal_getVersion(HCkGlobal cHandle, HCkString retval);

const char *CkGlobal_version(HCkGlobal cHandle);

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

Methods

BOOL CkGlobal_DnsClearCache(HCkGlobal cHandle);

Introduced in version 9.5.0.49

Clears the global DNS cache.

Returns TRUE for success, FALSE for failure.

BOOL CkGlobal_FinalizeThreadPool(HCkGlobal cHandle);

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 and VB6.

Returns TRUE for success, FALSE for failure.

BOOL CkGlobal_SaveLastError(HCkGlobal cHandle, const char *path);

Saves the last-error information (the contents of LastErrorXml) to an XML formatted file.

Returns TRUE for success, FALSE for failure.

BOOL CkGlobal_UnlockBundle(HCkGlobal cHandle, 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 UnlockComponent once, the instance of the Global 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 UnlockComponent are no-ops.

Note: The Global's UnlockBundle method should only be called with a Bundle unlock code. If an individual product license was purchased, the UnlockComponent method in the specifically licensed class should be called instead.

Returns TRUE for success, FALSE for failure.

Call UnlockBundle Only Once at the Beginning of a Program

Global Unlock