diff --git a/index.html b/index.html index ef13d9d..542203e 100644 --- a/index.html +++ b/index.html @@ -12,7 +12,7 @@

TLSharp

-

Telegram client library implemented in C#.

+

Telegram client library implemented in C#

View on GitHub Download .zip Download .tar.gz @@ -47,6 +47,7 @@
  • Available Methods
    • @@ -65,7 +66,7 @@
    1. Clone TLSharp from GitHub
      2. -
    2. Compile source with VS2015
      3. +
    3. Compile source with VS2015 or MonoDevelop
    4. Add reference to TLSharp.Core.dll to your awesome project.
    @@ -146,7 +147,39 @@ All dependencies listed in SendMessageToChannel test

    -Available Methods

    +Working with files + +

    Telegram separate files to two categories -> big file and small file. File is Big if its size more than 10 Mb. TLSharp tries to hide this complexity from you, thats why we provide one method to upload files UploadFile.

    + +
        var fileResult = await client.UploadFile("cat.jpg", new StreamReader("data/cat.jpg"));
    + +

    TLSharp provides two wrappers for sending photo and document

    + +
        await client.SendUploadedPhoto(new TLInputPeerUser() { user_id = user.id }, fileResult, "kitty");
+    await client.SendUploadedDocument(
+                new TLInputPeerUser() { user_id = user.id },
+                fileResult,
+                "some zips", //caption
+                "application/zip", //mime-type
+                new TLVector<TLAbsDocumentAttribute>()); //document attributes, such as file name
    + +

    Full code you can see at SendPhotoToContactTest and SendBigFileToContactTest

    + +

    To download file you should call GetFile method

    + +
        await client.GetFile(
+                new TLInputDocumentFileLocation()
+                {
+                    access_hash = document.access_hash,
+                    id = document.id,
+                    version = document.version
+                },
+                document.size); //size of fileChunk you want to retrieve
    + +

    Full code you can see at DownloadFileFromContactTest

    + +

    +Available Methods

    For your convenience TLSharp have wrappers for several Telegram API methods. You could add your own, see details below.

    @@ -159,6 +192,10 @@ All dependencies listed in The only way is Telegram API docs. Yes, it's outdated. But there is no other source. Latest scheme in JSON format you can find here

    -

    -Contributing

    +

    +Contributing

    Contributing is highly appreciated!

    -

    -What things can I Implement (Project Roadmap)?

    +

    +What things can I Implement (Project Roadmap)?

    -

    -Release 1.0.0

    +

    +Release 1.0.0

    @@ -261,6 +299,7 @@ Bitcoin wallet: 3K1ocweFgaHnAibJ3n6hX7RNZWFTFcJjUe

    diff --git a/params.json b/params.json index 9b204f3..da3652c 100644 --- a/params.json +++ b/params.json @@ -1,6 +1,6 @@ { "name": "TLSharp", - "tagline": "Telegram client library implemented in C#.", - "body": "#TLSharp\r\n\r\n[![Join the chat at https://gitter.im/TLSharp/Lobby](https://badges.gitter.im/TLSharp/Lobby.svg)](https://gitter.im/TLSharp/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)\r\n[![Build status](https://ci.appveyor.com/api/projects/status/95rl618ch5c4h2fa?svg=true)](https://ci.appveyor.com/project/sochix/tlsharp)\r\n\r\n_Unofficial_ Telegram (http://telegram.org) client library implemented in C#. Latest TL scheme supported, thanks to Afshin Arani\r\n\r\n**Consider donation to speed up development process.** \r\n\r\nBitcoin wallet: **3K1ocweFgaHnAibJ3n6hX7RNZWFTFcJjUe**\r\n\r\nIt's a perfect fit for any developer who would like to send data directly to Telegram users or write own custom Telegram client.\r\n\r\n:star2: If you :heart: library, please star it! :star2:\r\n\r\n# Table of contents?\r\n\r\n- [How do I add this to my project?](#how-do-i-add-this-to-my-project)\r\n- [Dependencies](#dependencies)\r\n- [Starter Guide](#starter-guide)\r\n - [Quick configuration](#quick-configuration)\r\n - [First requests](#first-requests)\r\n- [Available Methods](#available-methods)\r\n- [Contributing](#contributing)\r\n- [FAQ](#faq)\r\n- [Donations](#donations)\r\n- [License](#license)\r\n\r\n# How do I add this to my project?\r\n\r\nLibrary _almost_ ready for production usage. We need contributors to make 1.0.0 release.\r\n\r\nTo use TLSharp follow next steps:\r\n\r\n1. Clone TLSharp from GitHub\r\n1. Compile source with VS2015\r\n1. Add reference to ```TLSharp.Core.dll``` to your awesome project.\r\n\r\n# Dependencies\r\n\r\nTLSharp has a few dependenices, most of functionality implemented from scratch.\r\nAll dependencies listed in [package.conf file](https://github.com/sochix/TLSharp/blob/master/TLSharp.Core/packages.config).\r\n\r\n# Starter Guide\r\n\r\n## Quick Configuration\r\nTelegram API isn't that easy to start. You need to do some configuration first.\r\n\r\n1. Create a [developer account](https://my.telegram.org/) in Telegram. \r\n1. Goto [API development tools](https://my.telegram.org/apps) and copy **API_ID** and **API_HASH** from your account. You'll need it later.\r\n\r\n## First requests\r\nTo start work, create an instance of TelegramClient and establish connection\r\n\r\n```csharp \r\n var client = new TelegramClient(apiId, apiHash);\r\n await client.ConnectAsync();\r\n```\r\nNow you can work with Telegram API, but ->\r\n> Only a small portion of the API methods are available to unauthorized users. ([full description](https://core.telegram.org/api/auth)) \r\n\r\nFor authentication you need to run following code\r\n```csharp\r\n var hash = await client.SendCodeRequestAsync(\"\");\r\n var code = \"\"; // you can change code in debugger\r\n\r\n var user = await client.MakeAuthAsync(\"\", hash, code);\r\n``` \r\n\r\nFull code you can see at [AuthUser test](https://github.com/sochix/TLSharp/blob/master/TLSharp.Tests/TLSharpTests.cs#L70)\r\n\r\nWhen user is authenticated, TLSharp creates special file called _session.dat_. In this file TLSharp store all information needed for user session. So you need to authenticate user every time the _session.dat_ file is corrupted or removed.\r\n\r\nYou can call any method on authenticated user. For example, let's send message to a friend by his phone number:\r\n\r\n```csharp\r\n //get available contacts\r\n var result = await client.GetContactsAsync();\r\n\r\n //find recipient in contacts\r\n var user = result.users.lists\r\n\t .Where(x => x.GetType() == typeof (TLUser))\r\n\t .Cast()\r\n\t .FirstOrDefault(x => x.phone == \"\");\r\n\t\r\n //send message\r\n await client.SendMessageAsync(new TLInputPeerUser() {user_id = user.id}, \"OUR_MESSAGE\");\r\n```\r\n\r\nFull code you can see at [SendMessage test](https://github.com/sochix/TLSharp/blob/master/TLSharp.Tests/TLSharpTests.cs#L87)\r\n\r\nTo send message to channel you could use the following code:\r\n```csharp\r\n //get user dialogs\r\n var dialogs = await client.GetUserDialogsAsync();\r\n\r\n //find channel by title\r\n var chat = dialogs.chats.lists\r\n .Where(c => c.GetType() == typeof(TLChannel))\r\n .Cast()\r\n .FirstOrDefault(c => c.title == \"\");\r\n\r\n //send message\r\n await client.SendMessageAsync(new TLInputPeerChannel() { channel_id = chat.id, access_hash = chat.access_hash.Value }, \"OUR_MESSAGE\");\r\n```\r\nFull code you can see at [SendMessageToChannel test](https://github.com/sochix/TLSharp/blob/master/TLSharp.Tests/TLSharpTests.cs#L107)\r\n\r\n## Available Methods\r\n\r\nFor your convenience TLSharp have wrappers for several Telegram API methods. You could add your own, see details below.\r\n\r\n1. IsPhoneRegisteredAsync\r\n1. SendCodeRequestAsync\r\n1. MakeAuthAsync\r\n1. SignUpAsync\r\n1. GetContactsAsync\r\n1. SendMessageAsync\r\n1. SendTypingAsync\r\n1. GetUserDialogsAsync\r\n\r\n**What if you can't find needed method at the list?**\r\n\r\nDon't panic. You can call any method with help of `SendRequestAsync` function. For example, send user typing method: \r\n\r\n```csharp\r\n\r\n //Create request \r\n var req = new TLRequestSetTyping()\r\n {\r\n action = new TLSendMessageTypingAction(),\r\n peer = peer\r\n };\r\n\r\n //run request, and deserialize response to Boolean\r\n return await SendRequestAsync(req);\r\n``` \r\n\r\n**Where you can find a list of requests and its params?**\r\n\r\nThe only way is [Telegram API docs](https://core.telegram.org/methods). Yes, it's outdated. But there is no other source.\r\nLatest scheme in JSON format you can find [here](https://gist.github.com/aarani/b22b7cda024973dff68e1672794b0298)\r\n\r\n## Contributing\r\n\r\nContributing is highly appreciated!\r\n\r\n### What things can I Implement (Project Roadmap)?\r\n\r\n#### Release 1.0.0\r\n\r\n* [DONE] Add PHONE_MIGRATE handling\r\n* Add Updates handling\r\n* Add NuGet package\r\n* [WIP] Add wrappers for media uploading\r\n* Store user session as JSON\r\n\r\n# FAQ\r\n\r\n#### What API layer is supported?\r\nThe latest one - 57. Thanks to Afshin Arani for his TLGenerator\r\n\r\n#### I get an error MIGRATE_X?\r\n\r\nTLSharp library should automatically handle this errors. If you see such errors, pls create a new issue.\r\n\r\n#### I get an exception: System.IO.EndOfStreamException: Unable to read beyond the end of the stream. All test methos except that AuthenticationWorks and TestConnection return same error. I did every thing including setting api id and hash, and setting server address.-\r\n\r\nYou should create a Telegram session. See [configuration guide](#sending-messages-set-up)\r\n\r\n#### Why I get FLOOD_WAIT error?\r\n[It's Telegram restrictions](https://core.telegram.org/api/errors#420-flood)\r\n\r\n#### Why does TLSharp lacks feature XXXX?\r\n\r\nNow TLSharp is basic realization of Telegram protocol, you can be a contributor or a sponsor to speed-up developemnt of any feature.\r\n\r\n#### Nothing helps\r\nAsk your question at gitter or create an issue in project bug tracker.\r\n\r\n**Attach following information**:\r\n\r\n* Full problem description and exception message\r\n* Stack-trace\r\n* Your code that runs in to this exception\r\n\r\nWithout information listen above your issue will be closed. \r\n\r\n# Donations\r\nThanks for donations! It's highly appreciated. \r\nBitcoin wallet: **3K1ocweFgaHnAibJ3n6hX7RNZWFTFcJjUe**\r\n\r\nList of donators:\r\n* [mtbitcoin](https://github.com/mtbitcoin)\r\n\r\n# Contributors\r\n* [Afshin Arani](http://aarani.ir) - TLGenerator, and a lot of other usefull things\r\n\r\n# License\r\n\r\n**Please, provide link to an author when you using library**\r\n\r\nThe MIT License\r\n\r\nCopyright (c) 2015 Ilya Pirozhenko http://www.sochix.ru/\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r\n", + "tagline": "Telegram client library implemented in C#", + "body": "#TLSharp\r\n\r\n[![Join the chat at https://gitter.im/TLSharp/Lobby](https://badges.gitter.im/TLSharp/Lobby.svg)](https://gitter.im/TLSharp/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)\r\n[![Build status](https://ci.appveyor.com/api/projects/status/95rl618ch5c4h2fa?svg=true)](https://ci.appveyor.com/project/sochix/tlsharp)\r\n\r\n_Unofficial_ Telegram (http://telegram.org) client library implemented in C#. Latest TL scheme supported, thanks to Afshin Arani\r\n\r\n**Consider donation to speed up development process.** \r\n\r\nBitcoin wallet: **3K1ocweFgaHnAibJ3n6hX7RNZWFTFcJjUe**\r\n\r\nIt's a perfect fit for any developer who would like to send data directly to Telegram users or write own custom Telegram client.\r\n\r\n:star2: If you :heart: library, please star it! :star2:\r\n\r\n# Table of contents?\r\n\r\n- [How do I add this to my project?](#how-do-i-add-this-to-my-project)\r\n- [Dependencies](#dependencies)\r\n- [Starter Guide](#starter-guide)\r\n - [Quick configuration](#quick-configuration)\r\n - [First requests](#first-requests)\r\n - [Working with files](#working-with-files)\r\n- [Available Methods](#available-methods)\r\n- [Contributing](#contributing)\r\n- [FAQ](#faq)\r\n- [Donations](#donations)\r\n- [License](#license)\r\n\r\n# How do I add this to my project?\r\n\r\nLibrary _almost_ ready for production usage. We need contributors to make 1.0.0 release.\r\n\r\nTo use TLSharp follow next steps:\r\n\r\n1. Clone TLSharp from GitHub\r\n1. Compile source with VS2015 or MonoDevelop\r\n1. Add reference to ```TLSharp.Core.dll``` to your awesome project.\r\n\r\n# Dependencies\r\n\r\nTLSharp has a few dependenices, most of functionality implemented from scratch.\r\nAll dependencies listed in [package.conf file](https://github.com/sochix/TLSharp/blob/master/TLSharp.Core/packages.config).\r\n\r\n# Starter Guide\r\n\r\n## Quick Configuration\r\nTelegram API isn't that easy to start. You need to do some configuration first.\r\n\r\n1. Create a [developer account](https://my.telegram.org/) in Telegram. \r\n1. Goto [API development tools](https://my.telegram.org/apps) and copy **API_ID** and **API_HASH** from your account. You'll need it later.\r\n\r\n## First requests\r\nTo start work, create an instance of TelegramClient and establish connection\r\n\r\n```csharp \r\n var client = new TelegramClient(apiId, apiHash);\r\n await client.ConnectAsync();\r\n```\r\nNow you can work with Telegram API, but ->\r\n> Only a small portion of the API methods are available to unauthorized users. ([full description](https://core.telegram.org/api/auth)) \r\n\r\nFor authentication you need to run following code\r\n```csharp\r\n var hash = await client.SendCodeRequestAsync(\"\");\r\n var code = \"\"; // you can change code in debugger\r\n\r\n var user = await client.MakeAuthAsync(\"\", hash, code);\r\n``` \r\n\r\nFull code you can see at [AuthUser test](https://github.com/sochix/TLSharp/blob/master/TLSharp.Tests/TLSharpTests.cs#L70)\r\n\r\nWhen user is authenticated, TLSharp creates special file called _session.dat_. In this file TLSharp store all information needed for user session. So you need to authenticate user every time the _session.dat_ file is corrupted or removed.\r\n\r\nYou can call any method on authenticated user. For example, let's send message to a friend by his phone number:\r\n\r\n```csharp\r\n //get available contacts\r\n var result = await client.GetContactsAsync();\r\n\r\n //find recipient in contacts\r\n var user = result.users.lists\r\n\t .Where(x => x.GetType() == typeof (TLUser))\r\n\t .Cast()\r\n\t .FirstOrDefault(x => x.phone == \"\");\r\n\t\r\n //send message\r\n await client.SendMessageAsync(new TLInputPeerUser() {user_id = user.id}, \"OUR_MESSAGE\");\r\n```\r\n\r\nFull code you can see at [SendMessage test](https://github.com/sochix/TLSharp/blob/master/TLSharp.Tests/TLSharpTests.cs#L87)\r\n\r\nTo send message to channel you could use the following code:\r\n```csharp\r\n //get user dialogs\r\n var dialogs = await client.GetUserDialogsAsync();\r\n\r\n //find channel by title\r\n var chat = dialogs.chats.lists\r\n .Where(c => c.GetType() == typeof(TLChannel))\r\n .Cast()\r\n .FirstOrDefault(c => c.title == \"\");\r\n\r\n //send message\r\n await client.SendMessageAsync(new TLInputPeerChannel() { channel_id = chat.id, access_hash = chat.access_hash.Value }, \"OUR_MESSAGE\");\r\n```\r\nFull code you can see at [SendMessageToChannel test](https://github.com/sochix/TLSharp/blob/master/TLSharp.Tests/TLSharpTests.cs#L107)\r\n## Working with files\r\nTelegram separate files to two categories -> big file and small file. File is Big if its size more than 10 Mb. TLSharp tries to hide this complexity from you, thats why we provide one method to upload files **UploadFile**.\r\n\r\n```csharp\r\n\tvar fileResult = await client.UploadFile(\"cat.jpg\", new StreamReader(\"data/cat.jpg\"));\r\n```\r\n\r\nTLSharp provides two wrappers for sending photo and document\r\n\r\n```csharp\r\n\tawait client.SendUploadedPhoto(new TLInputPeerUser() { user_id = user.id }, fileResult, \"kitty\");\r\n\tawait client.SendUploadedDocument(\r\n new TLInputPeerUser() { user_id = user.id },\r\n fileResult,\r\n \"some zips\", //caption\r\n \"application/zip\", //mime-type\r\n new TLVector()); //document attributes, such as file name\r\n```\r\nFull code you can see at [SendPhotoToContactTest](https://github.com/sochix/TLSharp/blob/master/TLSharp.Tests/TLSharpTests.cs#L125) and [SendBigFileToContactTest](https://github.com/sochix/TLSharp/blob/master/TLSharp.Tests/TLSharpTests.cs#L143)\r\n\r\nTo download file you should call **GetFile** method\r\n```csharp\r\n\tawait client.GetFile(\r\n new TLInputDocumentFileLocation()\r\n {\r\n access_hash = document.access_hash,\r\n id = document.id,\r\n version = document.version\r\n },\r\n document.size); //size of fileChunk you want to retrieve\r\n```\r\n\r\nFull code you can see at [DownloadFileFromContactTest](https://github.com/sochix/TLSharp/blob/master/TLSharp.Tests/TLSharpTests.cs#L167)\r\n\r\n# Available Methods\r\n\r\nFor your convenience TLSharp have wrappers for several Telegram API methods. You could add your own, see details below.\r\n\r\n1. IsPhoneRegisteredAsync\r\n1. SendCodeRequestAsync\r\n1. MakeAuthAsync\r\n1. SignUpAsync\r\n1. GetContactsAsync\r\n1. SendMessageAsync\r\n1. SendTypingAsync\r\n1. GetUserDialogsAsync\r\n1. SendUploadedPhoto\r\n1. SendUploadedDocument\r\n1. GetFile\r\n1. UploadFile\r\n\r\n**What if you can't find needed method at the list?**\r\n\r\nDon't panic. You can call any method with help of `SendRequestAsync` function. For example, send user typing method: \r\n\r\n```csharp\r\n\r\n //Create request \r\n var req = new TLRequestSetTyping()\r\n {\r\n action = new TLSendMessageTypingAction(),\r\n peer = peer\r\n };\r\n\r\n //run request, and deserialize response to Boolean\r\n return await SendRequestAsync(req);\r\n``` \r\n\r\n**Where you can find a list of requests and its params?**\r\n\r\nThe only way is [Telegram API docs](https://core.telegram.org/methods). Yes, it's outdated. But there is no other source.\r\nLatest scheme in JSON format you can find [here](https://gist.github.com/aarani/b22b7cda024973dff68e1672794b0298)\r\n\r\n# Contributing\r\n\r\nContributing is highly appreciated!\r\n\r\n## What things can I Implement (Project Roadmap)?\r\n\r\n### Release 1.0.0\r\n\r\n* [DONE] Add PHONE_MIGRATE handling\r\n* Add FILE_MIGRATE handling\r\n* Add Updates handling\r\n* Add NuGet package\r\n* [DONE] Add wrappers for media uploading and downloading\r\n* Store user session as JSON\r\n\r\n# FAQ\r\n\r\n#### What API layer is supported?\r\nThe latest one - 57. Thanks to Afshin Arani for his TLGenerator\r\n\r\n#### I get an error MIGRATE_X?\r\n\r\nTLSharp library should automatically handle this errors. If you see such errors, pls create a new issue.\r\n\r\n#### I get an exception: System.IO.EndOfStreamException: Unable to read beyond the end of the stream. All test methos except that AuthenticationWorks and TestConnection return same error. I did every thing including setting api id and hash, and setting server address.-\r\n\r\nYou should create a Telegram session. See [configuration guide](#sending-messages-set-up)\r\n\r\n#### Why I get FLOOD_WAIT error?\r\n[It's Telegram restrictions](https://core.telegram.org/api/errors#420-flood)\r\n\r\n#### Why does TLSharp lacks feature XXXX?\r\n\r\nNow TLSharp is basic realization of Telegram protocol, you can be a contributor or a sponsor to speed-up developemnt of any feature.\r\n\r\n#### Nothing helps\r\nAsk your question at gitter or create an issue in project bug tracker.\r\n\r\n**Attach following information**:\r\n\r\n* Full problem description and exception message\r\n* Stack-trace\r\n* Your code that runs in to this exception\r\n\r\nWithout information listen above your issue will be closed. \r\n\r\n# Donations\r\nThanks for donations! It's highly appreciated. \r\nBitcoin wallet: **3K1ocweFgaHnAibJ3n6hX7RNZWFTFcJjUe**\r\n\r\nList of donators:\r\n* [mtbitcoin](https://github.com/mtbitcoin)\r\n\r\n# Contributors\r\n* [Afshin Arani](http://aarani.ir) - TLGenerator, and a lot of other usefull things\r\n* [Knocte](https://github.com/knocte)\r\n\r\n# License\r\n\r\n**Please, provide link to an author when you using library**\r\n\r\nThe MIT License\r\n\r\nCopyright (c) 2015 Ilya Pirozhenko http://www.sochix.ru/\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r\n", "note": "Don't delete this file! It's used internally to help with page regeneration." } \ No newline at end of file