1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
// Copyright 2020 - developers of the `grammers` project. // // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or // https://www.apache.org/licenses/LICENSE-2.0> or the MIT license // <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your // option. This file may not be copied, modified, or distributed // except according to those terms. //! This library contains the Rust definitions for Telegram's [`types`] and //! [`functions`] in the form of `struct` and `enum`. All of them implement //! [`Serializable`], and by default only types implement [`Deserializable`]. //! //! If you're here because you want to invoke the "raw API" methods Telegram //! has to offer, use the search or read through the available [`functions`] //! to find out what "parameters" such remote call needs. Then, create an //! instance of it and pass it to some higher level library that can talk //! with Telegram's servers. //! //! To preserve compatibility with older applications, the API has a concept //! of "layers", where new layers can change, remove or add new definitions. //! The [`LAYER`] constant indicates which of the many layers was used to //! generate the definitions present in this version of this crate. //! //! # Usage //! //! The primary purpose is using these definitions to create requests //! (known as [`functions`]) which can be serialized and sent to Telegram. //! Note that this crate has no way to "invoke" any of these requests, //! this is to be done by a higher-level crate. //! //! All of the requests implement [`RemoteCall`]. This trait's associated //! type indicates what type the response from Telegram will be when invoked. //! //! After opening one of the many [`types`], you can inspect their fields //! to figure out what data Telegram will return. //! //! # Features //! //! The default feature set is intended to make the use of the library //! comfortable, and not intended to be minimal in code size. If you need //! a smaller libary or are concerned about build-times, consider disabling //! some of the default features. //! //! The default feature set includes: //! //! * `impl-debug`. //! * `impl-from-enum`. //! * `impl-from-type`. //! * `tl-api`. //! //! The available features are: //! //! * `deserializable-functions`: implements [`Deserializable`] for //! [`functions`]. This might be of interest for server implementations, //! which need to deserialize the client's requests, but is otherwise not //! required. //! //! * `impl-debug`: implements `Debug` for the generated code. //! //! * `impl-from-enum`: implements `TryFrom<Enum> for Type`. //! //! * `impl-from-type`: implements `From<Type> for Enum`. //! //! * `tl-api`: generates code for the `api.tl`. //! This is what high-level libraries often need. //! //! * `tl-mtproto`: generates code for the `mtproto.tl`. //! Only useful for low-level libraries. //! //! [`types`]: types/index.html //! [`functions`]: functions/index.html //! [`RemoteCall`]: trait.RemoteCall.html //! [`Serializable`]: trait.Serializable.html //! [`Deserializable`]: trait.Deserializable.html //! [`LAYER`]: constant.LAYER.html mod deserializable; pub mod errors; mod generated; mod serializable; pub(crate) use deserializable::{Buffer as InBuffer, Result as DeserializeResult}; pub use deserializable::{Cursor, Deserializable}; pub use generated::{enums, functions, types, LAYER}; pub(crate) use serializable::Buffer as OutBuffer; pub use serializable::Serializable; /// This struct represents the concrete type of a vector, that is, /// `vector` as opposed to the type `Vector`. This bare type is less /// common, so instead of creating a enum for `Vector` wrapping `vector` /// as Rust's `Vec` (as we would do with auto-generated code), /// a new-type for `vector` is used instead. #[derive(Clone, Debug, PartialEq)] pub struct RawVec<T>(pub Vec<T>); /// This struct represents an unparsed blob, which should not be deserialized /// as a bytes string. Used by functions returning generic objects which pass /// the underlying result without any modification or interpretation. #[derive(Clone, Debug, PartialEq)] pub struct Blob(pub Vec<u8>); impl From<Vec<u8>> for Blob { fn from(value: Vec<u8>) -> Self { Self(value) } } /// Anything implementing this trait is identifiable by both ends (client-server) /// when performing Remote Procedure Calls (RPC) and transmission of objects. pub trait Identifiable { /// The unique identifier for the type. const CONSTRUCTOR_ID: u32; } /// Structures implementing this trait indicate that they are suitable for /// use to perform Remote Procedure Calls (RPC), and know what the type of /// the response will be. pub trait RemoteCall: Serializable { /// The type of the "return" value coming from the other end of the /// connection. type Return: Deserializable; }