TDLib 总览与构建

GetTGAPI 阅读提示

本文依据上方所列版本的 TDLib 文档，正文中的“上游”“官方”指 TDLib 项目。构建步骤请结合自己的操作系统和依赖版本验证。

注意：编译库要求 C++17，与其他文档提到的 C++11 调用接口不是同一个要求；JSON 接口的二进制兼容，也不等于各版 API 方法和字段完全相同。原文的内存和活跃机器人数字是上游特定场景说明，不能直接用于估算你的服务器容量。运行恢复文档的 git checkout 命令前，应先保护相关文件中的本地修改。

本专题按编译与接口概念阅读，申请步骤另见 API ID / Hash 申请教程。GetTGAPI（gettgapi.com）提供开发者门户申请协助；取得应用凭证不等于完成用户账号授权。需要人工判断申请问题，可通过联系客服沟通。

TDLib

TDLib（Telegram Database library，Telegram 数据库库）是用于构建 Telegram 客户端的跨平台库，几乎可以从任何编程语言中便捷地使用。

特性

TDLib 有许多优势，尤其包括：

跨平台：TDLib 可用于 Android、iOS、Windows、macOS、Linux、FreeBSD、OpenBSD、NetBSD、illumos、Windows Phone、WebAssembly、watchOS、tvOS、visionOS、Tizen、Cygwin。它也应该能在其他 *nix 系统上工作，或者只需要少量适配。
多语言：凡是能够执行 C 函数的编程语言，都可以便捷地使用 TDLib。此外，它已提供原生 Java 绑定（使用 JNI）和 .NET 绑定（使用 C++/CLI 和 C++/CX）。
易用：TDLib 负责全部网络实现细节、加密和本地数据存储。
高性能：在 Telegram Bot API 中，每个 TDLib 实例同时处理超过 43000 个活跃机器人。
文档完整：全部 TDLib API 方法和公共接口都有完整文档。
一致性：TDLib 保证按正确顺序交付所有更新。
可靠：TDLib 在缓慢、不可靠的互联网连接上仍能保持稳定。
安全：所有本地数据都使用用户提供的加密密钥加密。
完全异步：发往 TDLib 的请求不会相互阻塞，也不会阻塞其他操作；响应就绪后即可返回。

示例与文档

基本概念请参阅官方 Getting Started 入门教程。

也可以查看官方示例。

详细构建步骤见 TDLib 构建说明生成器。

接口说明分别见 JSON、C++、Java 和 .NET 章节。

全部 TDLib 方法和类可在 td_api.tl 模式定义或自动生成的 HTML 文档中查阅。

依赖

TDLib 依赖以下组件：

兼容 C++17 的编译器：Clang 5.0+、GCC 7.0+、MSVC 19.1+（Visual Studio 2017.7+）、Intel C++ Compiler 19+。
OpenSSL。
zlib。
gperf（仅构建时需要）。
CMake（3.10+，仅构建时需要）。
PHP（可选，用于生成文档）。

构建

构建 TDLib 最简单的方式是使用官方 TDLib 构建说明生成器。选择编程语言和目标操作系统，即可获得完整构建步骤。

通常，先安装全部 TDLib 依赖，进入 TDLib 源码目录，再使用 CMake 编译：

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

在内存较少的设备上构建 TDLib 时，可以在编译源码之前运行 SplitSource.php 脚本，并只编译需要的目标：

php SplitSource.php
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --target tdjson
cmake --build . --target tdjson_static
cd ..
php SplitSource.php --undo

在上游作者的测试中，clang 6.0 配合 libc++ 编译每个文件所需 RAM 少于 500 MB，GCC 4.9/6.3 编译每个文件所需 RAM 少于 1 GB。

在 CMake C++ 项目中使用

对于使用 CMake 的 C++ 项目，最佳方式是把 TDLib 作为项目的一部分构建，或将它安装到系统中。

可以在 CMake 项目中使用以下库：

Td::TdJson、Td::TdJsonStatic：JSON 接口的动态库与静态库版本。它们提供简单的 C 接口，便于能够执行 C 函数的编程语言使用。更多信息见 td_json_client 文档。
Td::TdStatic：提供通用 C++ 接口的静态库。更多信息见 ClientManager 和 Client 文档。

例如，CMakeLists.txt 的一部分可以这样写：

add_subdirectory(td)
target_link_libraries(YourTarget PRIVATE Td::TdStatic)

也可以先安装 TDLib，再在 CMakeLists.txt 中引用：

find_package(Td 1.8.68 REQUIRED)
target_link_libraries(YourTarget PRIVATE Td::TdStatic)

参见 example/cpp/CMakeLists.txt。

在 Java 项目中使用

TDLib 通过 JNI 提供原生 Java 接口。启用时，向 CMake 传入 -DTD_ENABLE_JNI=ON 选项。

Java 使用示例及详细构建、使用说明见 example/java。

在 .NET 项目中使用

TDLib 通过 C++/CLI 和 C++/CX 提供原生 .NET 接口。启用时，分别向 CMake 传入 -DTD_ENABLE_DOTNET=ON 或 -DTD_ENABLE_DOTNET=CX。

.NET Core 从 3.1 版本起才支持 C++/CLI，且仅在 Windows 上支持。因此，如果使用更早的 .NET Core，或需要可移植性，应改为通过 P/Invoke 使用 TDLib JSON 接口。

C# 使用示例及详细构建、使用说明见 example/csharp。C# UWP 应用的使用示例，以及 Visual Studio 扩展“TDLib for Universal Windows Platform”的详细构建、使用说明见 example/uwp。

启用 TD_ENABLE_DOTNET 选项构建 TDLib 时，一些文件中的 C++ 文档会被移除。要恢复这些 C++ 文档，需要检出这些文件：

git checkout td/telegram/Client.h td/telegram/Log.h td/tl/TlObject.h

从其他编程语言中使用

TDLib 提供高效的原生 C++、Java 和 .NET 接口。不过，上游针对大多数使用场景建议采用 JSON 接口；凡是能执行 C 函数的编程语言，都能便捷地使用它。

JSON 接口的详细说明见 td_json_client。全部 TDLib 方法和类见 td_api.tl 模式定义或自动生成的 HTML 文档。

TDLib JSON 接口遵循语义化版本规则，主版本号相同的版本在二进制层面保持兼容并向后兼容；但底层 TDLib API 在不同次版本，甚至不同补丁版本之间，都可能发生变化。

如果需要支持多个 TDLib 版本，可以读取 version 选项的值，确定准确版本，再使用相应的 API 方法。

这种用法的示例见 example/python/tdjson_example.py。

许可

TDLib 采用 Boost Software License。更多信息见 LICENSE_1_0.txt。