Native C API

Native C API Reference: functions, types and enumerations.

New to TFORMer? Create your first PDF with the Native C/C++ Quick Start. It includes a complete Windows C++ example using the native C API and its form layout. Continue here for interface details and Linux setup.

Introduction

The native C API exposes the TFormer function family through a Windows DLL or a Linux shared library. String types depend on the target platform:

• Windows: Provides narrow char/LPCSTR and Unicode wchar_t/LPCWSTR entry points.
• Linux: Uses UTF-8 char strings.

The T-suffixed function names in TFormer.h select the platform-appropriate source mapping.

Use the native C API directly from C or C++, or from another environment that can call the platform's native application binary interface. Use the dedicated .NET, COM, or Java interface when it provides a more natural integration for the application.

Choose the build instructions for your platform:

• Windows: Start with Build on Windows, then follow the PDF example.
• Linux: Start with Build on Linux, which describes the supplied build script and sample.

Build on Windows

Install the SDK's native components and samples as described in Installation on Microsoft Windows.

Include the public header TFormer.h and link the import library that matches the application architecture:

• 32-bit: TFormer9.lib and TFormer9.dll
• 64-bit: TFormer9x64.lib and TFormer9x64.dll

The SDK places the header, import libraries, and runtime DLLs in its Bin directory:

• C:\Program Files\TEC-IT\TFORMer9 SDK\Bin
• C:\Program Files (x86)\TEC-IT\TFORMer9 SDK\Bin

Configure the compiler and linker to use that directory, and keep the import library and runtime DLL from the same SDK release.

Before running the application, make the matching native runtime files available to it; see Windows deployment requirements. Configuring compiler and linker paths does not deploy these files.

Apply a License

Apply your license before generating output. With the public header included as described above, the following fragment can be used in main before creating the form handle:

ERRCODE licenseResult = TFormer_LicenseBase64(
    "BASE64_LICENSE_DATA_FROM_TEC_IT");
if (licenseResult != ErrOk)
    return 1;

Replace the placeholder with the Base64 license data supplied by TEC-IT and keep it confidential. Check the return code and handle licensing errors before proceeding. See Licensing for license types, validity and file-based licensing.

If you received a license file, use TFormer_LicenseFile; for individual license values, use TFormer_License. Apply either alternative before generating output and check its return code.

Build on Linux

Current Linux packages provide the same native function family in libTFORMer9.so. The package installs:

• TFormer.h below /usr/local/include/TFORMer9/
• supporting headers below /usr/local/include/TFORMer9/TECITStd/
• the complete shared-library chain below /usr/local/lib/

The installed Linux sample includes the public headers as <TFORMer9/TECITStd/TECITStd.h> and <TFORMer9/TFormer.h>. Use the supplied build_sample.sh as the canonical build route. The script selects the required platform options and links the sample with the installed TFORMer shared library.

For your own Linux application, define TECIT_DLLIMPORT, _TEC_UNIX, TEC_UNIX_BUILD, and TEC_LINUX before including TECITStd/TECITStd.h and then TFormer.h from the installed header directory. The supplied sample defines the first three in its source; build_sample.sh supplies TEC_LINUX through the compiler command line.

The current package provides a shared library; do not assume that a static archive is included.

The native C sample and generated programming references are installed in:

• /usr/local/share/TFORMer9/Examples/C Command Line
• /usr/local/share/TFORMer9/APIDocs

Additional programming samples are located below:

/usr/local/share/TFORMer9/Examples

Before running or distributing your application, check the Linux deployment requirements and the Linux configuration file location.

Use TFORMer from Python

Call the native C API from Python with the standard-library ctypes module. This Windows example imports two product records from CSV and creates a PDF; it does not require a separate Python SDK.

Prepare the Example

1. Install the 64-bit TFORMer SDK and use 64-bit Python 3.8 or later. Python and the SDK DLL must have the same architecture.
2. Download the CSV/XML sample files and extract them. For this example, use only ProductLabel.tff and Data.csv; the included .NET project is not needed.
3. Save the following code as product_label.py beside those two files. Adjust sdk_bin if the SDK is installed elsewhere, then run python product_label.py from that directory.

Complete Example

import ctypes as ct
import os
from pathlib import Path

sdk_bin = Path(r"C:\Program Files\TEC-IT\TFORMer9 SDK\Bin")
folder = Path(__file__).resolve().parent
output = folder / "ProductLabel.pdf"

if ct.sizeof(ct.c_void_p) != 8:
    raise RuntimeError("This example requires 64-bit Python and the 64-bit SDK.")

# Keep the SDK's dependency directory available until the job is finished.
with os.add_dll_directory(str(sdk_bin)):
    sdk = ct.WinDLL(str(sdk_bin / "TFormer9x64.dll"))

    def bind(name, result_type, *argument_types):
        function = getattr(sdk, "TFormer_" + name)
        function.restype = result_type
        function.argtypes = list(argument_types)
        return function

    # Explicit types preserve the 64-bit handle and Windows Unicode strings.
    init = bind("Init", ct.c_void_p, ct.c_void_p)
    close = bind("Exit", ct.c_long, ct.c_void_p)
    set_layout = bind("SetRepositoryNameW", ct.c_long,
                      ct.c_void_p, ct.c_wchar_p)
    set_csv = bind("SetTxtDataFileW", ct.c_long,
                   ct.c_void_p, ct.c_wchar_p, ct.c_wchar, ct.c_wchar)
    set_output = bind("SetPrinterNameW", ct.c_long,
                      ct.c_void_p, ct.c_wchar_p, ct.c_void_p)
    print_job = bind("Print", ct.c_long, ct.c_void_p)
    last_error = bind("GetLastErrorDescriptionW", ct.c_wchar_p, ct.c_void_p)

    form = init(None)
    if not form:
        raise RuntimeError("TFORMer initialization failed.")

    def check(code):
        if code != 0:
            raise RuntimeError(f"TFORMer error {code}: {last_error(form)}")

    try:
        # Load the layout and import CSV with comma and double-quote delimiters.
        check(set_layout(form, str(folder / "ProductLabel.tff")))
        check(set_csv(form, str(folder / "Data.csv"), ",", '"'))
        # PDF: selects the output type and filename together.
        check(set_output(form, "PDF:" + str(output), None))
        check(print_job(form))
    finally:
        close(form)

print(f"Created {output}")

Open ProductLabel.pdf to check the two product labels. A new run replaces that file. Without a valid license, output may contain demo markings or demo notices in place of content; see Licensing.

The W functions used here accept Windows Unicode strings. For other functions, declare the argument and return types from TFormer.h before calling them. See Build on Linux for the different library and string conventions; this example is Windows-specific.

If you prefer to run a separate command instead of loading a native library into Python, call TFPrint with Python's subprocess.run(..., check=True). Reuse the TFPrint Quick Start for the command and files.

Reference and Sample Links

Use the native C programming reference and the maintained samples supplied with the selected SDK release. See also Working with Data and Configuration.