Improved examples documentation

Examples/Program_CollectAccessHash.cs

@@ -43,6 +43,14 @@ namespace WTelegramClientTest
 			}
 			else
 			{
+				// Zero means the access hash for Durov's Channel was not collected yet.
+				// So we need to obtain it through Client API calls whose results contains the access_hash field, such as:
+				// - Messages_GetAllChats (see Program_GetAllChats.cs   for an example on how to use it)
+				// - Messages_GetDialogs  (see Program_ListenUpdates.cs for an example on how to use it)
+				// - Contacts_ResolveUsername                (see below for an example on how to use it)
+				// and many more API methods...
+				// The access_hash fields can be found inside instance of User, Channel, Photo, Document, etc..
+				// usually listed through their base class UserBase, ChatBase, PhotoBase, DocumentBase, etc...
 				Console.WriteLine("Resolving channel @durov to get its ID, access hash and other infos...");
 				var durovResolved = await client.Contacts_ResolveUsername("durov"); // @durov = Durov's Channel 
 				if (durovResolved.peer.ID != DurovID)

Examples/Program_GetAllChats.cs

@@ -9,6 +9,7 @@ namespace WTelegramClientTest
 	class Program_GetAllChats
 	{
 		// This code is similar to what you should have obtained if you followed the README introduction
+		// I've just added a few comments to explain further what's going on
 
 		// go to Project Properties > Debug > Environment variables and add at least these: api_id, api_hash, phone_number
 		static string Config(string what)
@@ -30,7 +31,7 @@ namespace WTelegramClientTest
 			var user = await client.LoginUserIfNeeded();
 			Console.WriteLine($"We are logged-in as {user.username ?? user.first_name + " " + user.last_name} (id {user.id})");
 
-			var chats = await client.Messages_GetAllChats(null);
+			var chats = await client.Messages_GetAllChats(null); // chats = groups/channels (does not include users dialogs)
 			Console.WriteLine("This user has joined the following:");
 			foreach (var chat in chats.chats)
 				switch (chat)
@@ -42,7 +43,7 @@ namespace WTelegramClientTest
 						Console.WriteLine($"{channel.id}: Channel {channel.username}: {channel.title}");
 						//Console.WriteLine($"              → access_hash = {channel.access_hash:X}");
 						break;
-					case Channel group:
+					case Channel group: // no broadcast flag => it's a big group, also called supergroup or megagroup
 						Console.WriteLine($"{group.id}: Group {group.username}: {group.title}");
 						//Console.WriteLine($"              → access_hash = {group.access_hash:X}");
 						break;
@@ -52,7 +53,7 @@ namespace WTelegramClientTest
 			long id = long.Parse(Console.ReadLine());
 			var target = chats.chats.First(chat => chat.ID == id);
 			Console.WriteLine($"Sending a message in chat {target.ID}: {target.Title}");
-			// This line implicitely creates an adequate InputPeer (with eventual access_hash) from ChatBase:
+			// Next line implicitely creates an adequate InputPeer from ChatBase: (with the access_hash if these is one)
 			InputPeer peer = target;
 			await client.SendMessageAsync(peer, "Hello, World");
 		}

Examples/Program_ListenUpdates.cs

@@ -20,7 +20,7 @@ namespace WTelegramClientTest
 			users[my.id] = my;
 			// note that on login Telegram may sends a bunch of updates/messages that happened in the past and were not acknowledged
 			Console.WriteLine($"We are logged-in as {my.username ?? my.first_name + " " + my.last_name} (id {my.id})");
-			var dialogsBase = await client.Messages_GetDialogs(default, 0, null, 0, 0);
+			var dialogsBase = await client.Messages_GetDialogs(default, 0, null, 0, 0); // dialogs = groups/channels/users
 			if (dialogsBase is Messages_Dialogs dialogs)
 				while (dialogs.dialogs.Length != 0)
 				{
@@ -33,7 +33,7 @@ namespace WTelegramClientTest
 					dialogs = (Messages_Dialogs)await client.Messages_GetDialogs(lastMsg?.Date ?? default, lastDialog.top_message, offsetPeer, 500, 0);
 				}
 			Console.ReadKey();
-			await client.Ping(43); // dummy API call.. this is used to force an acknowledge on this session's updates
+			await client.Ping(42); // dummy API call
 		}
 
 

README.md

@@ -99,15 +99,15 @@ await client.SendMessageAsync(target, "Hello, World");
 
 # Other things to know
 
-The Client class also offers an `Update` event that is triggered when Telegram servers sends unsollicited Updates or notifications/information/status/service messages, independently of your API requests.
+The Client class also offers an `Update` event that is triggered when Telegram servers sends unsollicited Updates or notifications/information/status/service messages, independently of your API requests. See [Examples/Program_ListenUpdates.cs](https://github.com/wiz0u/WTelegramClient/blob/master/Examples/Program_ListenUpdates.cs)
 
 An invalid API request can result in a `RpcException` being raised, reflecting the [error code and status text](https://revgram.github.io/errors.html) of the problem.
 
 The other configuration items that you can override include: **session_pathname, server_address, device_model, system_version, app_version, system_lang_code, lang_pack, lang_code, user_id**
 
-Optional API parameters have a default value of `null` when unset. Passing `null` for a required string/array is the same as *empty* (0-length). Required API parameters/fields can sometimes be set to 0 or `null` when unused (check API documentation).
+Optional API parameters have a default value of `null` when unset. Passing `null` for a required string/array is the same as *empty* (0-length). Required API parameters/fields can sometimes be set to 0 or `null` when unused (check API documentation or experiment).
 
-I've added several useful converters or implicit cast to various API object so that they are more easy to manipulate.
+I've added several useful converters, implicit cast or helper properties to various API object so that they are more easy to manipulate.
 
 Beyond the TL async methods, the Client class offers a few other methods to simplify the sending/receiving of files, medias or messages.
 

src/Client.cs

@@ -22,6 +22,8 @@ namespace WTelegram
 {
 	public sealed class Client : IDisposable
 	{
+		/// <summary>This event will be called when an unsollicited update/message is sent by Telegram servers</summary>
+		/// <remarks>See <see href="https://github.com/wiz0u/WTelegramClient/tree/master/Examples/Program_ListenUpdate.cs">Examples/Program_ListenUpdate.cs</see> for how to use this</remarks>
 		public event Action<ITLObject> Update;
 		public Config TLConfig { get; private set; }
 		public int MaxAutoReconnects { get; set; } = 5; // number of automatic reconnections on connection/reactor failure
@@ -1218,7 +1220,9 @@ namespace WTelegram
 		readonly Dictionary<Type, Dictionary<long, long>> _accessHashes = new();
 		public IEnumerable<KeyValuePair<long, long>> AllAccessHashesFor<T>() where T : ITLObject
 			=> _accessHashes.GetValueOrDefault(typeof(T));
-		/// <summary>Retrieve the access_hash associated with this id (for a TL class)</summary>
+		/// <summary>Retrieve the access_hash associated with this id (for a TL class) if it was collected</summary>
+		/// <remarks>This requires <see cref="CollectAccessHash"/> to be set to <see langword="true"/> first.
+		/// <br/>See <see href="https://github.com/wiz0u/WTelegramClient/tree/master/Examples/Program_CollectAccessHash.cs">Examples/Program_CollectAccessHash.cs</see> for how to use this</remarks>
 		/// <typeparam name="T">a TL object class. For example User, Channel or Photo</typeparam>
 		public long GetAccessHashFor<T>(long id) where T : ITLObject
 		{