tdweb: prettify documentation.

GitOrigin-RevId: f61800e92f2df4269d28921592b3ec4bd6e36579
This commit is contained in:
levlam 2019-04-29 20:06:18 +03:00
parent b49e312389
commit ec849f86b2
4 changed files with 30 additions and 30 deletions

View File

@ -70,7 +70,7 @@ cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . cmake --build .
``` ```
To build `TDLib` on low memory devices you can use [SplitSource.php](https://github.com/tdlib/td/blob/master/SplitSource.php) To build `TDLib` on low memory devices you can run [SplitSource.php](https://github.com/tdlib/td/blob/master/SplitSource.php) script
before compiling main `TDLib` source code and compile only needed targets: before compiling main `TDLib` source code and compile only needed targets:
``` ```
mkdir build mkdir build
@ -85,7 +85,7 @@ cmake --build . --target tdjson_static
cd .. cd ..
php SplitSource.php --undo php SplitSource.php --undo
``` ```
In our tests clang 6.0 with libc++ required less than 500 MB of RAM per file and GCC 6.3 used less than 1 GB of RAM per file. In our tests clang 6.0 with libc++ required less than 500 MB of RAM per file and GCC 4.9/6.3 used less than 1 GB of RAM per file.
<a name="installing-dependencies"></a> <a name="installing-dependencies"></a>
### Installing dependencies ### Installing dependencies

View File

@ -1,15 +1,15 @@
# TDLib Web example # TDLib Web example
This is an example of building `TDLib` for browsers using [Emscripten](https://github.com/kripken/emscripten). This is an example of building `TDLib` for browsers using [Emscripten](https://github.com/kripken/emscripten).
These scripts build `TDLib` and creates an [NPM](https://www.npmjs.com/) package [tdweb](https://www.npmjs.com/package/@arseny30/tdweb). These scripts build `TDLib` and create an [NPM](https://www.npmjs.com/) package [tdweb](https://www.npmjs.com/package/@arseny30/tdweb).
You need Unix shell with `sed`, `tar` and `wget` utilities to run provided scripts. You need a Unix shell with `sed`, `tar` and `wget` utilities to run the provided scripts.
## Building tdweb NPM package ## Building tdweb NPM package
* Install latest [emsdk](https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html). Do not use system-provided `emscripten` package, because it contains too old version. * Install the latest [emsdk](https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html). Do not use the system-provided `emscripten` package, because it contains a version that is too old.
* Install all `TDLib` build dependencies as described in [Building](https://github.com/tdlib/td#building). * Install all `TDLib` build dependencies as described in [Building](https://github.com/tdlib/td#building).
* Run `source ./emsdk_env.sh` from `emsdk` directory to set up correct build environment. * Run `source ./emsdk_env.sh` from `emsdk` directory to set up the correct build environment.
* On `macOS` install `coreutils` [Homebrew](https://brew.sh) package and replace `realpath` usages in scripts with `grealpath`: * On `macOS`, install the `coreutils` [Homebrew](https://brew.sh) package and replace `realpath` in scripts with `grealpath`:
``` ```
brew install coreutils brew install coreutils
sed -i.bak 's/[(]realpath/(grealpath/g' build-tdlib.sh sed -i.bak 's/[(]realpath/(grealpath/g' build-tdlib.sh
@ -22,8 +22,8 @@ cd <path to TDLib sources>/example/web
./copy-tdlib.sh ./copy-tdlib.sh
./build-tdweb.sh ./build-tdweb.sh
``` ```
* The built package is now located in `tdweb` directory. * The built package is now located in the `tdweb` directory.
## Using tdweb NPM package ## Using tdweb NPM package
See [tdweb](https://www.npmjs.com/package/@arseny30/tdweb) or [README.md](https://github.com/tdlib/td/tree/master/example/web/tdweb/README.md) for the package documentation. See [tdweb](https://www.npmjs.com/package/@arseny30/tdweb) or [README.md](https://github.com/tdlib/td/tree/master/example/web/tdweb/README.md) for package documentation.

View File

@ -1,19 +1,19 @@
## tdweb - TDLib in a browser ## tdweb - TDLib in a browser
[TDLib](https://github.com/tdlib/td) is a library for building Telegram clients. This is a convenient wrapper for the TDLib in a browser which controls TDLib instance creation, [TDLib](https://github.com/tdlib/td) is a library for building Telegram clients. tdweb is a convenient wrapper for TDLib in a browser which controls TDLib instance creation,
handles interaction with the TDLib and manages a filesystem for persistent TDLib data. handles interaction with TDLib and manages a filesystem for persistent TDLib data.
For interaction with the TDLib you need to create an instance of a class `TdClient`, providing a handler for incoming updates and other options if needed. For interaction with TDLib you need to create an instance of the class `TdClient`, providing a handler for incoming updates and other options if needed.
After that you can send queries to the TDLib instance using the method `TdClient.send` which returns a Promise object representing the result of the query. Once this is done, you can send queries to the TDLib instance using the method `TdClient.send` which returns a Promise object representing the result of the query.
See a [Getting Started](https://core.telegram.org/tdlib/getting-started) for a description of basic TDLib concepts and a short introduction to TDLib usage. See [Getting Started](https://core.telegram.org/tdlib/getting-started) for a description of basic TDLib concepts and a short introduction to TDLib usage.
See the [td_api.tl](https://github.com/tdlib/td/blob/master/td/generate/scheme/td_api.tl) scheme or See the [td_api.tl](https://github.com/tdlib/td/blob/master/td/generate/scheme/td_api.tl) scheme or
the automatically generated [HTML documentation](https://core.telegram.org/tdlib/docs/td__api_8h.html) for a list of all available the automatically generated [HTML documentation](https://core.telegram.org/tdlib/docs/td__api_8h.html) for a list of all available
TDLib [methods](https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_function.html) and [classes](https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_object.html). TDLib [methods](https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_function.html) and [classes](https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_object.html).
The JSON representation of TDLib API objects is straightforward: all API objects are represented as JSON objects with the same keys as the API object field names in the The JSON representation of TDLib API objects is straightforward: all API objects are represented as JSON objects with the same keys as the API object field names in the
[td_api.tl](https://github.com/tdlib/td/blob/master/td/generate/scheme/td_api.tl) scheme. Note that in the automatically generated Ñ++ documentation all fields has additional terminating underscore [td_api.tl](https://github.com/tdlib/td/blob/master/td/generate/scheme/td_api.tl) scheme. Note that in the automatically generated Ñ++ documentation all fields have an additional terminating underscore
which shouldn't be used in the JSON interface. The object type name is stored in the special field '@type' which is optional in places where a type is uniquely determined by the context. which shouldn't be used in the JSON interface. The object type name is stored in the special field '@type' which is optional in places where type is uniquely determined by the context.
Fields of Bool type are stored as Boolean, fields of int32, int53 and double types are stored as Number, fields of int64 and string types are stored as String, Fields of Bool type are stored as Boolean, fields of int32, int53 and double types are stored as Number, fields of int64 and string types are stored as String,
fields of bytes type are base64 encoded and then stored as String, fields of vector type are stored as Array. fields of bytes type are base64 encoded and then stored as String, fields of vector type are stored as Array.
You can also add a field '@extra' to any query to TDLib and the response will contain field '@extra' with exactly the same value. You can also add the field '@extra' to any query to TDLib and the response will contain the field '@extra' with exactly the same value.

View File

@ -11,18 +11,18 @@ const sleep = ms => new Promise(res => setTimeout(res, ms));
* *
* TDLib can be compiled to WebAssembly or asm.js using Emscripten compiler and used in a browser from JavaScript. * TDLib can be compiled to WebAssembly or asm.js using Emscripten compiler and used in a browser from JavaScript.
* This is a convenient wrapper for TDLib in a browser which controls TDLib instance creation, handles interaction * This is a convenient wrapper for TDLib in a browser which controls TDLib instance creation, handles interaction
* with the TDLib and manages a filesystem for persistent TDLib data. * with TDLib and manages a filesystem for persistent TDLib data.
* TDLib instance is created in a Web Worker to run it in a separate thread. * TDLib instance is created in a Web Worker to run it in a separate thread.
* TdClient just sends queries to the Web Worker and receive updates and results from it. * TdClient just sends queries to the Web Worker and receives updates and results from it.
* <br> * <br>
* <br> * <br>
* Differences from TDLib JSON API:<br> * Differences from the TDLib JSON API:<br>
* 1. Added the update <code>updateFatalError error:string = Update;</code> which is sent whenever a TDLib fatal error is encountered.<br> * 1. Added the update <code>updateFatalError error:string = Update;</code> which is sent whenever TDLib encounters a fatal error.<br>
* 2. Added the method <code>setJsLogVerbosityLevel new_verbosity_level:string = Ok;</code>, which allows to change the verbosity level of tdweb logging.<br> * 2. Added the method <code>setJsLogVerbosityLevel new_verbosity_level:string = Ok;</code>, which allows to change the verbosity level of tdweb logging.<br>
* 3. Added the possibility to use blobs as input files via constructor <code>inputFileBlob data:<JavaScript blob> = InputFile;</code>.<br> * 3. Added the possibility to use blobs as input files via the constructor <code>inputFileBlob data:<JavaScript blob> = InputFile;</code>.<br>
* 4. The class <code>filePart</code> contains data as a JavaScript blob instead of a base64-encoded string.<br> * 4. The class <code>filePart</code> contains data as a JavaScript blob instead of a base64-encoded string.<br>
* 5. Methods <code>getStorageStatistics</code>, <code>getStorageStatisticsFast</code>, <code>optimizeStorage</code>, <code>addProxy</code> are not supported.<br> * 5. The methods <code>getStorageStatistics</code>, <code>getStorageStatisticsFast</code>, <code>optimizeStorage</code>, <code>addProxy</code> are not supported.<br>
* 6. Added the field <code>idb_key</code> to <code>file</code> object, which contains IndexedDB key in which the file content is stored.<br> * 6. Added the field <code>idb_key</code> to <code>file</code> object, which contains the IndexedDB key in which the file content is stored.<br>
* This field is non-empty only for fully downloaded files. IndexedDB database name is chosen during TdClient creation via options.instanceName parameter.<br> * This field is non-empty only for fully downloaded files. IndexedDB database name is chosen during TdClient creation via options.instanceName parameter.<br>
* <br> * <br>
*/ */
@ -34,13 +34,13 @@ class TdClient {
/** /**
* Create TdClient. * Create TdClient.
* @param {Object} options - The options for TDLib instance creation. * @param {Object} options - Options for TDLib instance creation.
* @param {TdClient~updateCallback} options.onUpdate - The callback for all incoming updates. * @param {TdClient~updateCallback} options.onUpdate - Callback for all incoming updates.
* @param {string} [options.instanceName=tdlib] - The name of the TDLib instance. Currently only one instance of TdClient with a given name is allowed. All but one created instances with a given name will be automatically closed. Usually, the newest non-background instance is kept alive. Files will be stored in IndexedDb table with the same name. * @param {string} [options.instanceName=tdlib] - Name of the TDLib instance. Currently only one instance of TdClient with a given name is allowed. All but one instances with the same name will be automatically closed. Usually, the newest non-background instance is kept alive. Files will be stored in an IndexedDb table with the same name.
* @param {boolean} [options.isBackground=false] - Pass true, if the instance is opened from the background. * @param {boolean} [options.isBackground=false] - Pass true, if the instance is opened from the background.
* @param {string} [options.jsLogVerbosityLevel=info] - The initial verbosity level of the JavaScript part of the code (one of 'error', 'warning', 'info', 'log', 'debug'). * @param {string} [options.jsLogVerbosityLevel=info] - The initial verbosity level of the JavaScript part of the code (one of 'error', 'warning', 'info', 'log', 'debug').
* @param {number} [options.logVerbosityLevel=2] - The initial verbosity level for TDLib internal logging (0-1023). * @param {number} [options.logVerbosityLevel=2] - The initial verbosity level for the TDLib internal logging (0-1023).
* @param {boolean} [options.useDatabase=true] - Pass false to use TDLib without database and secret chats. It will significantly improve load time, but some functionality will be unavailable. * @param {boolean} [options.useDatabase=true] - Pass false to use TDLib without database and secret chats. It will significantly improve loading time, but some functionality will be unavailable.
* @param {boolean} [options.readOnly=false] - For debug only. Pass true to open TDLib database in read-only mode * @param {boolean} [options.readOnly=false] - For debug only. Pass true to open TDLib database in read-only mode
* @param {string} [options.mode=auto] - For debug only. The type of the TDLib build to use. 'asmjs' for asm.js and 'wasm' for WebAssembly. If mode == 'auto' WebAbassembly will be used if supported by browser, asm.js otherwise. * @param {string} [options.mode=auto] - For debug only. The type of the TDLib build to use. 'asmjs' for asm.js and 'wasm' for WebAssembly. If mode == 'auto' WebAbassembly will be used if supported by browser, asm.js otherwise.
*/ */
@ -66,7 +66,7 @@ class TdClient {
/** /**
* Send a query to TDLib. * Send a query to TDLib.
* *
* If the query contains an '@extra' field, the same field will be added into the result. * If the query contains the field '@extra', the same field will be added into the result.
* *
* @param {Object} query - The query for TDLib. See the [td_api.tl]{@link https://github.com/tdlib/td/blob/master/td/generate/scheme/td_api.tl} scheme or * @param {Object} query - The query for TDLib. See the [td_api.tl]{@link https://github.com/tdlib/td/blob/master/td/generate/scheme/td_api.tl} scheme or
* the automatically generated [HTML documentation]{@link https://core.telegram.org/tdlib/docs/td__api_8h.html} * the automatically generated [HTML documentation]{@link https://core.telegram.org/tdlib/docs/td__api_8h.html}