tdlight-team/tdlight
tdlight-team/tdlight
1
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Improve new interface documentation.

Browse Source
This commit is contained in:
levlam 2020-11-18 23:42:26 +03:00
parent 15359488be
commit ebfe3f3d99
2 changed files with 32 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
td/telegram/Client.h
View File

@ -25,7 +25,7 @@ namespace td {
* 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.
* Some service TDLib requests can be executed synchronously from any thread by using the Client::execute method.
* Some service TDLib requests can be executed synchronously from any thread using the Client::execute method.
*
* General pattern of usage:
* \code
@ -134,13 +134,13 @@ class Client final {
/**
* The future native C++ interface for interaction with TDLib.
*
* The TDLib client instance is created using the ClientManager::create_client_id method, returning a client identifier.
* Requests to a TDLib client instance can be sent using the ClientManager::send method from any thread.
* New updates and responses to requests can be received using the ClientManager::receive method from any thread
* after a first request is sent to the client instance. ClientManager::receive must not be called simultaneously from
* A TDLib client instance can be created through the method ClientManager::create_client_id.
* Requests can then 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 by using the ClientManager::execute method.
* Some TDLib requests can be executed synchronously from any thread using the method ClientManager::execute.
*
* General pattern of usage:
* \code
@ -159,8 +159,8 @@ class Client final {
* continue;
* }
*
* if (response.id == 0) {
* // process response.object as an incoming update of type td_api::Update for the client response.client_id
* 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
* }
@ -182,14 +182,14 @@ class ClientManager final {
/**
* Request identifier.
* Responses to TDLib requests will have the same request id as the corresponding request.
* Updates from TDLib will have request id == 0, incoming requests are thus disallowed to have request id == 0.
* 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.
* \return Opaque indentifier of a new TDLib instance.
* \return Opaque identifier of a new TDLib instance.
*/
ClientId create_client_id();
@ -206,7 +206,7 @@ class ClientManager final {
*/
struct Response {
/**
* TDLib client instance identifier, for which the response is received.
* TDLib client instance identifier, for which the response was received.
*/
ClientId client_id;
@ -222,24 +222,24 @@ class ClientManager final {
};
/**
* Receives incoming updates and request responses from TDLib. May be called from any thread, but must not be
* 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.
* \return An incoming update or request response. The object returned in the response may be a nullptr
* \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);
/**
* Synchronously executes TDLib requests. Only a few requests can be executed synchronously.
* May be called from any thread.
* 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);
/**
* Destroys the client manager and all TDLib client instance managed by it.
* Destroys the client manager and all TDLib client instances managed by it.
*/
~ClientManager();

34
td/telegram/td_json_client.h
View File

@ -97,18 +97,18 @@ TDJSON_EXPORT void td_json_client_destroy(void *client);
/*
* New TDLib JSON interface.
*
* The main TDLib interface is asynchronous. To match requests with a corresponding response a field "@extra" can
* The main TDLib interface is asynchronous. To match requests with a corresponding response, the field "@extra" can
* be added to the request object. The corresponding response will have an "@extra" field with exactly the same value.
* Each returned object will have an "@client_id" field, containing and identifier of the client for which
* a response or an update is received.
* Each returned object will have an "@client_id" field, containing the identifier of the client for which
* a response or an update was received.
*
* A TDLib client instance can be created through td_create_client_id.
* Requests then can be sent using td_send from any thread and the received client identifier.
* New updates and request responses can be received through td_receive from any thread. This function
* must not be called simultaneously from two different threads. Also note that all updates and request responses
* must be applied in the order they were received to ensure consistency.
* Some TDLib requests can be executed synchronously from any thread by using td_execute.
* The TDLib client instances are destroyed automatically after they are closed.
* Requests can then be sent using td_send and the received client identifier.
* New updates and responses to requests can be received through td_receive from any thread after the first request
* has been sent to the client instance. This function must not be called simultaneously from two different threads.
* Also note that all updates and responses to requests must be applied in the order they were received for consistency.
* Some TDLib requests can be executed synchronously from any thread using td_execute.
* TDLib client instances are destroyed automatically after they are closed.
*
* General pattern of usage:
* \code
@ -119,7 +119,7 @@ TDJSON_EXPORT void td_json_client_destroy(void *client);
* while (true) {
* const char *result = td_receive(WAIT_TIMEOUT);
* if (result) {
* // parse the result as JSON object and process it as an incoming update or an answer to a previously sent request
* // parse the result as a JSON object and process it as an incoming update or the answer to a previously sent request
* }
* }
* \endcode
@ -128,31 +128,29 @@ TDJSON_EXPORT void td_json_client_destroy(void *client);
/**
* Returns an opaque identifier of a new TDLib instance.
* The TDLib instance will not send updates until the first request is sent to it.
* \return Opaque indentifier of a new TDLib instance.
* \return Opaque identifier of a new TDLib instance.
*/
TDJSON_EXPORT int td_create_client_id();
/**
* Sends request to the TDLib client. May be called from any thread.
* \param[in] client_id The TDLib client identifier.
* \param[in] client_id TDLib client identifier.
* \param[in] request JSON-serialized null-terminated request to TDLib.
*/
TDJSON_EXPORT void td_send(int client_id, const char *request);
/**
* Receives incoming updates and request responses. Must not be called simultaneously from two different threads.
* Returned pointer will be deallocated by TDLib during next call to td_receive or td_execute
* in the same thread, so it can't be used after that.
* The returned pointer can be used until the next call to td_receive or td_execute, after which it will be deallocated by TDLib.
* \param[in] timeout The maximum number of seconds allowed for this function to wait for new data.
* \return JSON-serialized null-terminated incoming update or request response. May be NULL if the timeout expires.
*/
TDJSON_EXPORT const char *td_receive(double timeout);
/**
* Synchronously executes TDLib request. May be called from any thread.
* Only a few requests can be executed synchronously.
* Returned pointer will be deallocated by TDLib during next call to td_receive or td_execute
* in the same thread, so it can't be used after that.
* Synchronously executes a TDLib request.
* A request can be executed synchronously, only if it is documented with "Can be called synchronously".
* The returned pointer can be used until the next call to td_receive or td_execute, after which it will be deallocated by TDLib.
* \param[in] request JSON-serialized null-terminated request to TDLib.
* \return JSON-serialized null-terminated request response.
*/