364 lines
18 KiB
HTML
364 lines
18 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<title>PocketSharp - a C#.NET class library that integrates the Pocket API</title>
|
|
<meta charset="utf-8" />
|
|
<meta name="robots" content="index,follow" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
<meta name="description" content="PocketSharp is a C#.NET class library that integrates the Pocket API" />
|
|
<meta name="author" content="cee" />
|
|
<meta name="msvalidate.01" content="8E69C8BDF4C9B86924E9DA609952B416" />
|
|
<meta property="twitter:site" content="@artistandsocial" />
|
|
<meta property="twitter:creator" content="@artistandsocial" />
|
|
<meta property="og:title" content="PocketSharp - a C#.NET class library" />
|
|
<meta property="og:url" content="http://pocketsharp.frontendplay.com/" />
|
|
<meta property="og:site_name" content="PocketSharp" />
|
|
<meta property="og:description" content="PocketSharp is a C#.NET class library that integrates the Pocket API" />
|
|
|
|
<meta property="og:image" content="http://pocketsharp.frontendplay.com/Assets/Images/pocketsharp.png" />
|
|
<link rel="icon" type="image/png" href="/Assets/Images/pocketsharp.png" />
|
|
<link rel="image_src" href="/Assets/Images/pocketsharp.png" />
|
|
|
|
<link href="/Release/app.css" rel="stylesheet" />
|
|
</head>
|
|
|
|
<body>
|
|
<div class="app">
|
|
|
|
<aside class="app-side">
|
|
<h1>
|
|
<a href="/"><i class="entypo-code"></i>PocketSharp</a>
|
|
</h1>
|
|
<p class="app-description">
|
|
PocketSharp is a C#.NET class library, that integrates the Pocket API v3
|
|
<br><br>
|
|
Current version: <b>2.0.0</b><br>
|
|
<a href="https://www.nuget.org/packages/PocketSharp/">@ nuget</a>
|
|
</p>
|
|
<div class="app-nuget">
|
|
<code>Install-Package PocketSharp</code>
|
|
</div>
|
|
<div class="app-social">
|
|
<a href="https://github.com/ceee/PocketSharp"><i class="entypo-github"></i></a>
|
|
<a href="https://twitter.com/artistandsocial"><i class="entypo-twitter"></i></a>
|
|
</div>
|
|
</aside>
|
|
|
|
<div class="app-main">
|
|
<nav class="app-nav">
|
|
<a href="#" data-id="gettingstarted" class="is-active">Getting Started</a>
|
|
<a href="#" data-id="get">Get</a>
|
|
<a href="#" data-id="add">Add</a>
|
|
<a href="#" data-id="reader">Reader</a>
|
|
<a href="#" data-id="modify">Modify</a>
|
|
<a href="#" data-id="account">Account</a>
|
|
</nav>
|
|
<article class="article">
|
|
|
|
<div data-part="gettingstarted">
|
|
<h2>Supported platforms</h2>
|
|
<p>PocketSharp is a <strong>Portable Class Library</strong> (since 1.0.0), therefore it's compatible with multiple platforms:</p>
|
|
<ul>
|
|
<li><strong>.NET</strong> >= 4.0.3 (including WPF)</li>
|
|
<li><strong>Silverlight</strong> >= 4</li>
|
|
<li><strong>Windows Phone</strong> >= 7.5</li>
|
|
<li><strong>Windows Store</strong></li>
|
|
</ul>
|
|
<p>You can find examples for Silverlight 5, WP8 and WPF in the <code>PocketSharp.Examples</code> folder.</p>
|
|
<h2>Async Support</h2>
|
|
<p>All public methods, which communicate with the Pocket servers are asynchronous. So they should be called with the preceding <code>await</code> keyword, and the encapsulated method marked with <code>async</code>.</p>
|
|
<p><em>In PocketSharp versions < 1.0.0 all methods lacked async support and were blocking.</em></p>
|
|
|
|
<h2>Getting Started</h2>
|
|
<p>Request a <a href="http://getpocket.com/developer/apps/">Consumer Key on Pocket.</a></p>
|
|
<p>Include the PocketSharp namespace and it's associated models (you will need them later):</p>
|
|
|
|
<pre class="language-clike"><code>using PocketSharp;
|
|
using PocketSharp.Models;</code></pre>
|
|
|
|
<p>Initialize PocketClient with:</p>
|
|
|
|
<pre class="language-clike"><code>PocketClient _client = new PocketClient("[YOUR_CONSUMER_KEY]", "[YOUR_ACCESS_CODE]");</code></pre>
|
|
|
|
<p>Do a simple request - e.g. a search for <code>CSS</code>:</p>
|
|
|
|
<pre class="language-clike"><code>await _client.Search("css").ForEach(
|
|
item => Debug.WriteLine(item.ID + " | " + item.Title)
|
|
);</code></pre>
|
|
|
|
<p>Which will output:</p>
|
|
<pre class="language-markup"><code>330361896 | CSS Front-end Frameworks with comparison : By usabli.ca
|
|
345541438 | Editr - HTML, CSS, JavaScript playground
|
|
251743431 | CSS Architecture
|
|
343693149 | CSS3 Transitions - Thank God We Have A Specification!
|
|
...</code></pre>
|
|
|
|
<h2>Create an instance</h2>
|
|
<p>Constructor:</p>
|
|
|
|
<pre class="language-clike"><code>PocketClient(string consumerKey, string accessCode = null, Uri callbackUri = null)</code></pre>
|
|
|
|
<p>
|
|
<code>consumerKey</code>: The API key
|
|
<br>
|
|
<code>accessCode</code>: Provide an access code if the user is already authenticated
|
|
<br>
|
|
<code>callbackUri</code>: The callback URL is called by Pocket after authentication
|
|
</p>
|
|
<p>Example:</p>
|
|
|
|
<pre class="language-clike"><code>PocketClient _client = new PocketClient(
|
|
consumerKey: "123498237423498723498723",
|
|
callbackUri: new Uri("http:⁄⁄ceecore.com"),
|
|
accessCode: "097809-oi987-izi8-jk98-oiuu89"
|
|
);</code></pre>
|
|
|
|
<p>You can change the <em>Access Code</em> after initialization:</p>
|
|
|
|
<pre class="language-clike"><code>_client.AccessCode = "[YOU_ACCESS_CODE]";</code></pre>
|
|
|
|
<p>
|
|
<strong>Before authentication</strong> you will need to provide the <code>callbackUri</code> for authentication requests.
|
|
<br>
|
|
<strong>After authentication</strong> you will need to provide the <code>accessCode</code>.
|
|
</p>
|
|
|
|
<h2>Release History</h2>
|
|
<ul>
|
|
<li><b>2.0.0</b> (2013-10-17) Add Reader API</li>
|
|
<li><b>1.5.1</b> (2013-09-30) <code>RetrieveFilter.All</code> didn't work; improve search speed</li>
|
|
<li><b>1.5.0</b> (2013-09-28) add statistics and registration API</li>
|
|
<li><b>1.4.0</b> (2013-09-21) rename <code>Retrieve</code> to <code>Get</code> + update IntelliSense documentation + add <code>GetTags</code> method</li>
|
|
<li><b>1.3.0</b> (2013-09-19) get Item by ID + tag modification bugfixes</li>
|
|
<li><b>1.2.1</b> (2013-09-18) correct parameter conversion for DateTime and Boolean</li>
|
|
<li><b>1.2.0</b> (2013-09-17) simplified retrieve methods</li>
|
|
<li><b>1.1.0</b> (2013-09-17) fix modification requests</li>
|
|
<li><b>1.0.0</b> (2013-09-15) convert to PCL & implement async</li>
|
|
<li><b>0.3.2</b> (2013-08-16) tag modification fixed and full retrieval of items for Retrieve method</li>
|
|
<li><b>0.3.1</b> (2013-07-07) authentication fixes</li>
|
|
<li><b>0.3.0</b> (2013-07-02) update authentication process </li>
|
|
<li><b>0.2.0</b> (2013-06-27) add, modify item & modify tags</li>
|
|
<li><b>0.1.0</b> (2013-06-26) authentication & retrieve functionality</li>
|
|
</ul>
|
|
<h2>Used Packages</h2>
|
|
<ul>
|
|
<li><a href="https://www.nuget.org/packages/Microsoft.Bcl.Async/">Microsoft.Bcl.Async</a></li>
|
|
<li><a href="https://www.nuget.org/packages/Microsoft.Net.Http/">Microsoft.Net.Http</a></li>
|
|
<li><a href="https://www.nuget.org/packages/Newtonsoft.Json/">Newtonsoft.Json</a></li>
|
|
</ul>
|
|
<h2>Contributors</h2>
|
|
<p>
|
|
<a href="https://github.com/ceee" title="Tobias Klika @ceee on github">
|
|
<img src="http://gravatar.com/avatar/9c61b1f4307425f12f05d3adb930ba66?s=40" alt="twitter/artistandsocial" /></a> <a href="https://github.com/ceee">Tobias Klika @ceee</a>
|
|
</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div data-part="account">
|
|
|
|
|
|
<h2>Authentication</h2>
|
|
<p>In order to communicate with a Pocket User, you will need a consumer key (which is generated by <a href="http://getpocket.com/developer/apps/">creating a new application on Pocket</a>) and an <strong>Access Code</strong>.</p>
|
|
<p>The authentication is a 3-step process:</p>
|
|
<h4>1) Generate authentication URI</h4>
|
|
<p>Receive the <strong>request code</strong> and <strong>authentication URI</strong> from the library by calling <code>string GetRequestCode()</code>:</p>
|
|
|
|
<pre class="language-clike"><code>string requestCode = await _client.GetRequestCode();
|
|
// 0f453f2d-1605-8584-28fd-39af8e
|
|
Uri authenticationUri = _client.GenerateAuthenticationUri();
|
|
// https://getpocket.com/auth/authorize?request_token=0f453f2d-1605-8584-28fd-39af8e&redirect_uri=http%253a%252f%252fceecore.com</code></pre>
|
|
|
|
<p>The <em>request code</em> is stored internally, but you can also provide it as param in <code>GenerateAuthenticationUri(string requestCode = null)</code>.</p>
|
|
<h4>2) Redirect to Pocket</h4>
|
|
<p>Next you need to redirect the user to the <code>authenticationUri</code>, which displays a prompt to grant permissions for the application (see image). After the user granted or denied, he/she is redirected to the <code>callbackUri</code>.</p>
|
|
<p>
|
|
<img src="https://raw.github.com/ceee/PocketSharp/master/PocketSharp/authentication-screen.png" alt="authentication screen" /></p>
|
|
<h4>3) Get Access Code</h4>
|
|
<p>Call <code>Task<string> GetAccessCode(string requestCode = null)</code></p>
|
|
|
|
<pre class="language-clike"><code>string accessCode = await _client.GetAccessCode();
|
|
// fa8bfc16-69b3-4d22-7db7-84a58d</code></pre>
|
|
|
|
<p>
|
|
Again, the received <em>access code</em> is stored internally.
|
|
Note that <code>GetAccessCode</code> can only be called with an existing <em>request code</em>. If you need to re-authenticate a user, start again with Step 1).
|
|
</p>
|
|
<h4>Important</h4>
|
|
<p>
|
|
<strong>Be sure to permanently store the <em>Access Code</em> for your user.</strong>
|
|
<br>
|
|
Without it you would always have to redo the authentication process.
|
|
</p>
|
|
|
|
<h2>Account Registration</h2>
|
|
<p>The <code>RegisterAccount</code> method exists in Pocket API v3, but is currently undocumented.
|
|
<br>The user cannot authenticate directly after registration, as the account has to be activated via an opt-in link, which is sent to the e-mail address.</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.RegisterAccount("myUsername", "me@mymail.com", "mypassword");
|
|
</code></pre>
|
|
|
|
<p>After registration you have to remind the user to check his/her mail account.</p>
|
|
|
|
</div>
|
|
|
|
|
|
<div data-part="get">
|
|
|
|
<h2>Get</h2>
|
|
|
|
<p>Get list of all items:</p>
|
|
<p><pre class="language-clike"><code>List<PocketItem> items = await _client.Get();
|
|
// equivalent to: await _client.Get(RetrieveFilter.All)</code></pre></p>
|
|
<p>Get a list with specific parameters (explanation in the <a href="http://getpocket.com/developer/docs/v3/retrieve">Pocket Docs</a>):</p>
|
|
<p><pre class="language-clike"><code>List<PocketItem> items = await _client.Get(
|
|
State? state = null,
|
|
bool? favorite = null,
|
|
string tag = null,
|
|
ContentType? contentType = null,
|
|
Sort? sort = null,
|
|
string search = null,
|
|
string domain = null,
|
|
DateTime? since = null,
|
|
int? count = null,
|
|
int? offset = null
|
|
);</code></pre></p>
|
|
<p>It's best to use parameters as <em>named parameters</em>, to avoid typing <code>null</code> values:</p>
|
|
<p><pre class="language-clike"><code>List<PocketItem> items = await _client.Get(count: 10, offset: 20, sort: Sort.oldest);</code></pre></p>
|
|
<p>Get item by ID:</p>
|
|
<p><pre class="language-clike"><code>PocketItem item = await _client.Get(1298198);</code></pre></p>
|
|
<p>Find items by a tag:</p>
|
|
<p><pre class="language-clike"><code>List<PocketItem> items = await _client.SearchByTag("tutorial");</code></pre></p>
|
|
<p>Find items by a search string.<br>PocketSharp uses an internal search, which is significantly faster than the Search API by Pocket.</p>
|
|
<p><pre class="language-clike"><code>List<PocketItem> items = await _client.Search("css");</code></pre></p>
|
|
<p>Find items by a search string by already available items:</p>
|
|
<p><pre class="language-clike"><code>List<PocketItem> items = await _client.Search(myPocketItemList, "css");</code></pre></p>
|
|
<p>Get all tags:</p>
|
|
<p><pre class="language-clike"><code>List<PocketTag> items = await _client.GetTags();</code></pre></p>
|
|
<p>Get a filtered list:</p>
|
|
<p><pre class="language-clike"><code>List<PocketItem> items = await _client.Get(RetrieveFilter.Favorite);
|
|
// returns favorites only</code></pre></p>
|
|
<p>The RetrieveFilter Enum is specified as follows:</p>
|
|
<p><pre class="language-clike"><code>enum RetrieveFilter { All, Unread, Archive, Favorite, Article, Video, Image }</code></pre></p>
|
|
<h2>Statistics</h2>
|
|
<p>The Pocket API supports retrieval of a simple statistics object.</p>
|
|
<pre class="language-clike"><code>PocketStatistics statistics = await client.Statistics();
|
|
// PocketStatistics: [CountAll], [CountRead], [CountUnread]
|
|
</code></pre>
|
|
</div>
|
|
|
|
<div data-part="add">
|
|
|
|
<h2>Add</h2>
|
|
<p>
|
|
Adds a new item to your pocket list.
|
|
Accepts four parameters, with <code>uri</code> being required.
|
|
</p>
|
|
|
|
<pre class="language-clike"><code>Task<PocketItem> Add(Uri uri, string[] tags = null, string title = null, string tweetID = null)</code></pre>
|
|
|
|
<p>Example:</p>
|
|
|
|
<pre class="language-clike"><code>PocketItem newItem = await _client.Add(
|
|
new Uri("http:⁄⁄www.neowin.net/news/full-build-2013-conference-sessions-listing-revealed"),
|
|
new string[] { "microsoft", "neowin", "build" }
|
|
);</code></pre>
|
|
|
|
<p>The title can be included for cases where an item does not have a title, which is typical for image or PDF URLs. If Pocket detects a title from the content of the page, this parameter will be ignored.</p>
|
|
<p>If you are adding Pocket support to a Twitter client, please send along a reference to the tweet status id (with the tweetID). This allows Pocket to show the original tweet alongside the article.</p>
|
|
|
|
</div>
|
|
|
|
<div data-part="modify">
|
|
|
|
<h2>Modify</h2>
|
|
<p>All Modify methods accept either the itemID (as int) or a <code>PocketItem</code> as parameter.</p>
|
|
<p>Archive the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.Archive(myPocketItem);
|
|
</code></pre>
|
|
|
|
<p>Un-archive the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.Unarchive(myPocketItem);
|
|
</code></pre>
|
|
|
|
<p>Favorites the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.Favorite(myPocketItem);
|
|
</code></pre>
|
|
|
|
<p>Un-favorites the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.Unfavorite(myPocketItem);
|
|
</code></pre>
|
|
|
|
<p>Deletes the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.Delete(myPocketItem);
|
|
</code></pre>
|
|
|
|
<h4>Modify tags</h4>
|
|
<p>Add tags to the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.AddTags(myPocketItem, new string[] { "css", "2013" });
|
|
</code></pre>
|
|
|
|
<p>Remove tags from the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.RemoveTags(myPocketItem, new string[] { "css", "2013" });
|
|
</code></pre>
|
|
|
|
<p>Remove all tags from the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.RemoveTags(myPocketItem);
|
|
</code></pre>
|
|
|
|
<p>Replaces all existing tags with new ones for the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.ReplaceTags(myPocketItem, new string[] { "css", "2013" });
|
|
</code></pre>
|
|
|
|
<p>Renames a tag for the specified item:</p>
|
|
<pre class="language-clike"><code>bool isSuccess = await _client.RenameTag(myPocketItem, "oldTagName", "newTagName");
|
|
</code></pre>
|
|
|
|
</div>
|
|
|
|
<div data-part="reader">
|
|
<h2>Article Reader API</h2>
|
|
<p>PocketSharp 2.0 implements a new <strong>Reader API</strong>.</p>
|
|
<p>This API does _not _use the official (and private) Article View API by Pocket. It is based on a custom PCL port of NReadability and SgmlReader, which are included in the solution.</p>
|
|
<h3>What's it all about?</h3>
|
|
<p>The Reader API extracts the main content of a website and returns the extracted content as HTML and it's associated title (which should already be available in the <code>PocketItem</code>).</p>
|
|
<p>This content can be encapsulated in a <code><body></code>-Tag and displayed as a readable website with a custom CSS (it's up to you!).</p>
|
|
<h3>Implementation</h3>
|
|
<p>As with all PocketSharp implementations you have to require the main namespace and it's model namespace:</p>
|
|
<p><pre class="language-clike"><code>
|
|
using PocketSharp;
|
|
using PocketSharp.Models;</code></pre></p>
|
|
<p>The <code>PocketReader</code> is a seperated class with it's own <code>HttpClient</code>. Create an instance of it:</p>
|
|
<p><pre class="language-clike"><code>
|
|
PocketReader reader = new PocketReader();</code></pre></p>
|
|
<p><code>PocketReader</code> needs a <code>PocketItem</code> as a parameter to correctly identify its <code>ID</code> and <code>Uri</code>. With this requirement you can successfully query for an articles content.<br>
|
|
Don't forget exception handling in case a website is down or not accessible.</p>
|
|
<p><pre class="language-clike"><code>
|
|
PocketArticle article;
|
|
try
|
|
{
|
|
article = await reader.Read(myPocketItem);
|
|
// PocketArticle: {
|
|
// int PocketItemID
|
|
// string Content
|
|
// string Title
|
|
// string NextPageUrl
|
|
// }
|
|
}
|
|
catch (PocketException exc)
|
|
{
|
|
// handle exception
|
|
}
|
|
</code></pre></p>
|
|
|
|
</di>
|
|
|
|
</article>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<script src="/Release/app.js"></script>
|
|
</body>
|
|
</html>
|