DOCSEARCHbyAlgolia
Submit Docs

TDLib (Telegram Database library)

repository·master·Indexed 27 days ago

https://github.com/tdlib/td

A high-performance, cross-platform library for building Telegram clients. TDLib handles network implementation, encryption, and local data storage via a fully-asynchronous API. It supports multiple interfaces including C++, Java (JNI), JSON, .NET (C#), and Python, with build guides for Android, iOS, macOS, watchOS, tvOS, visionOS, and Windows.

Tokens
25.1K
Snippets
26
Records
163
Agent score
94%

What's inside TDLib

  1. Understand the Secret Group Call Encryption Architecture

    master

    Secret group calls in TDLib rely on three integrated components to ensure security and synchronization:

    1. Blockchain: A distributed ledger that manages group state (participants and shared keys). The hash of the most recent block is used to generate verification words and verification emojis for MitM protection.
    2. Encryption Protocol: An efficient protocol that encrypts video and audio frames at the media level rather than the network level. Each packet is signed for authorship verification.
    3. Emoji Generation Protocol: A two-phase commit-reveal protocol used to generate unpredictable randomness from the blockchain hash, preventing block creators from brute-forcing specific emojis.

    Security Note: MitM protection depends on all participants verifying they see identical emojis. If the server delivers different blocks to different participants, the resulting fork hashes will permanently differ.

  2. Use TDLib in Python projects

    master

    TDLib can be integrated into Python via the JSON interface. Several wrappers are available depending on your requirements:

    • Python >= 3.6: Use python-telegram (asyncio-based) or its fork pytglib.
    • Python >= 3.9 (asyncio): Use aiotdlib or Pytdbot (which uses tdjson).
    • Older Python versions: Use pytdlib.
    • SidusAI integration: Use sidusai-tdlib.

    For a basic implementation example, refer to example/python/tdjson_example.py.

  3. Pregenerate TDLib source files

    master

    If you are not building TDLib for macOS first, you must manually pregenerate the required source code files using CMake before proceeding with the Apple platform builds.

    cd <path to TDLib sources>
mkdir native-build
cd native-build
cmake -DTD_GENERATE_SOURCE_FILES=ON ..
cmake --build .

  4. Build TDLib with JNI bindings for Java

    master

    Before building the Java example, you must prebuild TDLib with JNI bindings and install it to a local subdirectory.

    Requirements:

    • JDK >= 1.6
    • CMake

    Platform Specifics:

    • Windows (MSVC): Use -A Win32 or -A x64 to match your target architecture. Use the vcpkg toolchain file by adding -DCMAKE_TOOLCHAIN_FILE=<VCPKG_DIR>/scripts/buildsystems/vcpkg.cmake.
    • JNI Errors: If CMake fails with "Could NOT find JNI ...", specify the JDK path using -DJAVA_HOME=/path/to/jdk.

    Build Steps:

    cd <path to TDLib sources>
mkdir jnibuild
cd jnibuild
cmake -DCMAKE_BUILD_TYPE=Release -DTD_ENABLE_JNI=ON -DCMAKE_INSTALL_PREFIX:PATH=../example/java/td ..
cmake --build . --target install

  5. Use TDLib in C projects

    master

    TDLib can be used in C through the JSON interface, supporting both static and dynamic linking.

    Alternatively, you can use the dedicated C client provided by TDLib, which is used by the telegram-cli project. The header file for this client is located at td/telegram/td_c_client.h.

  6. Install dependencies for building TDLib for Apple platforms

    master

    To build TDLib for iOS, watchOS, tvOS, visionOS, and macOS, you must install Xcode and several build dependencies via Homebrew.

    Requirements:

    • Xcode: Install the latest version via xcode-select --install or from the Apple Developer website. Note that Xcode >= 14.0 is required for watchOS support.
    • Homebrew Dependencies: Install gperf, cmake, and coreutils.

    Important Note: Ensure there are no spaces in your directory path, as the OpenSSL build scripts used in this process may fail if spaces are present.

    brew install gperf cmake coreutils

  7. Join or Remove Participants via the Blockchain

    master

    Group state changes (joining or removing participants) are managed by submitting new blocks to the blockchain.

    Joining a Call

    1. Request the latest blockchain block from the server.
    2. Create a new block containing the updated state, including yourself and a new shared key encrypted for all current participants.
    3. Submit the block to the server. The server validates that the block only adds the new user.

    Removing a Participant

    When a participant becomes inactive, an active participant must initiate a process similar to joining to remove them from the call state.

    Important Constraints

    • Self-Removal: Participants cannot remove themselves from a group, as this requires generating a new shared key for the remaining members.
    • Active Management: Active participants should remove inactive users, especially those blocking the emoji generation process.
    • Permissions: Currently, external_permissions in the blockchain state allows users to self-add to groups without explicit confirmation from existing members.

  9. Use TDLib in C++ projects

    master

    TDLib provides a C++11 interface for sending and receiving requests and can be statically linked.

    Refer to example/cpp/td_example.cpp for a complete example covering:

    • Authorization
    • Processing incoming messages
    • Getting a list of chats
    • Sending text messages.

  10. Build TDLib for Android using shell scripts

    master

    To build TDLib for Android on Linux, macOS, or Windows (with Bash), follow these steps in order.

    Prerequisites:

    • Bash shell
    • C++ compiler
    • JDK
    • PHP, perl, and gperf

    Standard Build Process:

    1. Check environment: ./check-environment.sh
    2. Download Android SDK: ./fetch-sdk.sh
    3. Build OpenSSL: ./build-openssl.sh
    4. Build TDLib: ./build-tdlib.sh

    Output Locations:

    • Built libraries: tdlib/libs
    • Java interface code: tdlib/java (if built)
    • Java documentation: tdlib/javadoc (if built)
    • Archives: tdlib/tdlib.zip and tdlib/tdlib-debug.zip contain all the above.
    ./check-environment.sh
./fetch-sdk.sh
./build-openssl.sh
./build-tdlib.sh

  11. Use TDLib in CMake C++ projects

    master

    You can integrate TDLib into C++ projects using either the JSON interface or the native C++ interface.

    Using Td::TdStatic (Native C++)

    If you are building TDLib as part of your project using add_subdirectory, link against Td::TdStatic:

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

    If TDLib is already installed system-wide, use find_package:

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

    Available C++ Libraries

    • Td::TdJson: Dynamic JSON interface with a simple C interface.
    • Td::TdJsonStatic: Static JSON interface with a simple C interface.
    • Td::TdStatic: Static library with the native C++ interface.
    add_subdirectory(td)
target_link_libraries(YourTarget PRIVATE Td::TdStatic)

  12. Use TDLib in Rust projects

    master

    TDLib can be used in Rust through the JSON interface.

    Recommended libraries:

    • rust-tdlib: Provides a convenient client with automatically generated and documented classes for all TDLib API methods and objects.
    • tdlib-rs: Another high-level client option.

    For low-level bindings, look at tdlib-sys or tdjson-rs.