From ec0285077eae5c817e03bdd070341eb2fc972a8e Mon Sep 17 00:00:00 2001 From: Wizou <11647984+wiz0u@users.noreply.github.com> Date: Sun, 25 Sep 2022 19:21:00 +0200 Subject: [PATCH] xmldoc of recent layers --- EXAMPLES.md | 64 +++++++++++++++--------- src/TL.Schema.cs | 114 +++++++++++++++++++++++++++++------------- src/TL.SchemaFuncs.cs | 39 +++++++++++---- 3 files changed, 148 insertions(+), 69 deletions(-) diff --git a/EXAMPLES.md b/EXAMPLES.md index 1a62b18..5244be8 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -15,7 +15,8 @@ go to your **Project Properties > Debug > Environment variables** and add at least these variables with adequate value: **api_id, api_hash, phone_number** Remember that these are just simple example codes that you should adjust to your needs. -In real production code, you might want to properly test the success of each operation or handle exceptions. +In real production code, you might want to properly test the success of each operation or handle exceptions, +and avoid calling the same methods (like `Messages_GetAllChats`) repetitively. ℹ️ WTelegramClient covers 100% of Telegram Client API, much more than the examples below: check the [full API methods list](https://corefork.telegram.org/methods)! More examples can also be found in the [Examples folder](Examples) and in answers to [StackOverflow questions](https://stackoverflow.com/questions/tagged/wtelegramclient). @@ -44,7 +45,7 @@ if (contacts.imported.Length > 0) ```csharp // HTML-formatted text: var text = $"Hello dear {HtmlText.Escape(myself.first_name)}\n" + - "Enjoy this userbot written with WTelegramClient"; + "Enjoy this userbot written with WTelegramClient"; var entities = client.HtmlToEntities(ref text); var sent = await client.SendMessageAsync(InputPeer.Self, text, entities: entities); // if you need to convert a sent/received Message to HTML: (easier to store) @@ -402,22 +403,31 @@ WTelegram.Helpers.Log = (lvl, str) => { }; ```csharp const string old_password = "password"; // current password if any (unused otherwise) const string new_password = "new_password"; // or null to disable 2FA -var accountPassword = await client.Account_GetPassword(); -var password = accountPassword.current_algo == null ? null : await WTelegram.Client.InputCheckPassword(accountPassword, old_password); -accountPassword.current_algo = null; // makes InputCheckPassword generate a new password -var new_password_hash = new_password == null ? null : await WTelegram.Client.InputCheckPassword(accountPassword, new_password); +var accountPwd = await client.Account_GetPassword(); +var password = accountPwd.current_algo == null ? null : await WTelegram.Client.InputCheckPassword(accountPwd, old_password); +accountPwd.current_algo = null; // makes InputCheckPassword generate a new password +var new_password_hash = new_password == null ? null : await WTelegram.Client.InputCheckPassword(accountPwd, new_password); await client.Account_UpdatePasswordSettings(password, new Account_PasswordInputSettings { flags = Account_PasswordInputSettings.Flags.has_new_algo, new_password_hash = new_password_hash?.A, - new_algo = accountPassword.new_algo, + new_algo = accountPwd.new_algo, hint = "new password hint", }); ``` - - - + +### Store session data to database or elsewhere, instead of files + +If you don't want to store session data into files *(for example if your VPS Hosting doesn't allow that)*, or just for easier management, +you can choose to store the session data somewhere else, like in a database. + +The WTelegram.Client constructor takes an optional `sessionStore` parameter to allow storing sessions in an alternate manner. +Use it to pass a custom Stream-derived class that will **read** (first initial call to Length & Read) and **store** (subsequent Writes) session data to database. + +You can find an example for such custom session store in [Examples/Program_Heroku.cs](https://github.com/wiz0u/WTelegramClient/blob/master/Examples/Program_Heroku.cs#L61) + + ### Fun with custom emojies and reactions on pinned messages ```csharp // • Fetch all available standard emoji reactions @@ -430,12 +440,12 @@ var chat = chats.chats[1234567890]; // the chat we want var full = await client.GetFullChat(chat); Reaction reaction = full.full_chat.AvailableReactions switch { - ChatReactionsSome some => some.reactions[0],// only some reactions are allowed => pick the first - ChatReactionsAll all => // all reactions are allowed in this chat + ChatReactionsSome some => some.reactions[0], // only some reactions are allowed => pick the first + ChatReactionsAll all => // all reactions are allowed in this chat all.flags.HasFlag(ChatReactionsAll.Flags.allow_custom) && client.User.flags.HasFlag(TL.User.Flags.premium) - ? new ReactionCustomEmoji { document_id = 5190875290439525089 } // we can use custom emoji reactions here - : new ReactionEmoji { emoticon = all_emoji.reactions[0].reaction }, // else, pick the first standard emoji reaction - _ => null // reactions are not allowed in this chat + ? new ReactionCustomEmoji { document_id = 5190875290439525089 } // we can use custom emoji reactions here + : new ReactionEmoji { emoticon = all_emoji.reactions[0].reaction }, // else, pick the first standard emoji reaction + _ => null // reactions are not allowed in this chat }; if (reaction == null) return; @@ -444,15 +454,21 @@ var messages = await client.Messages_Search(chat, lim foreach (var msg in messages.Messages) await client.Messages_SendReaction(chat, msg.ID, reaction: new[] { reaction }); ``` -*Note: you can find custom emojies document ID via API methods like [Messages_GetFeaturedEmojiStickers](https://corefork.telegram.org/method/messages.getFeaturedEmojiStickers). Access hash is not required* +*Note: you can find custom emoji document IDs via API methods like [Messages_GetFeaturedEmojiStickers](https://corefork.telegram.org/method/messages.getFeaturedEmojiStickers). Access hash is not required* - -### Store session data to database or elsewhere, instead of files + +### Forward or copy a message to another chat +```csharp +// Determine which chats and message to forward/copy +var chats = await client.Messages_GetAllChats(); +var from_chat = chats.chats[1234567890]; // source chat +var to_chat = chats.chats[1234567891]; // destination chat +var history = await client.Messages_GetHistory(from_chat, limit: 1); +var msg = history.Messages[0] as Message; // last message of source chat -If you don't want to store session data into files *(for example if your VPS Hosting doesn't allow that)*, or just for easier management, -you can choose to store the session data somewhere else, like in a database. +// • Forward the message (only the source message id is necessary) +await client.Messages_ForwardMessages(from_chat, new[] { msg.ID }, new[] { WTelegram.Helpers.RandomLong() }, to_chat); -The WTelegram.Client constructor takes an optional `sessionStore` parameter to allow storing sessions in an alternate manner. -Use it to pass a custom Stream-derived class that will **read** (first initial call to Length & Read) and **store** (subsequent Writes) session data to database. - -You can find an example for such custom session store in [Examples/Program_Heroku.cs](https://github.com/wiz0u/WTelegramClient/blob/master/Examples/Program_Heroku.cs#L61) +// • Copy the message (without the "Forwarded" header) +await client.SendMessageAsync(to_chat, msg.message, msg.media?.ToInputMedia(), entities: msg.entities); +``` \ No newline at end of file diff --git a/src/TL.Schema.cs b/src/TL.Schema.cs index 77dcc85..d5ada77 100644 --- a/src/TL.Schema.cs +++ b/src/TL.Schema.cs @@ -727,6 +727,7 @@ namespace TL [IfFlag(19)] public string bot_inline_placeholder; /// Language code of the user [IfFlag(22)] public string lang_code; + /// Emoji status [IfFlag(30)] public EmojiStatus emoji_status; [Flags] public enum Flags : uint @@ -3073,7 +3074,7 @@ namespace TL [TLDef(0x1BB00451)] public class InputMessagesFilterPinned : MessagesFilter { } - /// Object contains info on events occurred. Derived classes: , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , See + /// Object contains info on events occurred. Derived classes: , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , See public abstract class Update : IObject { } /// New message in a private chat or in a basic group. See [TLDef(0x1F2B0AFD)] @@ -3434,15 +3435,18 @@ namespace TL /// New sticker order by sticker ID public long[] order; } - /// Installed stickersets have changed, the client should refetch them using messages.getAllStickers See + /// Installed stickersets have changed, the client should refetch them as described in the docs. See [TLDef(0x31C24808)] public class UpdateStickerSets : Update { + /// Flags, see TL conditional fields public Flags flags; [Flags] public enum Flags : uint { + /// Whether mask stickersets have changed masks = 0x1, + /// Whether the list of installed custom emoji stickersets has changed emojis = 0x2, } } @@ -4252,23 +4256,26 @@ namespace TL /// Some featured custom emoji stickers were marked as read See [TLDef(0xFB4C496C)] public class UpdateReadFeaturedEmojiStickers : Update { } - /// See + /// The emoji status of a certain user has changed See [TLDef(0x28373599)] public class UpdateUserEmojiStatus : Update { + /// User ID public long user_id; + /// New emoji status public EmojiStatus emoji_status; } - /// See + /// The list of recent emoji statuses has changed See [TLDef(0x30F443DB)] public class UpdateRecentEmojiStatuses : Update { } - /// See + /// The list of recent message reactions has changed See [TLDef(0x6F7863F4)] public class UpdateRecentReactions : Update { } /// See [TLDef(0x86FCCF85)] public class UpdateMoveStickerSetToTop : Update { + /// Flags, see TL conditional fields public Flags flags; public long stickerset; @@ -4804,6 +4811,7 @@ namespace TL [IfFlag(2)] public int lang_pack_version; /// Basic language pack version [IfFlag(2)] public int base_lang_pack_version; + /// Default message reaction [IfFlag(15)] public Reaction reactions_default; [Flags] public enum Flags : uint @@ -5880,6 +5888,7 @@ namespace TL public byte[] secure_random; /// The 2FA password will be automatically removed at this date, unless the user cancels the operation [IfFlag(5)] public DateTime pending_reset_date; + /// A verified login email with the specified pattern is configured [IfFlag(6)] public string login_email_pattern; [Flags] public enum Flags : uint @@ -6074,7 +6083,7 @@ namespace TL public DateTime expires; } - /// Represents a stickerset Derived classes: , , , , , See + /// Represents a stickerset Derived classes: , , , , , , , See /// a null value means inputStickerSetEmpty public abstract partial class InputStickerSet : IObject { } /// Stickerset by ID See @@ -6109,10 +6118,10 @@ namespace TL /// Stickers to show when receiving a gifted Telegram Premium subscription See [TLDef(0xC88B3B02)] public class InputStickerSetPremiumGifts : InputStickerSet { } - /// See + /// Generic animation stickerset containing animations to play when reacting to messages using a normal emoji without a custom animation See [TLDef(0x04C4D4CE)] public class InputStickerSetEmojiGenericAnimations : InputStickerSet { } - /// See + /// Default custom emoji status stickerset See [TLDef(0x29D0F5EE)] public class InputStickerSetEmojiDefaultStatuses : InputStickerSet { } @@ -7611,7 +7620,7 @@ namespace TL MissedCall = 0xD61AD6EE, } - /// Type of the verification code that was sent Derived classes: , , , , See + /// Type of the verification code that was sent Derived classes: , , , , , , See public abstract class Auth_SentCodeType : IObject { } /// The code was sent through the telegram app See [TLDef(0x3DBB5986)] @@ -7648,31 +7657,41 @@ namespace TL /// Prefix of the phone number from which the call will be made public string prefix; } - /// See + /// The code was sent via email See [TLDef(0x5A159841)] public class Auth_SentCodeTypeEmailCode : Auth_SentCodeType { + /// Flags, see TL conditional fields public Flags flags; + /// Pattern of the email public string email_pattern; + /// Length of the sent verification code public int length; + /// If set, contains an absolute UNIX timestamp indicating when will the user be able to authorize with a code sent to the user's phone number [IfFlag(2)] public DateTime next_phone_login_date; [Flags] public enum Flags : uint { + /// Whether authorization through Apple ID is allowed apple_signin_allowed = 0x1, + /// Whether authorization through Google ID is allowed google_signin_allowed = 0x2, + /// Field has a value has_next_phone_login_date = 0x4, } } - /// See + /// The user should add and verify an email address in order to login See [TLDef(0xA5491DEA)] public class Auth_SentCodeTypeSetUpEmailRequired : Auth_SentCodeType { + /// Flags, see TL conditional fields public Flags flags; [Flags] public enum Flags : uint { + /// Whether authorization through Apple ID is allowed apple_signin_allowed = 0x1, + /// Whether authorization through Google ID is allowed google_signin_allowed = 0x2, } } @@ -13365,6 +13384,7 @@ namespace TL public string[] video_sections; /// A list of videos public DocumentBase[] videos; + /// Telegram Premium subscription options public PremiumSubscriptionOption[] period_options; /// Related user information public Dictionary users; @@ -13431,155 +13451,181 @@ namespace TL public string title; } - /// See + /// An emoji status See /// a null value means emojiStatusEmpty [TLDef(0x929B619D)] public class EmojiStatus : IObject { + /// Custom emoji document ID public long document_id; } - /// See + /// An emoji status valid until the specified date See [TLDef(0xFA30A8C7, inheritBefore = true)] public class EmojiStatusUntil : EmojiStatus { + /// This status is valid until this date public int until; } - /// See + /// A list of emoji statuses See /// a null value means account.emojiStatusesNotModified [TLDef(0x90C467D1)] public class Account_EmojiStatuses : IObject { + /// Hash for pagination, for more info click here public long hash; + /// Emoji statuses public EmojiStatus[] statuses; } - /// See + /// Message reaction Derived classes: , See /// a null value means reactionEmpty public abstract class Reaction : IObject { } - /// See + /// Normal emoji message reaction See [TLDef(0x1B2286B8)] public class ReactionEmoji : Reaction { + /// Emoji public string emoticon; } - /// See + /// Custom emoji message reaction See [TLDef(0x8935FC73)] public class ReactionCustomEmoji : Reaction { + /// Custom emoji document ID public long document_id; } - /// See + /// Available chat reactions Derived classes: , , See public abstract class ChatReactions : IObject { } - /// See + /// No reactions are allowed See [TLDef(0xEAFC32BC)] public class ChatReactionsNone : ChatReactions { } - /// See + /// All reactions or all non-custom reactions are allowed See [TLDef(0x52928BCA)] public class ChatReactionsAll : ChatReactions { + /// Flags, see TL conditional fields public Flags flags; [Flags] public enum Flags : uint { + /// Whether to allow custom reactions allow_custom = 0x1, } } - /// See + /// Some reactions are allowed See [TLDef(0x661D4037)] public class ChatReactionsSome : ChatReactions { + /// Allowed reactions public Reaction[] reactions; } - /// See + /// List of message reactions See /// a null value means messages.reactionsNotModified [TLDef(0xEAFDF716)] public class Messages_Reactions : IObject { + /// Hash for pagination, for more info click here public long hash; + /// Reactions public Reaction[] reactions; } - /// See + /// Email verification purpose Derived classes: , , See public abstract class EmailVerifyPurpose : IObject { } - /// See + /// Email verification purpose: setup login email See [TLDef(0x4345BE73)] public class EmailVerifyPurposeLoginSetup : EmailVerifyPurpose { public string phone_number; public string phone_code_hash; } - /// See + /// Email verification purpose: change login email See [TLDef(0x527D22EB)] public class EmailVerifyPurposeLoginChange : EmailVerifyPurpose { } - /// See + /// Verify an email for use in telegram passport See [TLDef(0xBBF51685)] public class EmailVerifyPurposePassport : EmailVerifyPurpose { } - /// See + /// Email verification code or token Derived classes: , , See public abstract class EmailVerification : IObject { } - /// See + /// Email verification code See [TLDef(0x922E55A9)] public class EmailVerificationCode : EmailVerification { + /// Received verification code public string code; } - /// See + /// Google ID email verification token See [TLDef(0xDB909EC2)] public class EmailVerificationGoogle : EmailVerification { + /// Token public string token; } - /// See + /// Apple ID email verification token See [TLDef(0x96D074FD)] public class EmailVerificationApple : EmailVerification { + /// Token public string token; } - /// See + /// The email was verified correctly. See [TLDef(0x2B96CD1B)] public class Account_EmailVerified : IObject { + /// The verified email address. public string email; } - /// See + /// The email was verified correctly, and a login code was just sent to it. See [TLDef(0xE1BB0D61, inheritBefore = true)] public class Account_EmailVerifiedLogin : Account_EmailVerified { + /// Info about the sent login code public Auth_SentCode sent_code; } - /// See + /// Describes a Telegram Premium subscription option See [TLDef(0xB6F11EBE)] public class PremiumSubscriptionOption : IObject { + /// Flags, see TL conditional fields public Flags flags; + /// Duration of subscription in months public int months; + /// Three-letter ISO 4217 currency code public string currency; + /// Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). public long amount; + /// Deep link used to initiate payment public string bot_url; + /// Store product ID, only for official apps [IfFlag(0)] public string store_product; [Flags] public enum Flags : uint { + /// Field has a value has_store_product = 0x1, current = 0x2, can_purchase_upgrade = 0x4, } } - /// See + /// Indicates a peer that can be used to send messages See [TLDef(0xB81C7034)] public class SendAsPeer : IObject { + /// Flags, see TL conditional fields public Flags flags; + /// Peer public Peer peer; [Flags] public enum Flags : uint { + /// Whether a Telegram Premium account is required to send messages as this peer premium_required = 0x1, } } diff --git a/src/TL.SchemaFuncs.cs b/src/TL.SchemaFuncs.cs index 9334043..d5b7f7d 100644 --- a/src/TL.SchemaFuncs.cs +++ b/src/TL.SchemaFuncs.cs @@ -126,6 +126,7 @@ namespace TL /// Phone number in the international format /// SMS-message ID, obtained from auth.sendCode /// Valid numerical code from the SMS-message + /// Email verification code or token [Obsolete("Use LoginUserIfNeeded instead of this method. See https://github.com/wiz0u/WTelegramClient/blob/master/FAQ.md#tlsharp")] public static Task Auth_SignIn(this Client client, string phone_number, string phone_code_hash, string phone_code = null, EmailVerification email_verification = null) => client.Invoke(new Auth_SignIn @@ -640,8 +641,9 @@ namespace TL phone_code = phone_code, }); - /// Send the verification email code for telegram passport. See Possible codes: 400 (details) - /// The email where to send the code + /// Send an email verification code. See Possible codes: 400 (details) + /// Verification purpose. + /// The email where to send the code. public static Task Account_SendVerifyEmailCode(this Client client, EmailVerifyPurpose purpose, string email) => client.Invoke(new Account_SendVerifyEmailCode { @@ -649,7 +651,9 @@ namespace TL email = email, }); - /// Verify an email address for telegram passport. See Possible codes: 400 (details) + /// Verify an email address. See Possible codes: 400 (details) + /// Verification purpose + /// Email verification code or token public static Task Account_VerifyEmail(this Client client, EmailVerifyPurpose purpose, EmailVerification verification) => client.Invoke(new Account_VerifyEmail { @@ -1008,14 +1012,16 @@ namespace TL mime_type = mime_type, }); - /// See + /// Set an emoji status See + /// Emoji status to set public static Task Account_UpdateEmojiStatus(this Client client, EmojiStatus emoji_status) => client.Invoke(new Account_UpdateEmojiStatus { emoji_status = emoji_status, }); - /// See + /// Get a list of default suggested emoji statuses See + /// Hash for pagination, for more info click here /// a null value means account.emojiStatusesNotModified public static Task Account_GetDefaultEmojiStatuses(this Client client, long hash = default) => client.Invoke(new Account_GetDefaultEmojiStatuses @@ -1023,7 +1029,8 @@ namespace TL hash = hash, }); - /// See + /// Get recently used emoji statuses See + /// Hash for pagination, for more info click here /// a null value means account.emojiStatusesNotModified public static Task Account_GetRecentEmojiStatuses(this Client client, long hash = default) => client.Invoke(new Account_GetRecentEmojiStatuses @@ -1031,7 +1038,7 @@ namespace TL hash = hash, }); - /// See + /// Clears list of recently used emoji statuses See public static Task Account_ClearRecentEmojiStatuses(this Client client) => client.Invoke(new Account_ClearRecentEmojiStatuses { @@ -3046,6 +3053,7 @@ namespace TL /// React to message See Possible codes: 400,403 (details) /// Whether a bigger and longer reaction should be shown + /// Add this reaction to the recent reactions list /// Peer /// Message ID to react to /// Reaction (a UTF8 emoji) @@ -3202,6 +3210,7 @@ namespace TL /// Web app URL /// If the web app was opened from the attachment menu using a attachment menu deep link, start_param should contain the data from the startattach parameter. /// Theme parameters for the web app + /// Short name of the application; 0-64 English letters, digits, and underscores /// Whether the inline message that will be sent by the bot on behalf of the user once the web app interaction is terminated should be sent in reply to this message ID. /// Open the web app as the specified peer, sending the resulting the message as the specified peer. public static Task Messages_RequestWebView(this Client client, InputPeer peer, InputUserBase bot, string platform, bool from_bot_menu = false, bool silent = false, string url = null, string start_param = null, DataJSON theme_params = null, int? reply_to_msg_id = null, InputPeer send_as = null) @@ -3240,6 +3249,7 @@ namespace TL /// Bot that owns the webapp /// Web app URL /// Theme parameters + /// Short name of the application; 0-64 English letters, digits, and underscores public static Task Messages_RequestSimpleWebView(this Client client, InputUserBase bot, string url, string platform, DataJSON theme_params = null) => client.Invoke(new Messages_RequestSimpleWebView { @@ -3323,7 +3333,10 @@ namespace TL hash = hash, }); - /// See + /// Report a message reaction See + /// Peer where the message was sent + /// Message ID + /// Peer that sent the reaction public static Task Messages_ReportReaction(this Client client, InputPeer peer, int id, InputPeer reaction_peer) => client.Invoke(new Messages_ReportReaction { @@ -3332,7 +3345,9 @@ namespace TL reaction_peer = reaction_peer, }); - /// See + /// Got popular message reactions See + /// Maximum number of results to return, see pagination + /// Hash for pagination, for more info click here /// a null value means messages.reactionsNotModified public static Task Messages_GetTopReactions(this Client client, int limit = int.MaxValue, long hash = default) => client.Invoke(new Messages_GetTopReactions @@ -3341,7 +3356,9 @@ namespace TL hash = hash, }); - /// See + /// Get recently used message reactions See + /// Maximum number of results to return, see pagination + /// Hash for pagination, for more info click here /// a null value means messages.reactionsNotModified public static Task Messages_GetRecentReactions(this Client client, int limit = int.MaxValue, long hash = default) => client.Invoke(new Messages_GetRecentReactions @@ -3350,7 +3367,7 @@ namespace TL hash = hash, }); - /// See + /// Clear recently used message reactions See public static Task Messages_ClearRecentReactions(this Client client) => client.Invoke(new Messages_ClearRecentReactions {