tdlight/td/telegram/Client.h

290 lines
9.6 KiB
C
Raw Normal View History

//
2021-01-01 13:57:46 +01:00
// Copyright Aliaksei Levin (levlam@telegram.org), Arseny Smirnov (arseny30@gmail.com) 2014-2021
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
#pragma once
///\file
#include "td/telegram/td_api.h"
#include "td/telegram/td_api.hpp"
#include <cstdint>
#include <memory>
namespace td {
/**
* Native C++ interface for interaction with TDLib.
*
* The TDLib instance is created for the lifetime of the Client object.
* Requests to TDLib can be sent using the Client::send method from any thread.
* New updates and responses to requests can be received using the Client::receive method from any thread,
* this function must not be called simultaneously from two different threads. Also note that all updates and
* responses to requests should be applied in the same order as they were received, to ensure consistency.
* Given this information, it's advisable to call this function from a dedicated thread.
2020-11-18 21:42:26 +01:00
* Some service TDLib requests can be executed synchronously from any thread using the Client::execute method.
*
* General pattern of usage:
* \code
* std::shared_ptr<td::Client> client = std::make_shared<td::Client>();
* // somehow share the client with other threads, which will be able to send requests via client->send
*
* const double WAIT_TIMEOUT = 10.0; // seconds
* bool is_closed = false; // should be set to true, when updateAuthorizationState with
* // authorizationStateClosed is received
* while (!is_closed) {
* auto response = client->receive(WAIT_TIMEOUT);
* if (response.object == nullptr) {
* continue;
* }
*
* if (response.id == 0) {
* // process response.object as an incoming update of type td_api::Update
* } else {
* // process response.object as an answer to a sent request with id response.id
* }
* }
* \endcode
*/
class Client final {
public:
/**
* Creates a new TDLib client.
*/
Client();
/**
* A request to the TDLib.
*/
struct Request {
/**
* Request identifier.
* Responses to TDLib requests will have the same id as the corresponding request.
* Updates from TDLib will have id == 0, incoming requests are thus disallowed to have id == 0.
*/
std::uint64_t id;
/**
* TDLib API function representing a request to TDLib.
*/
td_api::object_ptr<td_api::Function> function;
};
/**
* Sends request to TDLib. May be called from any thread.
* \param[in] request Request to TDLib.
*/
void send(Request &&request);
/**
* A response to a request, or an incoming update from TDLib.
*/
struct Response {
/**
* TDLib request identifier, which corresponds to the response, or 0 for incoming updates from TDLib.
*/
std::uint64_t id;
/**
* TDLib API object representing a response to a TDLib request or an incoming update.
*/
td_api::object_ptr<td_api::Object> object;
};
/**
* Receives incoming updates and request responses from TDLib. May be called from any thread, but shouldn't be
* called simultaneously from two different threads.
* \param[in] timeout The maximum number of seconds allowed for this function to wait for new data.
* \return An incoming update or request response. The object returned in the response may be a nullptr
* if the timeout expires.
*/
Response receive(double timeout);
/**
* Synchronously executes TDLib requests. Only a few requests can be executed synchronously.
* May be called from any thread.
* \param[in] request Request to the TDLib.
* \return The request response.
*/
static Response execute(Request &&request);
/**
* Destroys the client and TDLib instance.
*/
~Client();
/**
* Move constructor.
*/
Client(Client &&other);
/**
* Move assignment operator.
*/
Client &operator=(Client &&other);
private:
class Impl;
std::unique_ptr<Impl> impl_;
};
/**
* The future native C++ interface for interaction with TDLib.
*
2020-11-18 21:42:26 +01:00
* A TDLib client instance can be created through the method ClientManager::create_client_id.
2020-11-19 23:32:58 +01:00
* Requests can be sent using the method ClientManager::send from any thread.
2020-11-18 21:42:26 +01:00
* New updates and responses to requests can be received using the method ClientManager::receive from any thread after
* the first request has been sent to the client instance. ClientManager::receive must not be called simultaneously from
* two different threads. Also note that all updates and responses to requests should be applied in the same order as
* they were received, to ensure consistency.
2020-11-18 21:42:26 +01:00
* Some TDLib requests can be executed synchronously from any thread using the method ClientManager::execute.
*
* General pattern of usage:
* \code
* td::ClientManager manager;
* auto client_id = manager.create_client_id();
* // somehow share the manager and the client_id with other threads,
* // which will be able to send requests via manager.send(client_id, ...)
*
* // send some dummy requests to the new instance to activate it
* manager.send(client_id, ...);
*
* const double WAIT_TIMEOUT = 10.0; // seconds
* while (true) {
* auto response = manager.receive(WAIT_TIMEOUT);
* if (response.object == nullptr) {
* continue;
* }
*
2020-11-18 21:42:26 +01:00
* if (response.request_id == 0) {
* // process response.object as an incoming update of the type td_api::Update for the client response.client_id
* } else {
* // process response.object as an answer to a request response.request_id for the client response.client_id
* }
* }
* \endcode
*/
class ClientManager final {
public:
/**
* Creates a new TDLib client manager.
*/
ClientManager();
/**
* Opaque TDLib client instance identifier.
*/
using ClientId = std::int32_t;
/**
* Request identifier.
* Responses to TDLib requests will have the same request id as the corresponding request.
2020-11-18 21:42:26 +01:00
* Updates from TDLib will have the request_id == 0, incoming requests are thus not allowed to have request_id == 0.
*/
using RequestId = std::uint64_t;
/**
* Returns an opaque identifier of a new TDLib instance.
* The TDLib instance will not send updates until the first request is sent to it.
2020-11-18 21:42:26 +01:00
* \return Opaque identifier of a new TDLib instance.
*/
ClientId create_client_id();
/**
* Sends request to TDLib. May be called from any thread.
* \param[in] client_id TDLib client instance identifier.
* \param[in] request_id Request identifier. Must be non-zero.
* \param[in] request Request to TDLib.
*/
void send(ClientId client_id, RequestId request_id, td_api::object_ptr<td_api::Function> &&request);
/**
* A response to a request, or an incoming update from TDLib.
*/
struct Response {
/**
2020-11-18 21:42:26 +01:00
* TDLib client instance identifier, for which the response was received.
*/
ClientId client_id;
/**
* Request identifier, to which the response corresponds, or 0 for incoming updates from TDLib.
*/
RequestId request_id;
/**
* TDLib API object representing a response to a TDLib request or an incoming update.
*/
td_api::object_ptr<td_api::Object> object;
};
/**
2020-11-18 21:42:26 +01:00
* Receives incoming updates and responses to requests from TDLib. May be called from any thread, but must not be
* called simultaneously from two different threads.
* \param[in] timeout The maximum number of seconds allowed for this function to wait for new data.
2020-11-18 21:42:26 +01:00
* \return An incoming update or response to a request. The object returned in the response may be a nullptr
* if the timeout expires.
*/
Response receive(double timeout);
/**
2020-11-18 21:42:26 +01:00
* Synchronously executes a TDLib request.
* A request can be executed synchronously, only if it is documented with "Can be called synchronously".
* \param[in] request Request to the TDLib.
* \return The request response.
*/
static td_api::object_ptr<td_api::Object> execute(td_api::object_ptr<td_api::Function> &&request);
/**
* A type of callback function that will be called when a message is added to the internal TDLib log.
*
* \param verbosity_level Log verbosity level with which the message was added (-1 - 1024).
* If 0, then TDLib will crash as soon as the callback returns.
* None of the TDLib methods can be called from the callback.
* \param message Null-terminated string with the message added to the log.
*/
using LogMessageCallbackPtr = void (*)(int verbosity_level, const char *message);
/**
* Sets the callback that will be called when a message is added to the internal TDLib log.
* None of the TDLib methods can be called from the callback.
* By default the callback is not set.
*
* \param[in] max_verbosity_level Maximum verbosity level of messages for which the callback will be called.
* \param[in] callback Callback that will be called when a message is added to the internal TDLib log.
* Pass nullptr to remove the callback.
*/
static void set_log_message_callback(int max_verbosity_level, LogMessageCallbackPtr callback);
/**
2020-11-18 21:42:26 +01:00
* Destroys the client manager and all TDLib client instances managed by it.
*/
~ClientManager();
/**
* Move constructor.
*/
ClientManager(ClientManager &&other);
/**
* Move assignment operator.
*/
ClientManager &operator=(ClientManager &&other);
/**
* Returns a pointer to a singleton ClientManager instance.
* \return A unique singleton ClientManager instance.
*/
static ClientManager *get_manager_singleton();
private:
friend class Client;
class Impl;
std::unique_ptr<Impl> impl_;
};
} // namespace td