ClientManager Class Reference

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:

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

  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::Object >	execute (td_api::object_ptr< td_api::Function > &&request)
static void	set_log_message_callback (int max_verbosity_level, LogMessageCallbackPtr callback)
static ClientManager *	get_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
ClientManager &	operator= (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_level	Log 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.
message	Null-terminated UTF-8-encoded string with the message added to the log.

Constructor & Destructor Documentation

ClientManager() [1/2]

ClientManager

(

)

Creates a new TDLib client manager.

~ClientManager()

~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_id	TDLib client instance identifier.
[in]	request_id	Request identifier. Must be non-zero.
[in]	request	Request 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]

timeout

The 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]

request

Request 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_level	The maximum verbosity level of messages for which the callback will be called.
[in]	callback	Callback 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:

• td/telegram/Client.h