mirror of
https://github.com/MarshalX/telegram-crawler.git
synced 2024-12-28 23:38:26 +01:00
Update content of files
This commit is contained in:
GitHub Action
parent
26cfe12ee3
commit
8e98ce0623
2 changed files with 319 additions and 198 deletions
319
data/core.telegram.org/mtproto/TL-formal.html
Normal file
319
data/core.telegram.org/mtproto/TL-formal.html
Normal file
|
|
@ -0,0 +1,319 @@
|
|||
<!DOCTYPE html>
|
||||
<html class="">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>TL-formal</title>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta property="description" content="See also TL Language.
|
||||
For the syntax of declaring combinators, see in article Formal declaration of TL combinators.
|
||||
For…">
|
||||
<meta property="og:title" content="TL-formal">
|
||||
<meta property="og:image" content="">
|
||||
<meta property="og:description" content="See also TL Language.
|
||||
For the syntax of declaring combinators, see in article Formal declaration of TL combinators.
|
||||
For…">
|
||||
<link rel="shortcut icon" href="/favicon.ico?4" type="image/x-icon" />
|
||||
|
||||
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
|
||||
|
||||
<link href="/css/telegram.css?212" rel="stylesheet" media="screen">
|
||||
<style>
|
||||
</style>
|
||||
</head>
|
||||
<body class="preload">
|
||||
<div class="dev_page_wrap">
|
||||
<div class="dev_page_head navbar navbar-static-top navbar-tg">
|
||||
<div class="navbar-inner">
|
||||
<div class="container clearfix">
|
||||
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
|
||||
<ul class="nav navbar-nav">
|
||||
<li><a href="//telegram.org/">Home</a></li>
|
||||
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
|
||||
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
|
||||
<li class=""><a href="/api">API</a></li>
|
||||
<li class="active"><a href="/mtproto">Protocol</a></li>
|
||||
<li class=""><a href="/schema">Schema</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="container clearfix">
|
||||
<div class="dev_page">
|
||||
<div id="dev_page_content_wrap" class=" ">
|
||||
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/mtproto" >Mobile Protocol</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/mtproto/TL-formal" >TL-formal</a></li></ul></div>
|
||||
<h1 id="dev_page_title">TL-formal</h1>
|
||||
|
||||
<div id="dev_page_content"><p>See also <a href="TL">TL Language</a>.
|
||||
For the syntax of declaring combinators, see in article <a href="TL-combinators">Formal declaration of TL combinators</a>.
|
||||
For the syntax of patterns, see in article <a href="TL-patterns">Formal declaration of TL patterns</a>. </p>
|
||||
<h3><a class="anchor" href="#tokens" id="tokens" name="tokens"><i class="anchor-icon"></i></a>Tokens</h3>
|
||||
<p>Comments are the same as in C/C++. They are removed by a lexical parser (for example, being replaced by a single space). Whitespace separates tokens. Except for string constants, tokens cannot contain spaces. </p>
|
||||
<p>Character classes: </p>
|
||||
<div class="richcode">
|
||||
<p><em>lc-letter</em> ::= <code>a</code> | <code>b</code> | ... | <code>z</code><br>
|
||||
<em>uc-letter</em> ::= <code>A</code> | <code>B</code> | ... | <code>Z</code><br>
|
||||
<em>digit</em> ::= <code>0</code> | <code>1</code> | ... | <code>9</code><br>
|
||||
<em>hex-digit</em> ::= <em>digit</em> | <code>a</code> | <code>b</code> | <code>c</code> | <code>d</code> | <code>e</code> | <code>f</code><br>
|
||||
<em>underscore</em> ::= <code>_</code><br>
|
||||
<em>letter</em> ::= <em>lc-letter</em> | <em>uc-letter</em><br>
|
||||
<em>ident-char</em> ::= <em>letter</em> | <em>digit</em> | <em>underscore</em> </p>
|
||||
</div>
|
||||
<p>Simple identifiers and keywords: </p>
|
||||
<div class="richcode">
|
||||
<p><em>lc-ident</em> ::= <em>lc-letter</em> { <em>ident-char</em> }<br>
|
||||
<em>uc-ident</em> ::= <em>uc-letter</em> { <em>ident-char</em> }<br>
|
||||
<em>namespace-ident</em> ::= <em>lc-ident</em><br>
|
||||
<em>lc-ident-ns</em> ::= [ <em>namespace-ident</em> <code>.</code> ] <em>lc-ident</em><br>
|
||||
<em>uc-ident-ns</em> ::= [ <em>namespace-ident</em> <code>.</code> ] <em>uc-ident</em><br>
|
||||
<em>lc-ident-full</em> ::= <em>lc-ident-ns</em> [ <code>#</code> <em>hex-digit</em> *8 ] </p>
|
||||
</div>
|
||||
<p>Tokens:</p>
|
||||
<div class="richcode">
|
||||
<p><em>underscore</em> ::= <code>_</code><br>
|
||||
<em>colon</em> ::= <code>:</code><br>
|
||||
<em>semicolon</em> ::= <code>;</code><br>
|
||||
<em>open-par</em> ::= <code>(</code><br>
|
||||
<em>close-par</em> ::= <code>)</code><br>
|
||||
<em>open-bracket</em> ::= <code>[</code><br>
|
||||
<em>close-bracket</em> ::= <code>]</code><br>
|
||||
<em>open-brace</em> ::= <code>{</code><br>
|
||||
<em>close-brace</em> ::= <code>}</code><br>
|
||||
<em>triple-minus</em> ::= <code>---</code><br>
|
||||
<em>nat-const</em> ::= <em>digit</em> { <em>digit</em> }<br>
|
||||
<em>lc-ident-full</em><br>
|
||||
<em>lc-ident</em><br>
|
||||
<em>uc-ident-ns</em><br>
|
||||
<em>equals</em> ::= <code>=</code><br>
|
||||
<em>hash</em> ::= <code>#</code><br>
|
||||
<em>question-mark</em> ::= <code>?</code><br>
|
||||
<em>percent</em> ::= <code>%</code><br>
|
||||
<em>plus</em> ::= <code>+</code><br>
|
||||
<em>langle</em> ::= <code><</code><br>
|
||||
<em>rangle</em> ::= <code>></code><br>
|
||||
<em>comma</em> ::= <code>,</code><br>
|
||||
<em>dot</em> ::= <code>.</code><br>
|
||||
<em>asterisk</em> ::= <code>*</code><br>
|
||||
<em>excl-mark</em> ::= <code>!</code><br>
|
||||
<em>Final-kw</em> ::= <code>Final</code><br>
|
||||
<em>New-kw</em> ::= <code>New</code><br>
|
||||
<em>Empty-kw</em> ::= <code>Empty</code> </p>
|
||||
</div>
|
||||
<p><code>Final</code> is a reserved keyword, e.g. a special token. Words like <code>Type</code> are not keywords, rather they are identifiers with preset values. </p>
|
||||
<p>Tokens consisting of one or more constant symbols shall be hereafter denoted using terms in quotation marks (for example, <code>---</code> replaces <em>triple-minus</em>). </p>
|
||||
<h2><a class="anchor" href="#syntax" id="syntax" name="syntax"><i class="anchor-icon"></i></a>Syntax</h2>
|
||||
<h3><a class="anchor" href="#general-syntax-of-a-tl-program" id="general-syntax-of-a-tl-program" name="general-syntax-of-a-tl-program"><i class="anchor-icon"></i></a>General syntax of a TL program</h3>
|
||||
<p>Syntactically, a TL program consists of a stream of tokens (separated by spaces, which are ignored at this stage). General program structure: </p>
|
||||
<div class="richcode">
|
||||
<p><em>TL-program</em> ::= <em>constr-declarations</em> { <code>---</code> <code>functions</code> <code>---</code> <em>fun-declarations</em> | <code>---</code> <code>types</code> <code>---</code> <em>constr-declarations</em> } </p>
|
||||
</div>
|
||||
<p>Here the constructor- and function declarations are nearly identical in their syntax (they are both combinators): </p>
|
||||
<div class="richcode">
|
||||
<p><em>constr-declarations</em> ::= { <em>declaration</em> }<br>
|
||||
<em>fun-declarations</em> ::= { <em>declaration</em> } </p>
|
||||
</div>
|
||||
<p>There are various declarations: </p>
|
||||
<div class="richcode">
|
||||
<p><em>declaration</em> ::= <em>combinator-decl</em> | <em>partial-app-decl</em> | <em>final-decl</em> </p>
|
||||
</div>
|
||||
<p>Before explaining how declarations of combinators, partial applications, and type <code>finalization</code> are given, we will introduce additional syntactical categories: </p>
|
||||
<h3><a class="anchor" href="#syntactical-categories-and-constructions" id="syntactical-categories-and-constructions" name="syntactical-categories-and-constructions"><i class="anchor-icon"></i></a>Syntactical categories and constructions</h3>
|
||||
<p>The concept of an expression (<em>expr</em>) is important. There are type expressions (<em>type-expr</em>) and numeric expressions (<em>nat-expr</em>). However, they are defined the same way. Their correctness as type- or numeric expressions is checked when the type of the analyzed expression is checked. </p>
|
||||
<div class="richcode">
|
||||
<p><em>type-expr</em> ::= <em>expr</em><br>
|
||||
<em>nat-expr</em> ::= <em>expr</em><br>
|
||||
<em>expr</em> ::= { <em>subexpr</em> }<br>
|
||||
<em>subexpr</em> ::= <em>term</em> | <em>nat-const</em> <code>+</code> <em>subexpr</em> | <em>subexpr</em> <code>+</code> <em>nat-const</em><br>
|
||||
<em>term</em> ::= <code>(</code> <em>expr</em> <code>)</code> | <em>type-ident</em> | <em>var-ident</em> | <em>nat-const</em> | <code>%</code> <em>term</em> | <em>type-ident</em> <code><</code> <em>expr</em> { <code>,</code> <em>expr</em> } <code>></code><br>
|
||||
<em>type-ident</em> ::= <em>boxed-type-ident</em> | <em>lc-ident-ns</em> | <code>#</code><br>
|
||||
<em>boxed-type-ident</em> ::= <em>uc-ident-ns</em><br>
|
||||
<em>var-ident</em> ::= <em>lc-ident</em> | <em>uc-ident</em><br>
|
||||
<em>type-term</em> ::= <em>term</em><br>
|
||||
<em>nat-term</em> ::= <em>term</em> </p>
|
||||
</div>
|
||||
<p>Note that writing <code>E = E_1 E_2 ... E_n</code> in the expression for <em>expr</em> means applying the function <em>E_1</em> to the argument <em>E_2</em>, applying the result to <em>E_3</em>, etc. Specifically, <code>E_1 E_2 E_3 = (E_1 E_2) E_3</code>. A solitary <code>#</code> is included in <em>type-ident</em>, because it is actually the identifier for a built-in type (<code>#</code> alias <code>nat</code>). </p>
|
||||
<p>The expression <code>E<E_1,...,E_n></code> is syntactic sugar for <code>(E (E_1) ... (E_n))</code>, i.e. both expressions are transformed into the same internal representation. </p>
|
||||
<h3><a class="anchor" href="#combinator-declarations" id="combinator-declarations" name="combinator-declarations"><i class="anchor-icon"></i></a>Combinator declarations</h3>
|
||||
<div class="richcode">
|
||||
<p><em>combinator-decl</em> ::= <em>full-combinator-id</em> { <em>opt-args</em> } { <em>args</em> } <code>=</code> <em>result-type</em> <code>;</code><br>
|
||||
<em>full-combinator-id</em> ::= <em>lc-ident-full</em> | <code>_</code><br>
|
||||
<em>combinator-id</em> ::= <em>lc-ident-ns</em> | <code>_</code><br>
|
||||
<em>opt-args</em> ::= <code>{</code> <em>var-ident</em> { <em>var-ident </em>} : [<em>excl-mark</em>] <em>type-expr</em> <code>}</code><br>
|
||||
<em>args</em> ::= <em>var-ident-opt</em> <code>:</code> [ <em>conditional-def</em> ] [ <code>!</code> ] <em>type-term</em><br>
|
||||
<em>args</em> ::= [ <em>var-ident-opt</em> <code>:</code> ] [ <em>multiplicity</em> <code>*</code>] <code>[</code> { <em>args</em> } <code>]</code><br>
|
||||
<em>args</em> ::= <code>(</code> <em>var-ident-opt</em> { <em>var-ident-opt</em> } <code>:</code> [<code>!</code>] <em>type-term</em> <code>)</code><br>
|
||||
<em>args</em> ::= [ <code>!</code> ] <em>type-term</em><br>
|
||||
<em>multiplicity</em> ::= <em>nat-term</em><br>
|
||||
<em>var-ident-opt</em> ::= <em>var-ident</em> | <code>_</code><br>
|
||||
<em>conditional-def</em> ::= <em>var-ident</em> [ <code>.</code> <em>nat-const</em> ] <code>?</code><br>
|
||||
<em>result-type</em> ::= <em>boxed-type-ident</em> { <em>subexpr</em> }<br>
|
||||
<em>result-type</em> ::= <em>boxed-type-ident</em> <code><</code> <em>subexpr</em> { <code>,</code> <em>subexpr</em> } <code>></code> </p>
|
||||
</div>
|
||||
<p>See <a href="TL-combinators">Formal declaration of TL combinators</a> for a description of what exactly this means. Here we will only note that when declaring the type of a combinator’s next argument, only the names of previously arranged (more to the left) arguments of the same combinator may be used as variables, but when declaring the result type you can use all of its parameters (of type <code>Type</code> and <code>#</code>). </p>
|
||||
<p>Note that the names of combinators declared in this way may be used in TL itself only as the corresponding bare types. The only combinators that appear in declarations are built-in: <code>O : #</code> and <code>S : # -> #</code>. </p>
|
||||
<p>There are also “pseudo-declarations” that are allowed only to declare built-in types (such as <code>int ? = Int;</code>): </p>
|
||||
<div class="richcode">
|
||||
<p><em>builtin-combinator-decl</em> ::= <em>full-combinator-id</em> <code>?</code> <code>=</code> <em>boxed-type-ident</em> <code>;</code> </p>
|
||||
</div>
|
||||
<h3><a class="anchor" href="#partial-applications-patterns" id="partial-applications-patterns" name="partial-applications-patterns"><i class="anchor-icon"></i></a>Partial applications (patterns)</h3>
|
||||
<div class="richcode">
|
||||
<p><em>partial-app-decl</em> ::= <em>partial-type-app-decl</em> | <em>partial-comb-app-decl</em><br>
|
||||
<em>partial-type-app-decl</em> ::= <em>boxed-type-ident</em> <em>subexpr</em> { <em>subexpr</em> } <code>;</code> | <em>boxed-type-ident</em> <code><</code> <em>expr</em> { <code>,</code> <em>expr</em> } <code>></code> <code>;</code><br>
|
||||
<em>partial-comb-app-decl</em> ::= <em>combinator-id</em> <em>subexpr</em> { <em>subexpr</em> } <code>;</code> </p>
|
||||
</div>
|
||||
<p>See <a href="TL-patterns">Formal declaration of TL patterns</a>. </p>
|
||||
<h3><a class="anchor" href="#type-finalization" id="type-finalization" name="type-finalization"><i class="anchor-icon"></i></a>Type finalization</h3>
|
||||
<div class="richcode">
|
||||
<p><em>final-decl</em> ::= <code>New</code> <em>boxed-type-ident</em> <code>;</code> | <code>Final</code> <em>boxed-type-ident</em> <code>;</code> | <code>Empty</code> <em>boxed-type-ident</em> <code>;</code> </p>
|
||||
</div>
|
||||
<p>This type of declaration means that there must not be any constructor for the indicated type: before the declaration for <code>New</code> and after the declaration for <code>Final</code>. The keyword <code>Empty</code> enables both effects.</p>
|
||||
<h3><a class="anchor" href="#predefined-identifiers" id="predefined-identifiers" name="predefined-identifiers"><i class="anchor-icon"></i></a>Predefined identifiers</h3>
|
||||
<p>Nearly all predefined identifiers may be given using the following schema (usually located in <code>common.tl</code>):</p>
|
||||
<div class="richcode">
|
||||
<p>/////<br>
|
||||
//<br>
|
||||
// Common Types<br>
|
||||
//<br>
|
||||
///// </p>
|
||||
<p>// Built-in types<br>
|
||||
int ? = Int;<br>
|
||||
long ? = Long;<br>
|
||||
double ? = Double;<br>
|
||||
string ? = String; </p>
|
||||
<p>// Boolean emulation<br>
|
||||
boolFalse = Bool;<br>
|
||||
boolTrue = Bool; </p>
|
||||
<p>// Boolean for diagonal queries<br>
|
||||
boolStat statTrue:int statFalse:int statUnknown:int = BoolStat; </p>
|
||||
<p>// Vector<br>
|
||||
vector {t:Type} # [t] = Vector t;<br>
|
||||
tuple {t:Type} {n:#} [t] = Tuple t n;<br>
|
||||
vectorTotal {t:Type} total_count:int vector:%(Vector t) = VectorTotal t; </p>
|
||||
<p>/////<br>
|
||||
//<br>
|
||||
// Result- (Maybe-) types<br>
|
||||
//<br>
|
||||
///// </p>
|
||||
<p>resultFalse {t:Type} = Maybe t;<br>
|
||||
resultTrue {t:Type} result:t = Maybe t; </p>
|
||||
<p>pair {X:Type} {Y:Type} a:X b:Y = Pair X Y;<br>
|
||||
map {X:Type} {Y:Type} key:X value:Y = Map X Y; </p>
|
||||
<p>Empty False;<br>
|
||||
true = True; </p>
|
||||
<p>unit = Unit; </p>
|
||||
</div>
|
||||
<ul>
|
||||
<li>
|
||||
<p>Predefined identifier <code>Type</code>: This type signifies the type of all types. It is usually used to specify the types of optional parameters in the constructors of polymorphic types. If strongly desired, it can be used in its own right, but this is very rarely needed in practice.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Identifier <code>#</code>: This type is used to specify a special type of nonnegative integers in the range from 0 to 2^31-1; its main purpose is the same as that of <code>Type</code>. There are two built-in constructors: <code>O</code> : # and <code>S</code> : # -> # (“null” and “next number”, respectively), which work as if <code>#</code> was defined using the schema</p>
|
||||
</li>
|
||||
</ul>
|
||||
<div class="richcode">
|
||||
<p>O = #;<br>
|
||||
S # = #; </p>
|
||||
</div>
|
||||
<ul>
|
||||
<li>
|
||||
<p>Identifier <code>Tuple</code>: Type -> # -> Type denotes a set of the specified number of values of the indicated type. In other words, <em>Tuple X n</em> means “a set of <em>n</em> values of type <em>X</em>".</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>The type<code>Bool</code>, with two constructors <code>boolTrue</code> and <code>boolFalse</code>, is used to transmit Boolean values.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>The constructor-less type <code>False</code> may be used instead of undeclared or invalid types in the construction of a TL schema, because any attempt to (de)serialize a value of type <code>False</code> will produce an error. Usage Example:</p>
|
||||
</li>
|
||||
</ul>
|
||||
<div class="richcode">
|
||||
<p>user {flags:#} id:flags.0?string first_name:flags.1?string last_name:flags.2?string reserved3:flags.3?False reserved4:flags.4?False = User flags;<br>
|
||||
user_present {flags:#} info:%(User flags) = UserInfo flags;<br>
|
||||
user_absent {flags:#} = UserInfo flags;<br>
|
||||
getUser flags:# id:int = !UserInfo flags; </p>
|
||||
</div>
|
||||
<p>In the future, bits 3 and 4 in the <code>flags</code> field may be used to transmit new fields after changing the names and types of the <code>reserved3</code> and <code>reserved4</code> fields. This will change the <code>user</code> constructor’s number, but this isn’t too important, since the <code>User flags</code> type is only used as a bare type. Transmitting bits 3 or 4 in the <code>flags</code> field in a <code>getUser</code> query before these fields have actually been defined will lead to an error in the (de)serialization of the request.</p>
|
||||
<ul>
|
||||
<li>The type <code>True</code> with a single null constructor <code>true</code> plays a role similar to the void type in C/C++. It is especially useful as a bare type <code>%True</code>, alias <code>true</code>, because its serialization has zero length. For example, the <code>first_name:flags.1?string</code> constructor used above is in fact shorthand for (the as-yet unsupported) alternative-type general constructor <code>first_name:(flags.1?string:true)</code>.</li>
|
||||
</ul>
|
||||
<p>When directly used in a <a href="https://core.telegram.org/mtproto/TL-combinators#conditional-fields">conditional field</a> it may simply indicate the presence (absence) of a certain parameter with void type.
|
||||
If the conditional field exists, the associated parameter will not be populated; the conditional field simply exists and the existance value can be used to perform certain operations, example:</p>
|
||||
<pre><code>user {flags:#} id:flags.0?string first_name:flags.1?string last_name:flags.2?string bot:flags.3?true reserved4:flags.4?False = User flags;</code></pre>
|
||||
<p>If bit 3 of the <code>flags</code> parameter isn't set, the user is a normal user.
|
||||
If bit 3 of the <code>flags</code> parameter is set, this indicates that the specified user is a bot: however, during deserialization, the <code>bot</code> parameter must not be assigned any value, since <code>true</code> is actually a <code>void</code> type.</p>
|
||||
<ul>
|
||||
<li>The type<code>Unit</code> with a single null constructor <code>Unit</code> is similar to the previous type.</li>
|
||||
</ul>
|
||||
<h4><a class="anchor" href="#antlr-definition" id="antlr-definition" name="antlr-definition"><i class="anchor-icon"></i></a>ANTLR definition</h4>
|
||||
<p>An <a href="https://www.antlr.org">ANLTR</a> definition of TL grammar can be found <a href="https://gitlab.com/telekram/telekram/-/blob/master/generator/src/commonMain/antlr/TL.g4">here »</a>. </p></div>
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="footer_wrap">
|
||||
<div class="footer_columns_wrap footer_desktop">
|
||||
<div class="footer_column footer_column_telegram">
|
||||
<h5>Telegram</h5>
|
||||
<div class="footer_telegram_description"></div>
|
||||
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
|
||||
</div>
|
||||
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/faq">About</a></h5>
|
||||
<ul>
|
||||
<li><a href="//telegram.org/faq">FAQ</a></li>
|
||||
<li><a href="//telegram.org/blog">Blog</a></li>
|
||||
<li><a href="//telegram.org/jobs">Jobs</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
|
||||
<ul>
|
||||
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
|
||||
<li><a href="//telegram.org/dl/android">Android</a></li>
|
||||
<li><a href="//telegram.org/dl/wp">Windows Phone</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
|
||||
<ul>
|
||||
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
|
||||
<li><a href="//macos.telegram.org/">macOS</a></li>
|
||||
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer_column footer_column_platform">
|
||||
<h5><a href="/">Platform</a></h5>
|
||||
<ul>
|
||||
<li><a href="/api">API</a></li>
|
||||
<li><a href="//translations.telegram.org/">Translations</a></li>
|
||||
<li><a href="//instantview.telegram.org/">Instant View</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div class="footer_columns_wrap footer_mobile">
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/faq">About</a></h5>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/blog">Blog</a></h5>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/apps">Apps</a></h5>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="/">Platform</a></h5>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<script src="/js/main.js?42"></script>
|
||||
|
||||
<script>backToTopInit("Go up");
|
||||
removePreloadInit();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
|
@ -1,198 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html class="">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Getting started with TDLib</title>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta property="description" content="TDLib is a fully functional Telegram client which takes care of all networking, local storage and data consistency details.…">
|
||||
<meta property="og:title" content="Getting started with TDLib">
|
||||
<meta property="og:image" content="">
|
||||
<meta property="og:description" content="TDLib is a fully functional Telegram client which takes care of all networking, local storage and data consistency details.…">
|
||||
<link rel="shortcut icon" href="/favicon.ico?4" type="image/x-icon" />
|
||||
|
||||
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
|
||||
|
||||
<link href="/css/telegram.css?212" rel="stylesheet" media="screen">
|
||||
<style>
|
||||
</style>
|
||||
</head>
|
||||
<body class="preload">
|
||||
<div class="dev_page_wrap">
|
||||
<div class="dev_page_head navbar navbar-static-top navbar-tg">
|
||||
<div class="navbar-inner">
|
||||
<div class="container clearfix">
|
||||
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
|
||||
<ul class="nav navbar-nav">
|
||||
<li><a href="//telegram.org/">Home</a></li>
|
||||
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
|
||||
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
|
||||
<li class=""><a href="/api">API</a></li>
|
||||
<li class=""><a href="/mtproto">Protocol</a></li>
|
||||
<li class=""><a href="/schema">Schema</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="container clearfix">
|
||||
<div class="dev_page">
|
||||
<div id="dev_page_content_wrap" class=" ">
|
||||
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/tdlib" >Telegram Database Library</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/tdlib/getting-started" >Getting started</a></li></ul></div>
|
||||
<h1 id="dev_page_title">Getting started with TDLib</h1>
|
||||
|
||||
<div id="dev_page_content"><!-- scroll_nav -->
|
||||
|
||||
<p><strong>TDLib</strong> is a fully functional Telegram client which takes care of all networking, local storage and data consistency details. In this tutorial we describe the main concepts understanding of which is required for effecient TDLib usage.</p>
|
||||
<h3><a class="anchor" name="tdlib-interface" href="#tdlib-interface"><i class="anchor-icon"></i></a>TDLib interface</h3>
|
||||
<p>In this text, <em>Client</em> means an interface for interaction with a TDLib instance and <em>Application</em> means the program that uses TDLib to interact with Telegram.</p>
|
||||
<p>The main TDLib API is fully-asyncronous. An <em>Application</em> can send a request to TDLib through <code>Client.send</code> method and receive a response asynchronously through the <code>Client.receive</code> method when it becomes available. The exact naming of these methods and the way in which requests are matched with responses is different for different TDLib interfaces, but the concept as a whole remains the same. For example, in <em>TDLib</em> <a href="https://core.telegram.org/tdlib/docs/td__json__client_8h.html"><em>JSON</em></a> interface these methods are called <code>td_json_client_send</code> and <code>td_json_client_receive</code>, and their <em>@extra</em> field should be used to match requests with the corresponding responses.</p>
|
||||
<p>In a high-level interface used by an <em>Application</em> the matching of responses with corresponding requests is often automated and transformed by some wrapper into a call to a continuation, a callback, a Promise or a Future to simplify the handling of responses.</p>
|
||||
<p>Aside from responses to requests, an <em>Application</em> receives a lot of important data through incoming <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_update.html"><em>updates</em></a>. <em>Updates</em> are used to pass new data from TDLib to the <em>Application</em> and often control the behavior of the <em>Application</em>, leaving no chance to implement something wrong. The correct handling of <em>updates</em> is crucial for creating an <em>Application</em> that is efficient and works correctly.</p>
|
||||
<blockquote>
|
||||
<p>You can find a <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_function.html">list of all available TDLib API methods</a> in our web-documentation. You can also find the descriptions of all available TDLib methods and classes in the <a href="https://github.com/tdlib/td/blob/master/td/generate/scheme/td_api.tl">TDLIB API scheme</a>.</p>
|
||||
<p>TDLib can be used from any programming language. You can find a lot of examples of TDLib-based frameworks in various programming languages in our <a href="https://github.com/tdlib/td/tree/master/example#readme">examples section</a>.</p>
|
||||
</blockquote>
|
||||
<h3><a class="anchor" name="tdlib-glossary" href="#tdlib-glossary"><i class="anchor-icon"></i></a>TDLib glossary</h3>
|
||||
<p>This section describes the basic notions required for understanding the <em>TDLib API</em>. If you have used the TDLib-based <a href="https://core.telegram.org/bots/api">Telegram Bot API</a> most of them should be already familiar to you.</p>
|
||||
<p>Telegram is a messenger, so the main object is a <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1message.html"><em>message</em></a>. Each <em>message</em> belongs to some <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat.html">chat</a> and has a unique identifier within that <em>chat</em>. <em>Messages</em> inside a <em>chat</em> should be sorted by that identifier. Telegram supports many different kinds of <em>messages</em>, so a <em>message</em> can have many different kinds of <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_message_content.html"><em>message content</em></a>. Currently there are more than 40 different kinds of <em>message content</em>, for example <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1message_text.html"><em>messageText</em></a> for text messages, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1message_photo.html"><em>messagePhoto</em></a> for photos, or <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1message_screenshot_taken.html"><em>messageScreenshotTaken</em></a> for notifications about screenshots taken by the other party.</p>
|
||||
<p>A Telegram user is called <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1user.html"><em>user</em></a>. Each <em>user</em> has a unique identifier and a <em>first name</em>, and can also have an optional <em>last name</em>, <em>username</em> and <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1profile_photo.html"><em>profile photo</em></a> among other useful fields. <em>Bot</em> is a special <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1user_type_bot.html">type</a> of <em>user</em> which can be controlled through the <a href="https://core.telegram.org/bots/api">Telegram Bot API</a>.</p>
|
||||
<p>Each <em>chat</em> has <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_member.html"><em>members</em></a>, i.e. <em>users</em> that immediately receive all <em>messages</em> sent to the <em>chat</em>. Currently there are <strong>6</strong> possible <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_chat_member_status.html">chat member statuses</a> which describe different rights and restrictions a <em>user</em> can have in a <em>chat</em>, ranging from the <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_member_status_creator.html">owner of the chat</a> who has more rights in the <em>chat</em> than any other <em>user</em>, to a <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_member_status_banned.html">user banned in the chat</a> who is <em>banned</em> in the <em>chat</em> and can't return to it by self or even view <em>chat messages</em>, even if the <em>chat</em> is <em>public</em>.</p>
|
||||
<p>As noted earlier, each <em>message</em> belongs to a <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat.html">chat</a>. Currently there are <strong>4</strong> different <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_chat_type.html">types</a> of <em>chats</em> on Telegram:</p>
|
||||
<ul>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_type_private.html">Private chats</a> are ordinary one-to-one chats with another <em>user</em> (or with oneself in the case of the special “Saved messages” chat).</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_type_basic_group.html">Basic groups</a> are basic groups with 0-200 <em>members</em>. Every <em>basic group</em> <em>member</em> has their own copy of the message history, so new <em>basic group</em> <em>members</em> may not see older <em>messages</em> (unless another user forwards their own copy to them).</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_type_supergroup.html">Supergroups</a> are groups with up to 200000 <em>members</em> who share a common message history, so new <em>supergroup</em> <em>members</em> can see all the previously sent <em>messages</em> (unless this is explicitly forbidden by the <em>chat creator</em>). There is a special kind of <em>supergroups</em>, called <em>channels</em>, which can have an unlimited number of members and where only the <em>chat creator</em> and some <em>chat administrators</em> can write. All other <em>chat members</em> can only read <em>channel</em> <em>messages</em>.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_type_secret.html">Secret chats</a> are end-to-end encrypted one-to-one <em>chats</em> with another <em>user</em>, available only on the device which was used to initiate and accept the chat.</li>
|
||||
</ul>
|
||||
<p>Each chat has a unique identifier, a <em>title</em> and an optional <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_photo.html">chat photo</a>. Chats comprise sorted lists shown to the user, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_position.html">position</a> in which is determined, roughly speaking, by the time of latest activity. The correct order of chats in chat lists is maintained by TDLib, so the <em>Application</em> only needs to listen to updates that change the <code>chat.positions</code> field and sort all chats by the pair <code>(position.order, chat.id)</code> in a given <code>position.list</code>.</p>
|
||||
<p><em>Messages</em>, <em>chat photos</em> and many other objects can have a <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1file.html"><em>file</em></a> inside of them. Each <em>file</em> has an identifier and may be available <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1local_file.html">locally</a> on a hard drive or <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1remote_file.html">remotely</a> on a cloud server. A <em>file</em> can be usually <em>downloaded</em> to the local hard drive or <em>uploaded</em> to Telegram cloud servers.</p>
|
||||
<p><em>Messages</em> with media content like <em>photos</em> or <em>videos</em> can have a short accompanying text called <em>caption</em>. The texts of text messages and media captions can contain fragments, which should be formatted in some unusual way. These fragments are called <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1text_entity.html"><em>text entities</em></a> and the combination of a <em>text</em> and its <em>entities</em> are referred together as a <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1formatted_text.html"><em>formatted text</em></a>.</p>
|
||||
<p>TDLib sends a lot of important data to the <em>Application</em> through <em>updates</em>. For example, if there is a user unknown to the <em>Application</em>, or some data about a user has changed, then TDLib immediately sends an <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_user.html"><em>updateUser</em></a> to the <em>Application</em>.</p>
|
||||
<blockquote>
|
||||
<p>You can find list of all currently available updates <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_update.html">here »</a></p>
|
||||
</blockquote>
|
||||
<h3><a class="anchor" name="user-authorization" href="#user-authorization"><i class="anchor-icon"></i></a>User authorization</h3>
|
||||
<p>Authorization is an example of a behavior, which is controlled by <em>TDLib</em> through <em>updates</em>. Whenever an action is required to proceed with user authorization, the <em>Application</em> receives an <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_authorization_state.html"><em>updateAuthorizationState</em></a> with the description of the current <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_authorization_state.html"><em>AuthorizationState</em></a>. The <em>Application</em> only needs to handle this <em>update</em> appropriately to correctly implement user authorization.</p>
|
||||
<p>The first <em>authorization state</em> received by the <em>Application</em> is always of the type <code>authorizationStateWaitTdlibParameters</code>. When it is received, the <em>Application</em> should provide parameters for <em>TDLib</em> initialization by calling the <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1set_tdlib_parameters.html"><em>setTdlibParameters</em></a> method. In this method the <em>Application</em> will need to specify, among other parameters:</p>
|
||||
<ul>
|
||||
<li>api_id — <em>Application</em> identifier for accessing the Telegram API, which can be obtained at https://my.telegram.org.</li>
|
||||
<li>api_hash — Hash of the <em>Application</em> identifier for accessing the Telegram API, which can be obtained at https://my.telegram.org.</li>
|
||||
<li>database_directory — The path to the directory on the local disk where the <em>TDLib</em> database is to be stored; must point to a writable directory.</li>
|
||||
<li>use_message_database — If set to true, the library will maintain a local cache of <em>chats</em> and <em>messages</em>.</li>
|
||||
<li>use_secret_chats — If set to true, support for <em>secret chats</em> will be enabled.</li>
|
||||
<li>system_language_code — IETF language tag of the <em>user</em>'s operating system language, like “en-GB”.</li>
|
||||
<li>device_model — Model of the device the <em>Application</em> is being run on, like “Samsung X”.</li>
|
||||
</ul>
|
||||
<p>After call to <code>setTdlibParameters</code> in case of success <em>Application</em> will receive <code>updateAuthorizationState</code> with new state and just needs to handle that update, nothing should be done explicitly. If <code>setTdlibParameters</code> fails, then authorization state is not changed and the <em>Application</em> should try to handle the current <em>authorization state</em> again.</p>
|
||||
<p>The second received authorization state is always <code>authorizationStateWaitEncryptionKey</code>. When it is received, the database encryption key should be provided through a call to <code>checkDatabaseEncryptionKey</code>. For most mobile apps, you can provide an empty database encryption key here (<a href="https://github.com/tdlib/td/issues/188#issuecomment-379536139">more info</a>). If user isn't authorized yet, then some of <code>authorizationStateWaitPhoneNumber</code>, <code>authorizationStateWaitCode</code>, <code>authorizationStateWaitRegistration</code> and <code>authorizationStateWaitPassword</code> <em>authorization states</em> may be received. After completing these authorization steps, the <em>Application</em> will receive <code>authorizationStateReady</code>, meaning that authorization was successful and ordinary requests can be sent now.</p>
|
||||
<blockquote>
|
||||
<p>You can find complete examples of <em>user</em> authorization in our <a href="https://github.com/tdlib/td/blob/eb80924dad30af4e6d8385d058bb7e847174df5e/example/java/org/drinkless/tdlib/example/Example.java#L97">Java</a> and <a href="https://github.com/tdlib/td/blob/eb80924dad30af4e6d8385d058bb7e847174df5e/example/csharp/TdExample.cs#L68">C#</a> examples.</p>
|
||||
</blockquote>
|
||||
<h3><a class="anchor" name="sending-a-message" href="#sending-a-message"><i class="anchor-icon"></i></a>Sending a message</h3>
|
||||
<p>To send any kind of <em>message</em>, the <em>Application</em> needs to call the method <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1send_message.html">sendMessage</a> providing a <code>chat identifier</code> and the <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_input_message_content.html">content of the message to be sent</a>. For example, the <em>Application</em> can send a <em>text message</em> using <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1input_message_text.html">inputMessageText</a> class as input message content, a <em>photo</em> using <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1input_message_photo.html">inputMessagePhoto</a> or a <em>location</em> using <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1input_message_location.html">inputMessageLocation</a>. The <em>Application</em> can use <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1input_file_local.html">inputFileLocal</a> as <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_input_file.html">InputFile</a> in these objects to send a local file from the hard drive.</p>
|
||||
<blockquote>
|
||||
<p>You can find examples of sending a <em>text message</em> in our <a href="https://github.com/tdlib/td/blob/eb80924dad30af4e6d8385d058bb7e847174df5e/example/java/org/drinkless/tdlib/example/Example.java#L304">Java</a> and <a href="https://github.com/tdlib/td/blob/eb80924dad30af4e6d8385d058bb7e847174df5e/example/csharp/TdExample.cs#L214">C#</a> examples.</p>
|
||||
</blockquote>
|
||||
<h3><a class="anchor" name="handling-updates" href="#handling-updates"><i class="anchor-icon"></i></a>Handling updates</h3>
|
||||
<p>All updates and responses to requests should be handled in the order they are received. Here is a list of the most important updates and how they should be handled:</p>
|
||||
<ul>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_authorization_state.html">updateAuthorizationState</a> — The handling of this update is essential for correct <a href="#user-authorization">user authorization</a>.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_new_chat.html">updateNewChat</a> — This update is received whenever a new <em>chat</em> is discovered. This update is guaranteed to come before the <em>chat</em> identifier is returned to the <em>Application</em>. So, whenever an <em>Application</em> receives a <code>chat_id</code>, it never needs to use a <code>getChat</code> request to receive the <em>chat</em> object. Instead it should maintain a cache of <em>chats</em> received through this update and take all the necessary data about <em>chats</em> from this cache.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_user.html">updateUser</a> — This update is received whenever a new <em>user</em> has been discovered or some data about a known <em>user</em> has changed. This update is guaranteed to come before the <em>user</em> identifier is returned to the <em>Application</em>. So, whenever an <em>Application</em> receives a <code>user_id</code>, it never needs to use the <code>getUser</code> request to receive the <em>user</em> object. Instead it should maintain a cache of <em>users</em> received through this update and take all the necessary data about <em>users</em> from this cache.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_basic_group.html">updateBasicGroup</a> — This update is received whenever a new <em>basic group</em> has been discovered or some data about a known <em>basic group</em> has changed. This update is guaranteed to come before the <em>basic group</em> identifier is returned to the <em>Application</em>. So, whenever an <em>Application</em> receives a <code>basic_group_id</code>, it never needs to use the <code>getBasicGroup</code> request to receive the <code>basicGroup</code> object. Instead it should maintain a cache of <em>basic groups</em> received through this update and take all the necessary data about <em>basic groups</em> from this cache.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_supergroup.html">updateSupergroup</a> — This update is received whenever a new <em>supergroup</em> has been discovered or some data about a known <em>supergroup</em> has changed. This update is guaranteed to come before the <em>supergroup</em> identifier is returned to the <em>Application</em>. So, whenever an <em>Application</em> receives a <code>supergroup_id</code>, it never needs to use the <code>getSupergroup</code> request to receive the <em>supergroup</em> object. Instead it should maintain a cache of <em>supergroups</em> received through this update and take all the necessary data about <em>supergroups</em> from this cache.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_secret_chat.html">updateSecretChat</a> — This update is received whenever a new <em>secret chat</em> has been discovered or some data about a known <em>secret chat</em> has changed. This update is guaranteed to come before the <em>secret chat</em> identifier is returned to the <em>Application</em>. So, whenever an <em>Application</em> receives a <code>secret_chat_id</code>, it never needs to use the <code>getSecretChat</code> request to receive the <em>secret chat</em> object. Instead it should maintain a cache of <em>secret chats</em> received through this update and take all the necessary data about <em>secret chats</em> from this cache.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_new_message.html">updateNewMessage</a> — This update is received whenever a new incoming or outgoing <em>message</em> is added to a <em>chat</em>.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_message_send_succeeded.html">updateMessageSendSucceeded</a> — This update is received whenever a <em>message</em> is successfully sent.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_message_content.html">updateMessageContent</a> — This update is received whenever the <em>content</em> of a <em>message</em> changes.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_file.html">updateFile</a> — This update is received whenever information about a file is updated. The handling of this update is essential to follow the progress of files being downloaded or uploaded.</li>
|
||||
<li><a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_title.html">updateChatTitle</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_photo.html">updateChatPhoto</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_permissions.html">updateChatPermissions</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_last_message.html">updateChatLastMessage</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_position.html">updateChatPosition</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_read_inbox.html">updateChatReadInbox</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_read_outbox.html">updateChatReadOutbox</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_reply_markup.html">updateChatReplyMarkup</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_draft_message.html">updateChatDraftMessage</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_notification_settings.html">updateChatNotificationSettings</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_unread_mention_count.html">updateChatUnreadMentionCount</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_default_disable_notification.html">updateChatDefaultDisableNotification</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_is_blocked.html">updateChatIsBlocked</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_is_marked_as_unread.html">updateChatIsMarkedAsUnread</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_has_scheduled_messages.html">updateChatHasScheduledMessages</a>, <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1update_chat_action_bar.html">updateChatActionBar</a> — These updates are received whenever some information about a <em>chat</em> changes, the <em>chats</em> cache should be updated accordingly</li>
|
||||
</ul>
|
||||
<blockquote>
|
||||
<p>For a full list of currently available <em>updates</em> see the documentation for the <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_update.html">Update</a> class.</p>
|
||||
<p>You can find an example of correct handling of some <em>updates</em> in our <a href="https://github.com/tdlib/td/blob/eb80924dad30af4e6d8385d058bb7e847174df5e/example/java/org/drinkless/tdlib/example/Example.java#L378">Java</a> example.</p>
|
||||
</blockquote>
|
||||
<h3><a class="anchor" name="getting-the-lists-of-chats" href="#getting-the-lists-of-chats"><i class="anchor-icon"></i></a>Getting the lists of chats</h3>
|
||||
<p>Currently there are <strong>3</strong> different types of <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_chat_list.html">chat lists</a>:<br>- <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_list_main.html">Main chat list</a>.<br>- <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_list_archive.html">Archive chat list</a>.<br>- <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat_list_filter.html">A folder chat list</a>.</p>
|
||||
<p>The <a href="https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1chat.html#a40cebc843050f52a09e2ef471c9091e1">positions</a> of <em>chats</em> in <em>chat lists</em> are managed by TDLib, so the <em>Application</em> only needs to listen to <em>updates</em> that change the <code>chat.positions</code> field, maintain the list of all <em>chats</em>, sorted by the pair <code>(position.order, chat.id)</code> in descending order, and call <code>getChats</code> only if there are not enough known <em>chats</em>. Responses to <code>getChats</code> can be often safely ignored, because if all <em>updates</em> changing <code>chat.positions</code> are processed correctly, then the <em>chat list</em> should already be up to date. Because <em>chats</em> are sorted in descending order of <code>position.order</code>, the first request to <code>getChats</code> should have <code>offset_order == 2^63 - 1 == 9223372036854775807</code> — the maximum possible value that a signed 64-bit integer can have. For optimal performance, the number of returned <em>chats</em> is chosen by TDLib and can be smaller than the specified <em>limit</em>. If the <em>Application</em> needs more <em>chats</em>, it should repeat the request with adjusted <code>offset_order</code> and <code>offset_chat_id</code> parameters.</p>
|
||||
<blockquote>
|
||||
<p>You can find an example of retrieving the Main <em>chat list</em> in our <a href="https://github.com/tdlib/td/blob/eb80924dad30af4e6d8385d058bb7e847174df5e/example/java/org/drinkless/tdlib/example/Example.java#L248">Java</a> example.</p>
|
||||
</blockquote>
|
||||
<h3><a class="anchor" name="getting-chat-messages" href="#getting-chat-messages"><i class="anchor-icon"></i></a>Getting chat messages</h3>
|
||||
<p>The <em>Application</em> can use the <code>getChatHistory</code> method to get <em>messages</em> in a <em>chat</em>. The <em>messages</em> will be returned in the reverse chronological order (i.e., in descending order of <code>message_id</code>). The <em>Application</em> can pass <code>from_message_id == 0</code> to get <em>messages</em> from the last <em>message</em>. To get more <em>messages</em> than can be returned in one response, the <em>Application</em> needs to pass the identifier of the last <em>message</em> it has received as <code>from_message_id</code> to next request. For optimal performance, the number of the returned <em>messages</em> is chosen by TDLib and can be smaller than the specified <em>limit</em>. If the <em>Application</em> needs more <em>messages</em>, it needs to adjust the <code>from_message_id</code> parameter and repeat the request.</p>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="footer_wrap">
|
||||
<div class="footer_columns_wrap footer_desktop">
|
||||
<div class="footer_column footer_column_telegram">
|
||||
<h5>Telegram</h5>
|
||||
<div class="footer_telegram_description"></div>
|
||||
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
|
||||
</div>
|
||||
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/faq">About</a></h5>
|
||||
<ul>
|
||||
<li><a href="//telegram.org/faq">FAQ</a></li>
|
||||
<li><a href="//telegram.org/blog">Blog</a></li>
|
||||
<li><a href="//telegram.org/jobs">Jobs</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
|
||||
<ul>
|
||||
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
|
||||
<li><a href="//telegram.org/dl/android">Android</a></li>
|
||||
<li><a href="//telegram.org/dl/wp">Windows Phone</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
|
||||
<ul>
|
||||
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
|
||||
<li><a href="//macos.telegram.org/">macOS</a></li>
|
||||
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer_column footer_column_platform">
|
||||
<h5><a href="/">Platform</a></h5>
|
||||
<ul>
|
||||
<li><a href="/api">API</a></li>
|
||||
<li><a href="//translations.telegram.org/">Translations</a></li>
|
||||
<li><a href="//instantview.telegram.org/">Instant View</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div class="footer_columns_wrap footer_mobile">
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/faq">About</a></h5>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/blog">Blog</a></h5>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="//telegram.org/apps">Apps</a></h5>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="/">Platform</a></h5>
|
||||
</div>
|
||||
<div class="footer_column">
|
||||
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<script src="/js/main.js?42"></script>
|
||||
<script src="/js/jquery.min.js?1"></script>
|
||||
<script src="/js/bootstrap.min.js"></script>
|
||||
|
||||
<script>window.initDevPageNav&&initDevPageNav();
|
||||
backToTopInit("Go up");
|
||||
removePreloadInit();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Loading…
Reference in a new issue