Describe the new JSON interface first.
This commit is contained in:
levlam
parent
4f2689d44a
commit
5280790347
@ -21,85 +21,6 @@
|
||||
* The main TDLib interface is asynchronous. To match requests with a corresponding response a field "@extra" can
|
||||
* be added to the request object. The corresponding response will have an "@extra" field with exactly the same value.
|
||||
*
|
||||
* A TDLib client instance can be created through td_json_client_create.
|
||||
* Requests then can be sent using td_json_client_send from any thread.
|
||||
* New updates and request responses can be received through td_json_client_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.
|
||||
* 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 td_json_client_execute.
|
||||
* The TDLib client instance can be destroyed via td_json_client_destroy.
|
||||
*
|
||||
* General pattern of usage:
|
||||
* \code
|
||||
* void *client = td_json_client_create();
|
||||
* // somehow share the client with other threads, which will be able to send requests via td_json_client_send
|
||||
*
|
||||
* const double WAIT_TIMEOUT = 10.0; // seconds
|
||||
* int is_closed = 0; // should be set to 1, when updateAuthorizationState with authorizationStateClosed is received
|
||||
* while (!is_closed) {
|
||||
* const char *result = td_json_client_receive(client, 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
|
||||
* }
|
||||
* }
|
||||
* td_json_client_destroy(client);
|
||||
* \endcode
|
||||
*/
|
||||
|
||||
#include "td/telegram/tdjson_export.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Creates a new instance of TDLib.
|
||||
* \return Pointer to the created instance of TDLib.
|
||||
*/
|
||||
TDJSON_EXPORT void *td_json_client_create();
|
||||
|
||||
/**
|
||||
* Sends request to the TDLib client. May be called from any thread.
|
||||
* \param[in] client The client.
|
||||
* \param[in] request JSON-serialized null-terminated request to TDLib.
|
||||
*/
|
||||
TDJSON_EXPORT void td_json_client_send(void *client, const char *request);
|
||||
|
||||
/**
|
||||
* Receives incoming updates and request responses from the TDLib client. May be called from any thread, but
|
||||
* must not be called simultaneously from two different threads.
|
||||
* Returned pointer will be deallocated by TDLib during next call to td_json_client_receive or td_json_client_execute
|
||||
* in the same thread, so it can't be used after that.
|
||||
* \param[in] client The client.
|
||||
* \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_json_client_receive(void *client, 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_json_client_receive or td_json_client_execute
|
||||
* in the same thread, so it can't be used after that.
|
||||
* \param[in] client The client. Currently ignored for all requests, so NULL can be passed.
|
||||
* \param[in] request JSON-serialized null-terminated request to TDLib.
|
||||
* \return JSON-serialized null-terminated request response.
|
||||
*/
|
||||
TDJSON_EXPORT const char *td_json_client_execute(void *client, const char *request);
|
||||
|
||||
/**
|
||||
* Destroys the TDLib client instance. After this is called the client instance must not be used anymore.
|
||||
* \param[in] client The client.
|
||||
*/
|
||||
TDJSON_EXPORT void td_json_client_destroy(void *client);
|
||||
|
||||
/**
|
||||
* \file
|
||||
* Alternatively, you can use new TDLib JSON interface, which will replace the current JSON interface in TDLib 2.0.0.
|
||||
*
|
||||
* Objects and functions serialization to JSON is the same for both JSON interfaces.
|
||||
*
|
||||
* 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 the identifier of the client for which
|
||||
@ -129,6 +50,12 @@ TDJSON_EXPORT void td_json_client_destroy(void *client);
|
||||
* \endcode
|
||||
*/
|
||||
|
||||
#include "td/telegram/tdjson_export.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Returns an opaque identifier of a new TDLib instance.
|
||||
* The TDLib instance will not send updates until the first request is sent to it.
|
||||
@ -181,6 +108,79 @@ typedef void (*td_log_message_callback_ptr)(int verbosity_level, const char *mes
|
||||
*/
|
||||
TDJSON_EXPORT void td_set_log_message_callback(int max_verbosity_level, td_log_message_callback_ptr callback);
|
||||
|
||||
/**
|
||||
* \file
|
||||
* Alternatively, you can use old TDLib JSON interface, which will be removed at TDLib 2.0.0.
|
||||
*
|
||||
* Objects and functions serialization to JSON is the same for both JSON interfaces.
|
||||
*
|
||||
* A TDLib client instance can be created through td_json_client_create.
|
||||
* Requests then can be sent using td_json_client_send from any thread.
|
||||
* New updates and request responses can be received through td_json_client_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.
|
||||
* 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 td_json_client_execute.
|
||||
* The TDLib client instance can be destroyed via td_json_client_destroy.
|
||||
*
|
||||
* General pattern of usage:
|
||||
* \code
|
||||
* void *client = td_json_client_create();
|
||||
* // somehow share the client with other threads, which will be able to send requests via td_json_client_send
|
||||
*
|
||||
* const double WAIT_TIMEOUT = 10.0; // seconds
|
||||
* int is_closed = 0; // should be set to 1, when updateAuthorizationState with authorizationStateClosed is received
|
||||
* while (!is_closed) {
|
||||
* const char *result = td_json_client_receive(client, 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
|
||||
* }
|
||||
* }
|
||||
* td_json_client_destroy(client);
|
||||
* \endcode
|
||||
*/
|
||||
|
||||
/**
|
||||
* Creates a new instance of TDLib.
|
||||
* \return Pointer to the created instance of TDLib.
|
||||
*/
|
||||
TDJSON_EXPORT void *td_json_client_create();
|
||||
|
||||
/**
|
||||
* Sends request to the TDLib client. May be called from any thread.
|
||||
* \param[in] client The client.
|
||||
* \param[in] request JSON-serialized null-terminated request to TDLib.
|
||||
*/
|
||||
TDJSON_EXPORT void td_json_client_send(void *client, const char *request);
|
||||
|
||||
/**
|
||||
* Receives incoming updates and request responses from the TDLib client. May be called from any thread, but
|
||||
* must not be called simultaneously from two different threads.
|
||||
* Returned pointer will be deallocated by TDLib during next call to td_json_client_receive or td_json_client_execute
|
||||
* in the same thread, so it can't be used after that.
|
||||
* \param[in] client The client.
|
||||
* \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_json_client_receive(void *client, 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_json_client_receive or td_json_client_execute
|
||||
* in the same thread, so it can't be used after that.
|
||||
* \param[in] client The client. Currently ignored for all requests, so NULL can be passed.
|
||||
* \param[in] request JSON-serialized null-terminated request to TDLib.
|
||||
* \return JSON-serialized null-terminated request response.
|
||||
*/
|
||||
TDJSON_EXPORT const char *td_json_client_execute(void *client, const char *request);
|
||||
|
||||
/**
|
||||
* Destroys the TDLib client instance. After this is called the client instance must not be used anymore.
|
||||
* \param[in] client The client.
|
||||
*/
|
||||
TDJSON_EXPORT void td_json_client_destroy(void *client);
|
||||
|
||||
#ifdef __cplusplus
|
||||
} // extern "C"
|
||||
#endif
|
||||
|
||||
Loading…
Reference in New Issue
Block a user