TD Java Interface

TD (Telegram Database) предоставляет удобный доступ к API мессенджера Telegram, полностью беря на себя шифрование, сетевое взаимодействие и локальное хранение данных. Взаимодействие с TD осуществляется асинхронным образом. Клиент получает обновления данных через установленный им обработчик и может как-либо на них реагировать. При необходимости получить конкретные данные (например, сообщения из диалога) клиент отправляет соответствующий запрос в TD, передавая вместе с запросом обработчик, который будет вызван, когда данные будут доступны.

TD предоставляет интерфейс для работы с базой на языке C++, описываемый TL-схемой, и обёртки на некоторых других языках программирования для этого интерфейса. Поэтому для работы с TD необходимо базовое понимание системы типов TL. Для клиентов на Java также доступна документаций в виде javadoc.

Пример интерфейса

Здесь и далее будет описан интерфейс TD для Java. Так как TD находится в стадии разработки, то интерфейс общения с базой может неоднократно измениться в будущем. На данный момент интерфейс для клиентов на Java выглядит следующим образом:

package org.drinkless.td.libcore.telegram:

public class TdApi {
  public static abstract class TLObject {
    public abstract int getConstructor();
  }

  public static abstract class TLFunction extends TLObject {
    public abstract int getConstructor();
  }

  public static class Error extends TLObject {
    public int code;
    public String text;

    ...
  }

  ...
}

public class Client implements Runnable {
  public interface ResultHandler {
    void onResult(TdApi.TLObject object);
  }

  public void send(TdApi.TLFunction function, ResultHandler handler);
}

public class TG {
    /**
     * Sets handler which will be invoked for every incoming update from TDLib of type TdApi.Update.
     * Must be called before getClientInstance().
     *
     * @param updatesHandler Handler to be invoked on updates.
     */
    public static void setUpdatesHandler(Client.ResultHandler updatesHandler);

    /**
     * Sets directory for storing persistent data of TDLib. Defaults to the current working directory.
     * Must be called before getClientInstance().
     *
     * @param dir Directory to store persistent data.
     */
    public static void setDir(String dir);

    /**
     * Sets directory for storing files of TDLib. Defaults to directory set via {@link #setDir(String)}
     * Must be called before getClientInstance().
     *
     * @param dir Directory to store files.
     */
    public static void setFilesDir(String dir);

    /**
     * Enables/disables logging to a file in addition to logging to Android Log.
     * By default logging to the file is disabled.
     * Must be called before getClientInstance().
     *
     * @param is_enabled Directory to store files.
     */
    public static void setFileLogEnabled(boolean is_enabled);

    /**
     * Enables/disables logging to a file in addition to logging to Android Log.
     * By default logging to the file is disabled.
     * Must be called before getClientInstance().
     *
     * @param use_test_dc Directory to store files.
     */
    public static void setUseTestDc(boolean use_test_dc);

    /**
     * This function stops and destroys the Client.
     * No queries are possible after this call, but completely new instance
     * of a Client with different settings can be obtained through getClientInstance()
     */
    public static void stopClient();

    /**
     * Changes TDLib log verbosity.
     *
     * @param newLogVerbosity New value of log verbosity. Must be positive.
     *                        Value 0 corresponds to android.util.Log.ASSERT,
     *                        value 1 corresponds to android.util.Log.ERROR,
     *                        value 2 corresponds to android.util.Log.WARNING,
     *                        value 3 corresponds to android.util.Log.INFO,
     *                        value 4 corresponds to android.util.Log.DEBUG,
     *                        value 5 corresponds to android.util.Log.VERBOSE,
     *                        value greater than 5 can be used to enable even more logging.
     *                        Default value of the log verbosity is 5.
     * @throws IllegalArgumentException if newLogVerbosity is negative.
     */
    public static void setLogVerbosity(int newLogVerbosity);

    /**
     * This function returns singleton object of class Client which can be used for querying TDLib.
     * setUpdatesHandler(), setDir(), setFilesDir() and setFileLogEnabled() must be called before this function.
     */
    public static Client getClientInstance();
}

Класс TdApi представляет собой автоматически сгенерированный по TL-схеме с описанием API класс, в котором описаны все необходимые для работы с TD типы и предоставляемые базой функции.

Класс TdApi.TLObject является абстрактным базовым классом для всех остальных классов из API TD.

Класс TdApi.TLFunction является абстрактным базовым классом для всех методов, предоставляемых API TD.

Все остальные вложенные классы класса TdApi соответствуют типам и методам из TL-схемы, описывающей API. Названия конкретных классов, соответствующих конструкторам в TL, начинаются с маленькой буквы, названия абстрактных классов, соответствующих TL-типам, — с большой. Подробнее о сгенерированных по TL-схеме классах смотри в статье Генерация Java-классов по TL-схеме.

Класс TdApi.error служит для обозначения ошибки, которая может прийти в ответ на любой запрос. Он содержит поля public int code и public String text с кодом ошибки и её текстовым описанием, соответственно. Их можно использовать для дебага, но полагаться на конкретный код ошибки или текстовое описание нельзя.

Класс Client — основной класс, через который происходит общение с TD. Для отправки запросов базе используется его функция Client::send, которой передаётся сам запрос (объект, реализующий интерфейс TDAPI.TLFunction) и обработчик, которому будет передан результат выполнения запроса, (объект, реализующий интерфейс Client.ResultHandler).

Интерфейс Client.ResultHandler предназначен для обработки результатов запросов. Когда результат будет готов, будет вызван метод onResult обработчика. В случае неудачного выполнения запроса вместо результата в метод onResult будет передан объект типа TdApi.Error.

Класс TG является менеджером для объекта класса Client. Все его методы статические. Метод setUpdatesHandler позволяет установить обработчик событий, который будет вызываться для всех событий, приходящий по инициативе TD (например, входящие сообщения). Метод setDir устанавливает директорию для хранения персистентных данных. Метод getClientInstance позволяет получить singleton-объект класса Client для взаимодействия с базой. Методы setDir и setUpdatesHandler должны быть вызваны до метода getClientInstance. Метод stopClient позволяет завершить работу с TD.

Описание доступных на данный момент типов и методов TD API можно посмотреть на странице TD Java API.

Для корректной работы приложения, использующего библиотеку TDLib, требуется разрешение android.permission.INTERNET. Если в setDirпередаётся директория на SD-карте, то дополнительно нужно разрешение android.permission.WRITE_EXTERNAL_STORAGE.