List of all members | Classes | Public Types | Public Class Methods | Public Instance Methods
ClientManager Class Referencefinal

Description

The native C++ interface for interaction with TDLib.

A TDLib client instance can be created through the method ClientManager::create_client_id. Requests can be sent using the method ClientManager::send from any thread. 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. Some TDLib requests can be executed synchronously from any thread using the method ClientManager::execute.

General pattern of usage:

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;
}
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
}
}

Classes

struct  Response
 

Public Types

using ClientId = std::int32_t
 
using RequestId = std::uint64_t
 
using LogMessageCallbackPtr = void(*)(int verbosity_level, const char *message)
 

Public Class Methods

static td_api::object_ptr< td_api::Objectexecute (td_api::object_ptr< td_api::Function > &&request)
 
static void set_log_message_callback (int max_verbosity_level, LogMessageCallbackPtr callback)
 
static ClientManagerget_manager_singleton ()
 

Public Instance Methods

 ClientManager ()
 
ClientId create_client_id ()
 
void send (ClientId client_id, RequestId request_id, td_api::object_ptr< td_api::Function > &&request)
 
Response receive (double timeout)
 
 ~ClientManager ()
 
 ClientManager (ClientManager &&other) noexcept
 
ClientManageroperator= (ClientManager &&other) noexcept
 

Member Typedef Documentation

◆ ClientId

using ClientId = std::int32_t

Opaque TDLib client instance identifier.

◆ RequestId

using RequestId = std::uint64_t

Request identifier. Responses to TDLib requests will have the same request id as the corresponding request. Updates from TDLib will have the request_id == 0, incoming requests are thus not allowed to have request_id == 0.

◆ LogMessageCallbackPtr

using LogMessageCallbackPtr = void (*)(int verbosity_level, const char *message)

A type of callback function that will be called when a message is added to the internal TDLib log.

Parameters
verbosity_levelLog verbosity level with which the message was added from -1 up to 1024. If 0, then TDLib will crash as soon as the callback returns. None of the TDLib methods can be called from the callback.
messageNull-terminated UTF-8-encoded string with the message added to the log.

Constructor & Destructor Documentation

◆ ClientManager() [1/2]

Creates a new TDLib client manager.

◆ ~ClientManager()

Destroys the client manager and all TDLib client instances managed by it.

◆ ClientManager() [2/2]

ClientManager ( ClientManager &&  other)
noexcept

Move constructor.

Method Documentation

◆ create_client_id()

ClientId create_client_id ( )

Returns an opaque identifier of a new TDLib instance. The TDLib instance will not send updates until the first request is sent to it.

Returns
Opaque identifier of a new TDLib instance.

◆ send()

void send ( ClientId  client_id,
RequestId  request_id,
td_api::object_ptr< td_api::Function > &&  request 
)

Sends request to TDLib. May be called from any thread.

Parameters
[in]client_idTDLib client instance identifier.
[in]request_idRequest identifier. Must be non-zero.
[in]requestRequest to TDLib.

◆ receive()

Response receive ( double  timeout)

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.

Parameters
[in]timeoutThe maximum number of seconds allowed for this function to wait for new data.
Returns
An incoming update or response to a request. The object returned in the response may be a nullptr if the timeout expires.

◆ execute()

static td_api::object_ptr<td_api::Object> execute ( td_api::object_ptr< td_api::Function > &&  request)
static

Synchronously executes a TDLib request. A request can be executed synchronously, only if it is documented with "Can be called synchronously".

Parameters
[in]requestRequest to the TDLib.
Returns
The request response.

◆ set_log_message_callback()

static void set_log_message_callback ( int  max_verbosity_level,
LogMessageCallbackPtr  callback 
)
static

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.

Parameters
[in]max_verbosity_levelThe maximum verbosity level of messages for which the callback will be called.
[in]callbackCallback that will be called when a message is added to the internal TDLib log. Pass nullptr to remove the callback.

◆ operator=()

ClientManager& operator= ( ClientManager &&  other)
noexcept

Move assignment operator.

◆ get_manager_singleton()

static ClientManager* get_manager_singleton ( )
static

Returns a pointer to a singleton ClientManager instance.

Returns
A unique singleton ClientManager instance.

The documentation for this class was generated from the following file: