Chilkat for Embarcadero® C++ Builder®

using Chilkat C++ over CBridge in C++ Builder

Windows 32-bit (bcc32c and classic bcc32) · Windows 64-bit (bcc64) · Windows 64-bit Modern (bcc64x)

Starting with Chilkat v11.7.0, C++ Builder projects use Chilkat C++ over CBridge in place of the Chilkat static libraries for C++ Builder. It is the same Chilkat C++ API — the same classes and the same header files — so existing code compiles unchanged. What changes is how the project is built: you add one Chilkat source file to the project, link an import library, and ship one Chilkat DLL with your application. The same download is used with every C++ Builder version and compiler.

Download

This is the full-version Chilkat product. Chilkat libraries are fully functional for a 30-day evaluation; no separate trial build is required.

The files you need

The download contains the Chilkat headers (include), the wrapper sources (src), and the Chilkat DLLs with their Visual C++ import libraries (lib). Which DLL and which import library you use depends on the target platform of your project:

The other folders under lib (Windows ARM64, Linux, Alpine Linux, macOS) are for other compilers and are not used by C++ Builder.

Step 1: Create the import library

The .lib files in the download are in the Visual C++ format. The Windows 64-bit (Modern) compiler links them as they are. The other C++ Builder compilers need an import library in their own format, which C++ Builder's own tools create from the DLL. Do this once, and again whenever you update to a new Chilkat version.

Open the RAD Studio Command Prompt (or run rsvars.bat from the bin folder of your C++ Builder installation in a command prompt), change to C:\chilkat-cpp-bridge, and run the command for your target platform:

Windows 32-bit (bcc32c and bcc32)

implib -a -c chilkat_c_bridge_win32_omf.lib lib\windows-x86\chilkat_c_bridge_win32.dll

The -a option is required: it adds the underscore-prefixed names that the 32-bit compilers use for the DLL's cdecl functions. -c keeps the names case-sensitive.

Windows 64-bit (bcc64)

mkexp chilkat_c_bridge_x64.a lib\windows-x64\chilkat_c_bridge_x64.dll

Windows 64-bit (Modern) (bcc64x)

Nothing to create. Link lib\windows-x64\chilkat_c_bridge_x64.lib directly.

Step 2: Set up the project

1. Add the include paths. In Project > Options, add both of these folders to the include path of the project:

   C:\chilkat-cpp-bridge\include
   C:\chilkat-cpp-bridge\src

2. Add the wrapper source to the project. Use Project > Add to Project and select C:\chilkat-cpp-bridge\src\ChilkatCppBridgeAll.cpp. This one file includes all of the other files in src, so it is the only Chilkat source file to add. (Alternatively, add every .cpp file in src except ChilkatCppBridgeAll.cpp. Never add both.)
3. Add the import library to the project. Use Project > Add to Project again and select the import library for the target platform, from the table above.
4. Copy the DLL next to the executable. Copy the Chilkat DLL for the target platform into the folder where the project's .exe is written, for example Win32\Debug, Win64\Debug or Win64x\Debug under the project folder. A 32-bit program needs chilkat_c_bridge_win32.dll; a 64-bit program needs chilkat_c_bridge_x64.dll.
5. Include the Chilkat headers after the VCL or FireMonkey headers. In each source file that uses Chilkat, put the Chilkat #include lines after #include <vcl.h> or #include <fmx.h> (see the first of the notes below).

Step 3: Use Chilkat in your code

In C++ Builder, String is a UnicodeString (wchar_t characters on Windows). The Chilkat wide-character classes — the class name followed by W, such as CkHttpW — take and return const wchar_t *, so they work directly with String and are the natural choice in VCL and FireMonkey applications. The classes without the W (CkHttp) take and return const char *: ANSI by default, or UTF-8 after calling put_Utf8(true) on the object.

The following is the click handler of a button on a VCL form that also has an edit box and a memo. It unlocks Chilkat, AES-encrypts the text of the edit box, and decrypts it again.

#include <vcl.h>
#pragma hdrstop

#include "Unit1.h"
#include "CkGlobalW.h"
#include "CkCrypt2W.h"

// ...

void __fastcall TForm1::Button1Click(TObject *Sender)
{
    // Unlock once, at program start.  Any string begins the fully functional 30-day trial.
    CkGlobalW glob;
    if (!glob.UnlockBundle(L"Anything for 30-day trial"))
    {
        Memo1->Lines->Add(glob.lastErrorText());
        return;
    }

    CkCrypt2W crypt;
    crypt.put_CryptAlgorithm(L"aes");
    crypt.put_CipherMode(L"cbc");
    crypt.put_KeyLength(256);
    crypt.put_PaddingScheme(0);
    crypt.put_EncodingMode(L"hex");
    crypt.SetEncodedIV(L"000102030405060708090A0B0C0D0E0F", L"hex");
    crypt.SetEncodedKey(
        L"000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F", L"hex");

    const wchar_t *enc = crypt.encryptStringENC(Edit1->Text.c_str());
    if (!enc)
    {
        Memo1->Lines->Add(crypt.lastErrorText());
        return;
    }
    String encrypted = enc;     // copy the returned string into a String
    Memo1->Lines->Add(String(L"Encrypted: ") + encrypted);

    const wchar_t *dec = crypt.decryptStringENC(encrypted.c_str());
    if (!dec)
    {
        Memo1->Lines->Add(crypt.lastErrorText());
        return;
    }
    Memo1->Lines->Add(String(L"Decrypted: ") + dec);
}

Call UnlockBundle once when the program starts, for example in the main form's constructor. With a purchased license, pass your unlock code in place of the trial string.

Documentation & Samples

• 📖 Unicode C++ Reference Documentation — the wide-character (W) classes
• 📖 C++ Reference Documentation — the const char * classes
• 💻 Unicode C++ Sample Code and C++ Sample Code
• 📄 Chilkat C++ over CBridge — the same download for Visual C++, MinGW, Linux, and macOS
• 📝 Release Notes on the Chilkat blog

Building from the command line

The download includes a small console program, examples\quickstart.cpp. The commands below build and run it. Run them in the RAD Studio Command Prompt, from the C:\chilkat-cpp-bridge folder. The wrapper is compiled once to an object file, which is then linked with the program.

Windows 64-bit (Modern): bcc64x

copy examples\quickstart.cpp .
bcc64x -c -O1 -Iinclude -Isrc -oChilkatCppBridgeAll.o src\ChilkatCppBridgeAll.cpp
bcc64x -Iinclude -Isrc quickstart.cpp ChilkatCppBridgeAll.o lib\windows-x64\chilkat_c_bridge_x64.lib -o quickstart.exe
copy lib\windows-x64\chilkat_c_bridge_x64.dll .
quickstart.exe

A program built this way also needs C++ Builder's own C++ runtime DLLs when it runs. They are in the x86_64-w64-mingw32\bin folder of the C++ Builder installation; add that folder to the PATH.

Windows 32-bit: bcc32c (or bcc32)

copy examples\quickstart.cpp .
implib -a -c chilkat_c_bridge_win32_omf.lib lib\windows-x86\chilkat_c_bridge_win32.dll
bcc32c -c -O1 -Iinclude -Isrc -oChilkatCppBridgeAll.obj src\ChilkatCppBridgeAll.cpp
bcc32c -Iinclude -Isrc quickstart.cpp ChilkatCppBridgeAll.obj chilkat_c_bridge_win32_omf.lib
copy lib\windows-x86\chilkat_c_bridge_win32.dll .
quickstart.exe

For the classic compiler, use bcc32 in place of bcc32c in both commands.

Windows 64-bit: bcc64

copy examples\quickstart.cpp .
mkexp chilkat_c_bridge_x64.a lib\windows-x64\chilkat_c_bridge_x64.dll
bcc64 -c -O1 -Iinclude -Isrc -oChilkatCppBridgeAll.o src\ChilkatCppBridgeAll.cpp
bcc64 -Iinclude -Isrc quickstart.cpp ChilkatCppBridgeAll.o chilkat_c_bridge_x64.a
copy lib\windows-x64\chilkat_c_bridge_x64.dll .
quickstart.exe

Moving a project from the Chilkat static libraries

If your project links one of the Chilkat static libraries for C++ Builder (chilkat_clang_win32.lib, chilkat_clang_win64.lib, chilkat_classic_win32.lib or chilkat_classic_win64.a):

1. Remove the Chilkat static library from the project. The wrapper and a Chilkat static library must not be linked into the same program.
2. Replace the old Chilkat include folder in the project's include path with the include and src folders of this download.
3. Follow steps 1 and 2 above. Your source code does not need to change, apart from the differences listed in the notes below.
4. Add the Chilkat DLL to your installer. A program that used a static library had no Chilkat file to deploy; it now has one.

Important notes

• Use src and the DLL from the same download. The wrapper checks the DLL's interface version when the program runs. With a DLL from another Chilkat version no Chilkat object is created, every method fails, and lastErrorText() says why. When you update Chilkat, replace include, src and the DLL together, and create the import library again.
• 32-bit programs use chilkat_c_bridge_win32.dll from lib\windows-x86. This is the cdecl build. The wrapper refuses to use the stdcall build of the DLL that ships with some other Chilkat products.
• Events: the CkBaseProgress callbacks AbortCheck, PercentDone, ProgressInfo and TaskCompleted are delivered. The class-specific progress callbacks (CkZipProgress, CkMailManProgress, CkHttpProgress, CkFtp2Progress, CkSFtpProgress, CkTarProgress, …) are not called; code that overrides them still compiles.
• Asynchronous methods: TaskCompleted may arrive after CkTask::Wait() returns.
• The wide-character classes (CkHttpW, …) are included. The UTF-16 Ck*U classes, CkRegistry and CkService are not.
• LastErrorText reports the language as "C++ CBridge".

Deploying your application

The Chilkat DLL is the only Chilkat file to deploy. Install it in the same folder as your executable: chilkat_c_bridge_win32.dll with a 32-bit program, chilkat_c_bridge_x64.dll with a 64-bit program. Nothing is registered. The DLLs are code-signed. The import library, the headers and the wrapper sources are needed only to build.

Troubleshooting

For anything else, contact Chilkat support and include the contents of lastErrorText().

"C++Builder" and "Embarcadero" are registered trademarks of Embarcadero Technologies.