2013-07-09 21:25:10 +02:00
<!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://frontendplay.com/Content/Images/frontendplay-200.png" />
2013-07-13 14:21:53 +02:00
< link rel = "icon" type = "image/png" href = "/Assets/Images/pocketsharp.png" />
< link rel = "image_src" href = "/Assets/Images/pocketsharp.png" />
2013-07-09 21:25:10 +02:00
2013-07-13 14:21:53 +02:00
< link href = "/Release/app.css" rel = "stylesheet" />
2013-07-09 21:25:10 +02:00
</ head >
2013-07-09 22:57:45 +02:00
2013-07-09 21:25:10 +02:00
< body >
2013-07-09 22:17:55 +02:00
< 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
2013-09-17 23:28:28 +02:00
< br >< br >
Current version: < b > 1.2.0</ b >
2013-07-09 22:17:55 +02:00
</ p >
2013-07-09 22:57:45 +02:00
< div class = "app-nuget" >
< code > Install-Package PocketSharp</ code >
</ div >
2013-07-13 00:04:35 +02:00
< 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 >
2013-07-09 22:17:55 +02:00
</ aside >
< div class = "app-main" >
2013-07-09 22:57:45 +02:00
< nav class = "app-nav" >
2013-07-13 12:51:49 +02:00
< a href = "#" data-id = "gettingstarted" class = "is-active" > Getting Started</ a >
< a href = "#" data-id = "authentication" > Authentication</ a >
< a href = "#" data-id = "retrieve" > Retrieve</ a >
< a href = "#" data-id = "add" > Add</ a >
< a href = "#" data-id = "modify" > Modify</ a >
2013-07-09 22:57:45 +02:00
</ nav >
< article class = "article" >
2013-07-09 22:17:55 +02:00
2013-07-13 12:22:56 +02:00
< div data-part = "gettingstarted" >
2013-09-15 15:46:13 +02:00
< 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 >
2013-07-13 12:22:56 +02:00
< 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 >
2013-07-13 12:39:29 +02:00
2013-07-13 12:22:56 +02:00
< pre class = "language-clike" >< code > using PocketSharp;
2013-07-13 12:39:29 +02:00
using PocketSharp.Models;</ code ></ pre >
2013-07-13 12:22:56 +02:00
< p > Initialize PocketClient with:</ p >
2013-07-13 12:39:29 +02:00
2013-07-13 12:22:56 +02:00
< pre class = "language-clike" >< code > PocketClient _client = new PocketClient(" [YOUR_CONSUMER_KEY]" , " [YOUR_ACCESS_CODE]" );</ code ></ pre >
2013-07-13 12:39:29 +02:00
2013-07-13 12:22:56 +02:00
< p > Do a simple request - e.g. a search for < code > CSS</ code > :</ p >
2013-07-13 12:39:29 +02:00
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > await _client.Search(" css" ).ForEach(
item => Debug.WriteLine(item.ID + " | " + item.Title)
2013-07-13 12:22:56 +02:00
);</ code ></ pre >
2013-07-13 12:39:29 +02:00
2013-07-13 12:22:56 +02:00
< p > Which will output:</ p >
< pre class = "language-markup" >< code > 330361896 | CSS Front-end Frameworks with comparison : By usabli.ca
2013-07-13 12:39:29 +02:00
345541438 | Editr - HTML, CSS, JavaScript playground
251743431 | CSS Architecture
343693149 | CSS3 Transitions - Thank God We Have A Specification!
...</ code ></ pre >
2013-07-09 22:17:55 +02:00
2013-07-13 12:22:56 +02:00
< h2 > Create an instance</ h2 >
< p > Constructor:</ p >
2013-07-13 12:39:29 +02:00
2013-07-13 12:22:56 +02:00
< pre class = "language-clike" >< code > PocketClient(string consumerKey, string accessCode = null, Uri callbackUri = null)</ code ></ pre >
2013-07-13 12:39:29 +02:00
2013-07-13 12:22:56 +02:00
< 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 >
2013-07-13 12:39:29 +02:00
2013-07-13 12:22:56 +02:00
< pre class = "language-clike" >< code > PocketClient _client = new PocketClient(
2013-07-13 12:39:29 +02:00
consumerKey: " 123498237423498723498723" ,
callbackUri: new Uri(" http:⁄⁄ ceecore.com" ),
accessCode: " 097809-oi987-izi8-jk98-oiuu89"
);</ code ></ pre >
2013-07-13 12:22:56 +02:00
< p > You can change the < em > Access Code</ em > after initialization:</ p >
2013-07-13 12:39:29 +02:00
2013-07-13 12:22:56 +02:00
< pre class = "language-clike" >< code > _client.AccessCode = " [YOU_ACCESS_CODE]" ;</ code ></ pre >
2013-07-13 12:39:29 +02:00
2013-07-13 12:22:56 +02:00
< 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 >
2013-09-17 23:28:28 +02:00
< li > 2013-09-17 v1.2.0 simplified retrieve methods</ li >
< li > 2013-09-17 v1.1.0 fix modification requests</ li >
2013-09-15 15:46:13 +02:00
< li > 2013-09-15 v1.0.0 convert to PCL & implement async</ li >
2013-08-19 09:06:54 +02:00
< li > 2013-08-16 v0.3.2 tag modification fixed and full retrieval of items for Retrieve method</ li >
2013-07-13 12:22:56 +02:00
< li > 2013-07-07 v0.3.1 authentication fixes</ li >
< li > 2013-07-02 v0.3.0 update authentication process </ li >
< li > 2013-06-27 v0.2.0 add, modify item & modify tags</ li >
< li > 2013-06-26 v0.1.0 authentication & retrieve functionality</ li >
</ ul >
< h2 > Used Packages</ h2 >
< ul >
2013-09-15 15:46:13 +02:00
< 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 >
2013-07-13 12:22:56 +02:00
</ ul >
< h2 > Contributors</ h2 >
2013-07-09 22:57:45 +02:00
< p >
2013-07-13 12:22:56 +02:00
< 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 >
2013-07-09 22:57:45 +02:00
</ p >
2013-07-13 12:22:56 +02:00
</ div >
< div data-part = "authentication" >
< h2 > Authentication</ h2 >
2013-07-09 22:57:45 +02:00
< 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 >
2013-07-13 12:39:29 +02:00
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > string requestCode = await _client.GetRequestCode();
2013-07-09 22:57:45 +02:00
// 0f453f2d-1605-8584-28fd-39af8e
Uri authenticationUri = _client.GenerateAuthenticationUri();
2013-07-13 00:04:35 +02:00
// https://getpocket.com/auth/authorize?request_token=0f453f2d-1605-8584-28fd-39af8e& redirect_uri=http%253a%252f%252fceecore.com</ code ></ pre >
2013-07-13 12:39:29 +02:00
2013-07-09 22:57:45 +02:00
< 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 >
2013-09-15 15:46:13 +02:00
< p > Call < code > Task< string> GetAccessCode(string requestCode = null)</ code ></ p >
2013-07-13 12:39:29 +02:00
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > string accessCode = await _client.GetAccessCode();
2013-07-13 00:04:35 +02:00
// fa8bfc16-69b3-4d22-7db7-84a58d</ code ></ pre >
2013-07-13 12:39:29 +02:00
2013-07-09 22:57:45 +02:00
< 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 >
2013-09-15 15:46:13 +02:00
2013-07-13 12:22:56 +02:00
</ div >
2013-09-15 15:46:13 +02:00
2013-07-13 12:22:56 +02:00
< div data-part = "retrieve" >
< h2 > Retrieve</ h2 >
2013-09-17 23:28:28 +02:00
< p > Get list of all items:</ p >
< p >< pre class = "language-clike" >< code > List< PocketItem> items = await _client.Retrieve();
// equivalent to: await _client.RetrieveByFilter(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.Retrieve(
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.Retrieve(count: 10, offset: 20, sort: Sort.oldest);</ 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:</ p >
< p >< pre class = "language-clike" >< code > List< PocketItem> items = await _client.Search(" css" );</ code ></ pre ></ p >
< p > Get a filtered list:</ p >
< p >< pre class = "language-clike" >< code > List< PocketItem> items = await _client.RetrieveByFilter(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 >
2013-07-13 12:22:56 +02:00
</ div >
< div data-part = "add" >
< h2 > Add</ h2 >
2013-07-09 22:57:45 +02:00
< p >
Adds a new item to your pocket list.
Accepts four parameters, with < code > uri</ code > being required.
</ p >
2013-07-13 12:39:29 +02:00
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > Task< PocketItem> Add(Uri uri, string[] tags = null, string title = null, string tweetID = null)</ code ></ pre >
2013-07-13 12:39:29 +02:00
2013-07-09 22:57:45 +02:00
< p > Example:</ p >
2013-07-13 12:39:29 +02:00
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > PocketItem newItem = await _client.Add(
2013-07-13 00:04:35 +02:00
new Uri(" http:⁄⁄ www.neowin.net/news/full-build-2013-conference-sessions-listing-revealed" ),
2013-07-09 22:57:45 +02:00
new string[] { " microsoft" , " neowin" , " build" }
2013-07-13 00:04:35 +02:00
);</ code ></ pre >
2013-07-13 12:39:29 +02:00
2013-07-09 22:57:45 +02:00
< 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 >
2013-09-15 15:46:13 +02:00
2013-07-13 12:22:56 +02:00
</ div >
< div data-part = "modify" >
2013-09-15 15:46:13 +02:00
2013-07-13 12:22:56 +02:00
< h2 > Modify</ h2 >
2013-07-09 22:57:45 +02:00
< p > All Modify methods accept either the itemID (as int) or a < code > PocketItem</ code > as parameter.</ p >
< p > Archive the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.Archive(myPocketItem);
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-09 22:57:45 +02:00
< p > Un-archive the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.Unarchive(myPocketItem);
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-09 22:57:45 +02:00
< p > Favorites the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.Favorite(myPocketItem);
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-09 22:57:45 +02:00
< p > Un-favorites the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.Unfavorite(myPocketItem);
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-09 22:57:45 +02:00
< p > Deletes the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.Delete(myPocketItem);
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-09 22:57:45 +02:00
< h4 > Modify tags</ h4 >
< p > Add tags to the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.AddTags(myPocketItem, new string[] { " css" , " 2013" });
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-09 22:57:45 +02:00
< p > Remove tags from the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.RemoveTags(myPocketItem, new string[] { " css" , " 2013" });
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-09 22:57:45 +02:00
< p > Remove all tags from the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.RemoveTags(myPocketItem);
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-09 22:57:45 +02:00
< p > Replaces all existing tags with new ones for the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.ReplaceTags(myPocketItem, new string[] { " css" , " 2013" });
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-09 22:57:45 +02:00
< p > Renames a tag for the specified item:</ p >
2013-09-15 15:46:13 +02:00
< pre class = "language-clike" >< code > bool isSuccess = await _client.RenameTag(myPocketItem, " oldTagName" , " newTagName" );
2013-07-09 22:17:55 +02:00
</ code ></ pre >
2013-07-13 12:22:56 +02:00
</ div >
2013-07-09 22:17:55 +02:00
2013-07-09 22:57:45 +02:00
</ article >
2013-07-09 22:17:55 +02:00
</ div >
</ div >
2013-07-09 21:25:10 +02:00
2013-07-13 14:21:53 +02:00
< script src = "/Release/app.js" ></ script >
2013-07-09 21:25:10 +02:00
</ body >
2013-07-09 22:57:45 +02:00
</ html >
