update readme;

fix callbackUri escaping in authentication process;
move Auth Models into Response folder; remove unused usings;
2013-07-07 22:33:09 +02:00 · 2013-07-07 22:31:29 +02:00 · 2013-07-04 23:47:39 +02:00 · 2013-07-03 23:19:47 +02:00 · 2013-07-02 21:15:57 +02:00 · 2013-07-02 21:05:43 +02:00
18 changed files with 306 additions and 125 deletions
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
+    <ProjectGuid>{F1CEA363-7039-40BA-9744-0071F46BB90C}</ProjectGuid>
+    <OutputType>Library</OutputType>
+    <AppDesignerFolder>Properties</AppDesignerFolder>
+    <RootNamespace>PocketSharp.Tests</RootNamespace>
+    <AssemblyName>PocketSharp.Tests</AssemblyName>
+    <TargetFrameworkVersion>v4.0</TargetFrameworkVersion>
+    <FileAlignment>512</FileAlignment>
+    <ProjectTypeGuids>{3AC096D0-A1C2-E12C-1390-A8335801FDAB};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>
+    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">10.0</VisualStudioVersion>
+    <VSToolsPath Condition="'$(VSToolsPath)' == ''">$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)</VSToolsPath>
+    <ReferencePath>$(ProgramFiles)\Common Files\microsoft shared\VSTT\$(VisualStudioVersion)\UITestExtensionPackages</ReferencePath>
+    <IsCodedUITest>False</IsCodedUITest>
+    <TestProjectType>UnitTest</TestProjectType>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
+    <DebugSymbols>true</DebugSymbols>
+    <DebugType>full</DebugType>
+    <Optimize>false</Optimize>
+    <OutputPath>bin\Debug\</OutputPath>
+    <DefineConstants>DEBUG;TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
+    <DebugType>pdbonly</DebugType>
+    <Optimize>true</Optimize>
+    <OutputPath>bin\Release\</OutputPath>
+    <DefineConstants>TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+  </PropertyGroup>
+  <ItemGroup>
+    <Reference Include="System" />
+    <Reference Include="System.Core">
+      <RequiredTargetFramework>3.5</RequiredTargetFramework>
+    </Reference>
+  </ItemGroup>
+  <Choose>
+    <When Condition="('$(VisualStudioVersion)' == '10.0' or '$(VisualStudioVersion)' == '') and '$(TargetFrameworkVersion)' == 'v3.5'">
+      <ItemGroup>
+        <Reference Include="Microsoft.VisualStudio.QualityTools.UnitTestFramework, Version=10.1.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" />
+      </ItemGroup>
+    </When>
+    <Otherwise>
+      <ItemGroup>
+        <Reference Include="Microsoft.VisualStudio.QualityTools.UnitTestFramework" />
+      </ItemGroup>
+    </Otherwise>
+  </Choose>
+  <ItemGroup>
+    <Compile Include="UnitTest1.cs" />
+    <Compile Include="Properties\AssemblyInfo.cs" />
+  </ItemGroup>
+  <Choose>
+    <When Condition="'$(VisualStudioVersion)' == '10.0' And '$(IsCodedUITest)' == 'True'">
+      <ItemGroup>
+        <Reference Include="Microsoft.VisualStudio.QualityTools.CodedUITestFramework, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
+          <Private>False</Private>
+        </Reference>
+        <Reference Include="Microsoft.VisualStudio.TestTools.UITest.Common, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
+          <Private>False</Private>
+        </Reference>
+        <Reference Include="Microsoft.VisualStudio.TestTools.UITest.Extension, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
+          <Private>False</Private>
+        </Reference>
+        <Reference Include="Microsoft.VisualStudio.TestTools.UITesting, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL">
+          <Private>False</Private>
+        </Reference>
+      </ItemGroup>
+    </When>
+  </Choose>
+  <Import Project="$(VSToolsPath)\TeamTest\Microsoft.TestTools.targets" Condition="Exists('$(VSToolsPath)\TeamTest\Microsoft.TestTools.targets')" />
+  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
+  <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 
+       Other similar extension points exist, see Microsoft.Common.targets.
+  <Target Name="BeforeBuild">
+  </Target>
+  <Target Name="AfterBuild">
+  </Target>
+  -->
+</Project>
@@ -0,0 +1,36 @@
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+// General Information about an assembly is controlled through the following 
+// set of attributes. Change these attribute values to modify the information
+// associated with an assembly.
+[assembly: AssemblyTitle("PocketSharp.Tests")]
+[assembly: AssemblyDescription("")]
+[assembly: AssemblyConfiguration("")]
+[assembly: AssemblyCompany("")]
+[assembly: AssemblyProduct("PocketSharp.Tests")]
+[assembly: AssemblyCopyright("Copyright ©  2013")]
+[assembly: AssemblyTrademark("")]
+[assembly: AssemblyCulture("")]
+
+// Setting ComVisible to false makes the types in this assembly not visible 
+// to COM components.  If you need to access a type in this assembly from 
+// COM, set the ComVisible attribute to true on that type.
+[assembly: ComVisible(false)]
+
+// The following GUID is for the ID of the typelib if this project is exposed to COM
+[assembly: Guid("fbe5a0d2-d0de-44b1-8b8a-cf8cd3ac2230")]
+
+// Version information for an assembly consists of the following four values:
+//
+//      Major Version
+//      Minor Version 
+//      Build Number
+//      Revision
+//
+// You can specify all the values or you can default the Build and Revision Numbers 
+// by using the '*' as shown below:
+// [assembly: AssemblyVersion("1.0.*")]
+[assembly: AssemblyVersion("1.0.0.0")]
+[assembly: AssemblyFileVersion("1.0.0.0")]
@@ -0,0 +1,14 @@
+using System;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace PocketSharp.Tests
+{
+  [TestClass]
+  public class UnitTest1
+  {
+    [TestMethod]
+    public void TestMethod1()
+    {
+    }
+  }
+}
@@ -5,6 +5,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PocketSharp", "PocketSharp\
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PocketSharp.Console", "PocketSharp.Console\PocketSharp.Console.csproj", "{81B7D587-A189-4785-BDFE-CA8A9ABA0760}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PocketSharp.Tests", "PocketSharp.Tests\PocketSharp.Tests.csproj", "{F1CEA363-7039-40BA-9744-0071F46BB90C}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -19,6 +21,10 @@ Global
 		{81B7D587-A189-4785-BDFE-CA8A9ABA0760}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{81B7D587-A189-4785-BDFE-CA8A9ABA0760}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{81B7D587-A189-4785-BDFE-CA8A9ABA0760}.Release|Any CPU.Build.0 = Release|Any CPU
+		{F1CEA363-7039-40BA-9744-0071F46BB90C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{F1CEA363-7039-40BA-9744-0071F46BB90C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{F1CEA363-7039-40BA-9744-0071F46BB90C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{F1CEA363-7039-40BA-9744-0071F46BB90C}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -1,7 +1,5 @@
-using PocketSharp.Models.Authentification;
+using PocketSharp.Models;
 using System;
-using System.Collections.Generic;
-using RestSharp;

 namespace PocketSharp
 {
@@ -11,22 +9,48 @@ namespace PocketSharp
  public partial class PocketClient
  {
    /// <summary>
-    /// Gets the authentification URI.
+    /// Retrieves the requestCode from Pocket.
    /// </summary>
-    /// <param name="callbackUri">The callback URI.</param>
    /// <returns></returns>
-    public Uri Authenticate(Uri callbackUri)
+    public string GetRequestCode()
    {
-      RequestCode response = Get<RequestCode>("oauth/request", new List<Parameter>()
+      // check if request code is available
+      if (CallbackUri == null)
      {
-        new Parameter() { Name = "redirect_uri", Value = callbackUri, Type = ParameterType.GetOrPost }
-      });
+        throw new APIException("Authentication methods need a callbackUri on initialization of the PocketClient class");
+      }
+
+      // do request
+      RequestCode response = Get<RequestCode>("oauth/request", Utilities.CreateParamInList("redirect_uri", CallbackUri));

      // save code to client
      RequestCode = response.Code;

      // generate redirection URI and return
-      return new Uri(string.Format(authentificationUrl, RequestCode, Uri.EscapeDataString(callbackUri.ToString())));
+      return RequestCode;
+    }
+
+
+    /// <summary>
+    /// Generate Authentication URI from requestCode
+    /// </summary>
+    /// <param name="requestCode">The requestCode.</param>
+    /// <returns></returns>
+    public Uri GenerateAuthenticationUri(string requestCode = null)
+    {
+      // check if request code is available
+      if(RequestCode == null && requestCode == null)
+      {
+        throw new APIException("Call GetRequestCode() first to receive a request_code");
+      }
+
+      // override property with given param if available
+      if(requestCode != null)
+      {
+        RequestCode = requestCode;
+      }
+
+      return new Uri(string.Format(authentificationUri, RequestCode, CallbackUri));
    }


@@ -34,18 +58,22 @@ namespace PocketSharp
    /// Requests the access code after authentification
    /// </summary>
    /// <returns></returns>
-    public string GetAccessCode()
+    public string GetAccessCode(string requestCode = null)
    {
      // check if request code is available
-      if(RequestCode == null)
+      if(RequestCode == null && requestCode == null)
      {
-        throw new APIException("Authenticate the user first to receive a request_code");
+        throw new APIException("Call GetRequestCode() first to receive a request_code");
      }

-      AccessCode response = Get<AccessCode>("oauth/authorize", new List<Parameter>()
+      // override property with given param if available
+      if(requestCode != null)
      {
-        new Parameter() { Name = "code", Value = RequestCode, Type = ParameterType.GetOrPost }
-      });
+        RequestCode = requestCode;
+      }
+
+      // do request
+      AccessCode response = Get<AccessCode>("oauth/authorize", Utilities.CreateParamInList("code", RequestCode));

      // save code to client
      AccessCode = response.Code;
@@ -78,7 +78,7 @@ namespace PocketSharp


    /// <summary>
-    /// Replaces the specified tags.
+    /// Replaces all existing tags with new ones.
    /// </summary>
    /// <param name="itemID">The item ID.</param>
    /// <param name="tags">The tags.</param>
@@ -90,7 +90,7 @@ namespace PocketSharp


    /// <summary>
-    /// Replaces the specified tags.
+    /// Replaces all existing tags with new ones.
    /// </summary>
    /// <param name="item">The item.</param>
    /// <param name="tags">The tags.</param>
@@ -182,7 +182,7 @@ namespace PocketSharp.Models
    /// The _ tag dictionary.
    /// </value>
    [DataMember(Name = "tags")]
-    public Dictionary<string, PocketTag> _TagDictionary { get; set; }
+    public Dictionary<string, PocketTag> TagDictionary { get; set; }

    /// <summary>
    /// Gets or sets the _ image dictionary.
@@ -191,7 +191,7 @@ namespace PocketSharp.Models
    /// The _ image dictionary.
    /// </value>
    [DataMember(Name = "images")]
-    public Dictionary<string, PocketImage> _ImageDictionary { get; set; }
+    public Dictionary<string, PocketImage> ImageDictionary { get; set; }

    /// <summary>
    /// Gets or sets the _ video dictionary.
@@ -200,7 +200,7 @@ namespace PocketSharp.Models
    /// The _ video dictionary.
    /// </value>
    [DataMember(Name = "videos")]
-    public Dictionary<string, PocketVideo> _VideoDictionary { get; set; }
+    public Dictionary<string, PocketVideo> VideoDictionary { get; set; }

    /// <summary>
    /// Gets or sets the _ author dictionary.
@@ -209,7 +209,7 @@ namespace PocketSharp.Models
    /// The _ author dictionary.
    /// </value>
    [DataMember(Name = "authors")]
-    public Dictionary<string, PocketAuthor> _AuthorDictionary { get; set; }
+    public Dictionary<string, PocketAuthor> AuthorDictionary { get; set; }


    /// <summary>
@@ -221,7 +221,7 @@ namespace PocketSharp.Models
    [IgnoreDataMember]
    public List<PocketTag> Tags
    {
-      get { return Utilities.DictionaryToList<PocketTag>(_TagDictionary); }
+      get { return Utilities.DictionaryToList<PocketTag>(TagDictionary); }
    }

    /// <summary>
@@ -233,7 +233,7 @@ namespace PocketSharp.Models
    [IgnoreDataMember]
    public List<PocketImage> Images
    {
-      get { return Utilities.DictionaryToList<PocketImage>(_ImageDictionary); }
+      get { return Utilities.DictionaryToList<PocketImage>(ImageDictionary); }
    }

    /// <summary>
@@ -257,7 +257,7 @@ namespace PocketSharp.Models
    [IgnoreDataMember]
    public List<PocketVideo> Videos
    {
-      get { return Utilities.DictionaryToList<PocketVideo>(_VideoDictionary); }
+      get { return Utilities.DictionaryToList<PocketVideo>(VideoDictionary); }
    }

    /// <summary>
@@ -269,7 +269,7 @@ namespace PocketSharp.Models
    [IgnoreDataMember]
    public List<PocketAuthor> Authors
    {
-      get { return Utilities.DictionaryToList<PocketAuthor>(_AuthorDictionary); }
+      get { return Utilities.DictionaryToList<PocketAuthor>(AuthorDictionary); }
    }
  }
 }
@@ -1,6 +1,6 @@
 using System.Runtime.Serialization;

-namespace PocketSharp.Models.Authentification
+namespace PocketSharp.Models
 {
  /// <summary>
  /// Access Code
@@ -6,7 +6,7 @@ namespace PocketSharp.Models
  /// Add Response
  /// </summary>
  [DataContract]
-  class Add : ResponseBase
+  internal class Add : ResponseBase
  {
    /// <summary>
    /// Gets or sets the item.
@@ -6,7 +6,7 @@ namespace PocketSharp.Models
  /// Modify Response
  /// </summary>
  [DataContract]
-  class Modify : ResponseBase
+  internal class Modify : ResponseBase
  {
    /// <summary>
    /// Gets or sets the action results.
@@ -1,6 +1,6 @@
 using System.Runtime.Serialization;

-namespace PocketSharp.Models.Authentification
+namespace PocketSharp.Models
 {
  /// <summary>
  /// Request Code
@@ -6,7 +6,7 @@ namespace PocketSharp.Models
  /// Base for Responses
  /// </summary>
  [DataContract]
-  class ResponseBase
+  internal class ResponseBase
  {
    /// <summary>
    /// Gets or sets a value indicating whether this <see cref="ResponseBase"/> is status.
@@ -7,7 +7,7 @@ namespace PocketSharp.Models
  /// Item Response
  /// </summary>
  [DataContract]
-  class Retrieve : ResponseBase
+  internal class Retrieve : ResponseBase
  {
    /// <summary>
    /// Gets or sets the complete.
@@ -34,7 +34,7 @@ namespace PocketSharp.Models
    /// The _ item dictionary.
    /// </value>
    [DataMember(Name = "list")]
-    public Dictionary<string, PocketItem> _ItemDictionary { get; set; }
+    public Dictionary<string, PocketItem> ItemDictionary { get; set; }

    /// <summary>
    /// Gets the items.
@@ -45,7 +45,7 @@ namespace PocketSharp.Models
    [IgnoreDataMember]
    public List<PocketItem> Items
    {
-      get { return Utilities.DictionaryToList<PocketItem>(_ItemDictionary); }
+      get { return Utilities.DictionaryToList<PocketItem>(ItemDictionary); }
    }
  }
 }
@@ -1,5 +1,6 @@
 using PocketSharp.Models;
 using RestSharp;
+using RestSharp.Contrib;
 using System;
 using System.Collections.Generic;
 using System.Net;
@@ -17,19 +18,19 @@ namespace PocketSharp
    protected readonly RestClient _restClient;

    /// <summary>
-    /// default base URL for the API
+    /// The base URL for the Pocket API
    /// </summary>
-    protected static Uri defaultBaseUrl = new Uri("https://getpocket.com/v3/");
+    protected static Uri baseUri = new Uri("https://getpocket.com/v3/");

    /// <summary>
    /// The authentification URL
    /// </summary>
-    protected static string authentificationUrl = defaultBaseUrl + "auth/authorize?request_token={0}&redirect_uri={1}";
+    protected string authentificationUri = "https://getpocket.com/auth/authorize?request_token={0}&redirect_uri={1}";

    /// <summary>
-    /// base URL for the API
+    /// callback URL for API calls
    /// </summary>
-    protected Uri BaseUrl { get; set; }
+    protected string CallbackUri { get; set; }

    /// <summary>
    /// Accessor for the Pocket API key
@@ -56,52 +57,28 @@ namespace PocketSharp
    /// <summary>
    /// Initializes a new instance of the <see cref="PocketClient"/> class.
    /// </summary>
-    /// <param name="consumerKey">The API key.</param>
-    public PocketClient(string consumerKey)
-      : this(consumerKey, "", defaultBaseUrl) { }
-
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="PocketClient" /> class.
-    /// </summary>
-    /// <param name="consumerKey">The API key.</param>
-    /// <param name="accessCode">The access code.</param>
-    public PocketClient(string consumerKey, string accessCode)
-      : this(consumerKey, accessCode, defaultBaseUrl) { }
-
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="PocketClient" /> class.
-    /// </summary>
-    /// <param name="consumerKey">The API key.</param>
-    /// <param name="baseUrl">The base URL.</param>
-    public PocketClient(string consumerKey, Uri baseUrl)
-      : this(consumerKey, "", baseUrl) { }
-
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="PocketClient"/> class.
-    /// </summary>
-    /// <param name="consumerKey">The API key.</param>
+    /// <param name="consumerKey">The API key</param>
    /// <param name="accessCode">Provide an access code if the user is already authenticated</param>
-    /// <param name="baseUrl">The base URL.</param>
-    public PocketClient(string consumerKey, string accessCode, Uri baseUrl)
+    /// <param name="callbackUri">The callback URL is called by Pocket after authentication</param>
+    public PocketClient(string consumerKey, string accessCode = null, string callbackUri = null)
    {
      // assign public properties
-      BaseUrl = baseUrl;
      ConsumerKey = consumerKey;

      // assign access code if submitted
-      if (accessCode != "")
+      if (accessCode != null)
      {
        AccessCode = accessCode.ToString();
      }

-      // initialize REST client
-      _restClient = new RestClient
+      // assign callback uri if submitted
+      if (callbackUri != null)
      {
-        BaseUrl = BaseUrl.ToString()
-      };
+        CallbackUri = HttpUtility.UrlEncode(callbackUri.ToString());
+      }
+
+      // initialize REST client
+      _restClient = new RestClient(baseUri.ToString());

      // add default parameters to each request
      _restClient.AddDefaultParameter("consumer_key", ConsumerKey);
@@ -56,8 +56,8 @@
    <Compile Include="Components\ModifyTags.cs" />
    <Compile Include="Components\Retrieve.cs" />
    <Compile Include="JsonDeserializer.cs" />
-    <Compile Include="Models\Authentification\AccessCode.cs" />
-    <Compile Include="Models\Authentification\RequestCode.cs" />
+    <Compile Include="Models\Response\AccessCode.cs" />
+    <Compile Include="Models\Response\RequestCode.cs" />
    <Compile Include="Models\Parameters\AddParameters.cs" />
    <Compile Include="Models\PocketAuthor.cs" />
    <Compile Include="Models\PocketImage.cs" />
@@ -75,7 +75,9 @@
    <Compile Include="Properties\AssemblyInfo.cs" />
    <Compile Include="Utilities.cs" />
  </ItemGroup>
-  <ItemGroup />
+  <ItemGroup>
+    <Content Include="authentication-screen.png" />
+  </ItemGroup>
  <ItemGroup>
    <None Include="packages.config" />
  </ItemGroup>
@@ -1,7 +1,7 @@
-using RestSharp;
+
+using RestSharp;
 using System;
 using System.Collections.Generic;
-
 namespace PocketSharp
 {
  /// <summary>
@@ -34,12 +34,20 @@ namespace PocketSharp
    /// <returns></returns>
    public static Parameter CreateParam(string name, object value, ParameterType type = ParameterType.GetOrPost)
    {
-      return new Parameter()
-      {
-        Name = name,
-        Value = value,
-        Type = type
-      };
+      return new Parameter() { Name = name, Value = value, Type = type };
+    }
+
+
+    /// <summary>
+    /// Creates a Parameter object within a list.
+    /// </summary>
+    /// <param name="name">The name.</param>
+    /// <param name="value">The value.</param>
+    /// <param name="type">The type.</param>
+    /// <returns></returns>
+    public static List<Parameter> CreateParamInList(string name, object value, ParameterType type = ParameterType.GetOrPost)
+    {
+      return new List<Parameter>() { CreateParam(name, value, type) };
    }


@@ -1,21 +1,24 @@
 # PocketSharp

-PocketSharp is a C#.NET class library, that integrates the [Pocket API v3](http://getpocket.com/developer).
+> This project is work in progress.
+> PocketSharp will be released as a NuGet package when ready.

-_If you don't know Pocket, be sure to check it out [Pocket](http://getpocket.com). It's an awesome service, which lets you save articles, videos, ... in the cloud and access it from all your devices._
-
-PocketSharp consists of 4 parts:
+**PocketSharp** is a C#.NET class library, that integrates the [Pocket API v3](http://getpocket.com/developer) and consists of 4 parts:

 - Authentication
 - Retrieve
- Modify _(work in progress)_
- Add _(work in progress)_
+- Modify
+- Add
+
+---
+
+_If you don't know [Pocket](http://getpocket.com), be sure to check it out. It's an awesome service that lets you save articles, videos, ... in the cloud and access it from all your devices._

 ---

 ## Usage Example

-Request a Consumer Key on Pocket: [My Applications on Pocket](http://getpocket.com/developer/apps/)
+Request a [Consumer Key on Pocket.](http://getpocket.com/developer/apps/)

 Include the PocketSharp namespace and it's associated models (you will need them later):

@@ -48,20 +51,26 @@ Which will output:

 ## Create an instance

-There are 4 overloads for `PocketClient`:
+Constructor:

 ```csharp
-// used for authentication, when no accessCode is available yet
-PocketClient(string consumerKey)
+PocketClient(string consumerKey, string accessCode = null, Uri callbackUri = null)
+```

-// start the PocketClient with an accessCode
-PocketClient(string consumerKey, string accessCode)
+`consumerKey`: The API key
+<br>
+`accessCode`: Provide an access code if the user is already authenticated
+<br>
+`callbackUri`: The callback URL is called by Pocket after authentication

-// different base URL
-PocketClient(string consumerKey, Uri baseUrl)
+Example:

-// accessCode and different base URL
-PocketClient(string consumerKey, string accessCode, Uri baseUrl)
+```csharp
+PocketClient _client = new PocketClient(
+	consumerKey: "123498237423498723498723",
+	callbackUri: new Uri("http://ceecore.com"),
+	accessCode: "097809-oi987-izi8-jk98-oiuu89"
+);
 ```

 You can change the _Access Code_ after initialization:
@@ -70,46 +79,44 @@ You can change the _Access Code_ after initialization:
 _client.AccessCode = "[YOU_ACCESS_CODE]";
 ```

+**Before authentication** you will need to provide the `callbackUri` for authentication requests.
+<br>
+**After authentication** you will need to provide the `accessCode`.
+
 ## Authentication

 In order to communicate with a Pocket User, you will need a consumer key (which is generated by [creating a new application on Pocket](http://getpocket.com/developer/apps/)) and an **Access Code**.

-This is a 3-step process:
+The authentication is a 3-step process:

-1) Receive the authentication URI from the library by calling `Uri Authenticate(Uri callbackUri)`:
+#### 1) Generate authentication URI
+
+Receive the **request code** and **authentication URI** from the library by calling `string GetRequestCode()`:

 ```csharp
-Uri authenticationUri = client.Authenticate(new Uri("http://example.com"));
+string requestCode = _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
 ```

-The `callbackUri` is the URI which is triggered after the user successfully (or not) authenticated your application. 
+The _request code_ is stored internally, but you can also provide it as param in `GenerateAuthenticationUri(string requestCode = null)`.

-In this step not only the `authenticationUri` is generated, but the PocketSharp client also stores a received _Request Code_ internally.
+#### 2) Redirect to Pocket
+Next you need to redirect the user to the `authenticationUri`, which displays a prompt to grant permissions for the application (see image). After the user granted or denied, he/she is redirected to the `callbackUri`.

-2) Next you need to redirect the user to the `authenticationUri`, which displays a prompt to grant permissions for the application. After the user granted or denied, he/she is redirected to the `callbackUri`.
+![authentication screen](https://raw.github.com/ceee/PocketSharp/master/PocketSharp/authentication-screen.png)

-3) Call `string GetAccessCode()`
+#### 3) Get Access Code
+Call `string GetAccessCode(string requestCode = null)`

 ```csharp
-string accessCode = GetAccessCode();
+string accessCode = _client.GetAccessCode();
+// fa8bfc16-69b3-4d22-7db7-84a58d
 ```

-Again, the received _Access Code_ is stored internally.
-Note that `GetAccessCode` can only be called with an existing _Request Code_. If you need to re-authenticate a user, start again with Step 1).
-
-#### Note
-
-If you need to re-instantiate PocketClient after the redirect, please provide the _Request Code_:
-
-```csharp
-_client.RequestCode = "[YOU_REQUEST_CODE]";
-```
-
-After Step 1) you have public access to the RequestCode property and can store it for later usage.
-
-```csharp
-string requestCode = _client.RequestCode;
-```
+Again, the received _access code_ is stored internally.
+Note that `GetAccessCode` can only be called with an existing _request code_. If you need to re-authenticate a user, start again with Step 1).

 #### Important

@@ -119,6 +126,13 @@ Without it you would always have to redo the authentication process.

 ## Retrieve

+Get list of all items:
+
+```csharp
+List<PocketItem> items = _client.Retrieve();
+// equivalent to: _client.Retrieve(RetrieveFilter.All)
+```
+
 Find items by a tag:

 ```csharp
@@ -205,6 +219,8 @@ Deletes the specified item:

 	bool isSuccess = _client.Delete(myPocketItem);

+#### Modify tags
+
 Add tags to the specified item:

 	bool isSuccess = _client.AddTags(myPocketItem, new string[] { "css", "2013" });
@@ -229,8 +245,16 @@ Renames a tag for the specified item:

 ## Release History

+- 2013-07-07 v0.3.1 authentication fixes
+- 2013-07-02 v0.3.0 update authentication process 
+- 2013-06-27 v0.2.0 add, modify item & modify tags
 - 2013-06-26 v0.1.0 authentication & retrieve functionality

+## Used Packages
+
+- [RestSharp](http://restsharp.org/)
+- [ServiceStack.Text](https://github.com/ServiceStack/ServiceStack.Text)
+
 ## Contributors
 | [![twitter/artistandsocial](http://gravatar.com/avatar/9c61b1f4307425f12f05d3adb930ba66?s=70)](http://twitter.com/artistandsocial "Follow @artistandsocial on Twitter") |
 |---|
Author	SHA1	Message	Date
swcs	c36995ea2e	update readme;	2013-07-07 22:33:09 +02:00
swcs	9d213d309f	fix callbackUri escaping in authentication process;	2013-07-07 22:31:29 +02:00
swcs	01ab0f8bb8	move Auth Models into Response folder; remove unused usings;	2013-07-04 23:47:39 +02:00
swcs	7f38e346a2	add Tests project;	2013-07-03 23:19:47 +02:00
swcs	422ec73374	update documentation;	2013-07-02 21:15:57 +02:00
swcs	5382dd3326	update documentation;	2013-07-02 21:05:43 +02:00
swcs	761a33ebbe	update documentation;	2013-07-02 20:59:06 +02:00
swcs	edccc8891c	update documentation;	2013-07-02 20:58:13 +02:00
swcs	719a53a9c5	fix callback encoding; callback Uri -> string;	2013-07-02 20:43:38 +02:00
swcs	b53067b47b	update authentication process;	2013-07-01 23:17:31 +02:00
swcs	942f08a385	change access modifier for Model Parameters to internal;	2013-07-01 21:54:32 +02:00
swcs	08ea012a23	ähmm	2013-06-30 01:27:18 +02:00
swcs	d2f5342500	update readme	2013-06-27 11:43:23 +02:00
swcs	c4b86a4bfd	update readme	2013-06-27 11:38:57 +02:00