From bf5d8a50cef95b4a71f4db101bc97f7376bde645 Mon Sep 17 00:00:00 2001
From: Tobias Klika <cee@live.at>
Date: Fri, 8 Nov 2013 01:44:32 +0100
Subject: [PATCH] cancellationToken for ALL methods - completed; remove
 obsolete methods in preparation for v3

---
 PocketSharp/Components/ModifyTags.cs | 210 ++++++++++++++++++++++++---
 PocketSharp/Components/Statistics.cs |  28 +++-
 PocketSharp/IPocketClient.cs         | 134 ++++++++++++++++-
 3 files changed, 345 insertions(+), 27 deletions(-)

diff --git a/PocketSharp/Components/ModifyTags.cs b/PocketSharp/Components/ModifyTags.cs
index 0429e21..4e81995 100644
--- a/PocketSharp/Components/ModifyTags.cs
+++ b/PocketSharp/Components/ModifyTags.cs
@@ -1,4 +1,5 @@
 using PocketSharp.Models;
+using System.Threading;
 using System.Threading.Tasks;
 
 namespace PocketSharp
@@ -17,7 +18,7 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> AddTags(int itemID, string[] tags)
     {
-      return await SendTags(itemID, "tags_add", tags);
+      return await AddTags(CancellationToken.None, itemID, tags);
     }
 
 
@@ -30,7 +31,35 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> AddTags(PocketItem item, string[] tags)
     {
-      return await AddTags(item.ID, tags);
+      return await AddTags(CancellationToken.None, item.ID, tags);
+    }
+
+
+    /// <summary>
+    /// Adds the specified tags to an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> AddTags(CancellationToken cancellationToken, int itemID, string[] tags)
+    {
+      return await SendTags(cancellationToken, itemID, "tags_add", tags);
+    }
+
+
+    /// <summary>
+    /// Adds the specified tags to an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> AddTags(CancellationToken cancellationToken, PocketItem item, string[] tags)
+    {
+      return await AddTags(cancellationToken, item.ID, tags);
     }
 
 
@@ -43,7 +72,7 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> RemoveTags(int itemID, string[] tags)
     {
-      return await SendTags(itemID, "tags_remove", tags);
+      return await RemoveTags(CancellationToken.None, itemID, tags);
     }
 
 
@@ -56,7 +85,35 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> RemoveTags(PocketItem item, string[] tags)
     {
-      return await RemoveTags(item.ID, tags);
+      return await RemoveTags(CancellationToken.None, item.ID, tags);
+    }
+
+
+    /// <summary>
+    /// Removes the specified tags from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> RemoveTags(CancellationToken cancellationToken, int itemID, string[] tags)
+    {
+      return await SendTags(cancellationToken, itemID, "tags_remove", tags);
+    }
+
+
+    /// <summary>
+    /// Removes the specified tags from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="tags">The tag.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> RemoveTags(CancellationToken cancellationToken, PocketItem item, string[] tags)
+    {
+      return await RemoveTags(cancellationToken, item.ID, tags);
     }
 
 
@@ -69,7 +126,7 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> RemoveTag(int itemID, string tag)
     {
-      return await SendTags(itemID, "tags_remove", new string[] { tag });
+      return await RemoveTag(CancellationToken.None, itemID, tag);
     }
 
 
@@ -82,7 +139,35 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> RemoveTag(PocketItem item, string tag)
     {
-      return await RemoveTag(item.ID, tag);
+      return await RemoveTag(CancellationToken.None, item.ID, tag);
+    }
+
+
+    /// <summary>
+    /// Removes a tag from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="tag">The tag.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> RemoveTag(CancellationToken cancellationToken, int itemID, string tag)
+    {
+      return await SendTags(cancellationToken, itemID, "tags_remove", new string[] { tag });
+    }
+
+
+    /// <summary>
+    /// Removes a tag from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="tag">The tag.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> RemoveTag(CancellationToken cancellationToken, PocketItem item, string tag)
+    {
+      return await RemoveTag(cancellationToken, item.ID, tag);
     }
 
 
@@ -94,7 +179,7 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> RemoveTags(int itemID)
     {
-      return await SendDefault(itemID, "tags_clear");
+      return await RemoveTags(CancellationToken.None, itemID);
     }
 
 
@@ -106,7 +191,33 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> RemoveTags(PocketItem item)
     {
-      return await RemoveTags(item.ID);
+      return await RemoveTags(CancellationToken.None, item.ID);
+    }
+
+
+    /// <summary>
+    /// Clears all tags from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> RemoveTags(CancellationToken cancellationToken, int itemID)
+    {
+      return await SendDefault(cancellationToken, itemID, "tags_clear");
+    }
+
+
+    /// <summary>
+    /// Clears all tags from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> RemoveTags(CancellationToken cancellationToken, PocketItem item)
+    {
+      return await RemoveTags(cancellationToken, item.ID);
     }
 
 
@@ -119,7 +230,7 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> ReplaceTags(int itemID, string[] tags)
     {
-      return await SendTags(itemID, "tags_replace", tags);
+      return await ReplaceTags(CancellationToken.None, itemID, tags);
     }
 
 
@@ -132,7 +243,35 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> ReplaceTags(PocketItem item, string[] tags)
     {
-      return await ReplaceTags(item.ID, tags);
+      return await ReplaceTags(CancellationToken.None, item.ID, tags);
+    }
+
+
+    /// <summary>
+    /// Replaces all existing tags with the given tags in an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> ReplaceTags(CancellationToken cancellationToken, int itemID, string[] tags)
+    {
+      return await SendTags(cancellationToken, itemID, "tags_replace", tags);
+    }
+
+
+    /// <summary>
+    /// Replaces all existing tags with the given new ones in an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> ReplaceTags(CancellationToken cancellationToken, PocketItem item, string[] tags)
+    {
+      return await ReplaceTags(cancellationToken, item.ID, tags);
     }
 
 
@@ -146,13 +285,7 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> RenameTag(int itemID, string oldTag, string newTag)
     {
-      return await Send(new ActionParameter()
-      {
-        Action = "tag_rename",
-        ID = itemID,
-        OldTag = oldTag,
-        NewTag = newTag
-      });
+      return await RenameTag(CancellationToken.None, itemID, oldTag, newTag);
     }
 
 
@@ -166,25 +299,62 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<bool> RenameTag(PocketItem item, string oldTag, string newTag)
     {
-      return await RenameTag(item.ID, oldTag, newTag);
+      return await RenameTag(CancellationToken.None, item.ID, oldTag, newTag);
+    }
+
+
+    /// <summary>
+    /// Renames a tag in an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="oldTag">The old tag.</param>
+    /// <param name="newTag">The new tag name.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> RenameTag(CancellationToken cancellationToken, int itemID, string oldTag, string newTag)
+    {
+      return await Send(new ActionParameter()
+      {
+        Action = "tag_rename",
+        ID = itemID,
+        OldTag = oldTag,
+        NewTag = newTag
+      }, cancellationToken);
+    }
+
+
+    /// <summary>
+    /// Renames a tag in an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="oldTag">The old tag.</param>
+    /// <param name="newTag">The new tag name.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<bool> RenameTag(CancellationToken cancellationToken, PocketItem item, string oldTag, string newTag)
+    {
+      return await RenameTag(cancellationToken, item.ID, oldTag, newTag);
     }
 
 
     /// <summary>
     /// Puts the send action for tags.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     /// <param name="itemID">The item ID.</param>
     /// <param name="action">The action.</param>
     /// <param name="tags">The tags.</param>
     /// <returns></returns>
-    protected async Task<bool> SendTags(int itemID, string action, string[] tags)
+    protected async Task<bool> SendTags(CancellationToken cancellationToken, int itemID, string action, string[] tags)
     {
       return await Send(new ActionParameter()
       {
         Action = action,
         ID = itemID,
         Tags = tags
-      });
+      }, cancellationToken);
     }
   }
 }
diff --git a/PocketSharp/Components/Statistics.cs b/PocketSharp/Components/Statistics.cs
index 10c16cc..40d776a 100644
--- a/PocketSharp/Components/Statistics.cs
+++ b/PocketSharp/Components/Statistics.cs
@@ -1,5 +1,6 @@
 using PocketSharp.Models;
 using System;
+using System.Threading;
 using System.Threading.Tasks;
 
 namespace PocketSharp
@@ -16,19 +17,19 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     public async Task<PocketStatistics> GetUserStatistics()
     {
-      return await Request<PocketStatistics>("stats");
+      return await GetUserStatistics(CancellationToken.None);
     }
 
 
     /// <summary>
     /// Statistics from the user account.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     /// <returns></returns>
     /// <exception cref="PocketException"></exception>
-    [Obsolete("Please use GetUserStatistics instead")]
-    public async Task<PocketStatistics> Statistics()
+    public async Task<PocketStatistics> GetUserStatistics(CancellationToken cancellationToken)
     {
-      return await GetUserStatistics();
+      return await Request<PocketStatistics>("stats", cancellationToken);
     }
 
 
@@ -40,13 +41,30 @@ namespace PocketSharp
     /// <returns></returns>
     /// <exception cref="PocketException"></exception>
     public async Task<PocketLimits> GetUsageLimits()
+    {
+      return await GetUsageLimits(CancellationToken.None);
+    }
+
+
+    /// <summary>
+    /// Returns API usage statistics.
+    /// If a request was made before, the data is returned synchronously from the cache.
+    /// Note: This method only works for authenticated users with a given AccessCode.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    public async Task<PocketLimits> GetUsageLimits(CancellationToken cancellationToken)
     {
       string rateLimitForConsumerKey = TryGetHeaderValue(lastHeaders, "X-Limit-Key-Limit");
 
       if (rateLimitForConsumerKey == null)
       {
         // this is the fastest way to do a non-failing request to receive the correct headers
-        await Get(count: 1);
+        await Get(
+          cancellationToken: cancellationToken,
+          count: 1
+        );
       }
 
       return new PocketLimits()
diff --git a/PocketSharp/IPocketClient.cs b/PocketSharp/IPocketClient.cs
index d4f5150..5f47b3f 100644
--- a/PocketSharp/IPocketClient.cs
+++ b/PocketSharp/IPocketClient.cs
@@ -514,6 +514,26 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     Task<bool> AddTags(PocketItem item, string[] tags);
 
+    /// <summary>
+    /// Adds the specified tags to an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> AddTags(CancellationToken cancellationToken, int itemID, string[] tags);
+
+    /// <summary>
+    /// Adds the specified tags to an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> AddTags(CancellationToken cancellationToken, PocketItem item, string[] tags);
+
     /// <summary>
     /// Removes the specified tags from an item.
     /// </summary>
@@ -532,6 +552,26 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     Task<bool> RemoveTags(PocketItem item, string[] tags);
 
+    /// <summary>
+    /// Removes the specified tags from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> RemoveTags(CancellationToken cancellationToken, int itemID, string[] tags);
+
+    /// <summary>
+    /// Removes the specified tags from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="tags">The tag.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> RemoveTags(CancellationToken cancellationToken, PocketItem item, string[] tags);
+
     /// <summary>
     /// Removes a tag from an item.
     /// </summary>
@@ -550,6 +590,26 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     Task<bool> RemoveTag(PocketItem item, string tag);
 
+    /// <summary>
+    /// Removes a tag from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="tag">The tag.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> RemoveTag(CancellationToken cancellationToken, int itemID, string tag);
+
+    /// <summary>
+    /// Removes a tag from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="tag">The tag.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> RemoveTag(CancellationToken cancellationToken, PocketItem item, string tag);
+
     /// <summary>
     /// Clears all tags from an item.
     /// </summary>
@@ -566,6 +626,24 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     Task<bool> RemoveTags(PocketItem item);
 
+    /// <summary>
+    /// Clears all tags from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> RemoveTags(CancellationToken cancellationToken, int itemID);
+
+    /// <summary>
+    /// Clears all tags from an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> RemoveTags(CancellationToken cancellationToken, PocketItem item);
+
     /// <summary>
     /// Replaces all existing tags with the given tags in an item.
     /// </summary>
@@ -584,6 +662,26 @@ namespace PocketSharp
     /// <exception cref="PocketException"></exception>
     Task<bool> ReplaceTags(PocketItem item, string[] tags);
 
+    /// <summary>
+    /// Replaces all existing tags with the given tags in an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> ReplaceTags(CancellationToken cancellationToken, int itemID, string[] tags);
+
+    /// <summary>
+    /// Replaces all existing tags with the given new ones in an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="tags">The tags.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> ReplaceTags(CancellationToken cancellationToken, PocketItem item, string[] tags);
+
     /// <summary>
     /// Renames a tag in an item.
     /// </summary>
@@ -603,6 +701,28 @@ namespace PocketSharp
     /// <returns></returns>
     /// <exception cref="PocketException"></exception>
     Task<bool> RenameTag(PocketItem item, string oldTag, string newTag);
+
+    /// <summary>
+    /// Renames a tag in an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="itemID">The item ID.</param>
+    /// <param name="oldTag">The old tag.</param>
+    /// <param name="newTag">The new tag name.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> RenameTag(CancellationToken cancellationToken, int itemID, string oldTag, string newTag);
+
+    /// <summary>
+    /// Renames a tag in an item.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <param name="item">The item.</param>
+    /// <param name="oldTag">The old tag.</param>
+    /// <param name="newTag">The new tag name.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<bool> RenameTag(CancellationToken cancellationToken, PocketItem item, string oldTag, string newTag);
     #endregion
 
     #region statistics methods
@@ -616,10 +736,10 @@ namespace PocketSharp
     /// <summary>
     /// Statistics from the user account.
     /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
     /// <returns></returns>
     /// <exception cref="PocketException"></exception>
-    [Obsolete("Please use GetUserStatistics instead")]
-    Task<PocketStatistics> Statistics();
+    Task<PocketStatistics> GetUserStatistics(CancellationToken cancellationToken);
 
     /// <summary>
     /// Returns API usage statistics.
@@ -629,6 +749,16 @@ namespace PocketSharp
     /// <returns></returns>
     /// <exception cref="PocketException"></exception>
     Task<PocketLimits> GetUsageLimits();
+
+    /// <summary>
+    /// Returns API usage statistics.
+    /// If a request was made before, the data is returned synchronously from the cache.
+    /// Note: This method only works for authenticated users with a given AccessCode.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns></returns>
+    /// <exception cref="PocketException"></exception>
+    Task<PocketLimits> GetUsageLimits(CancellationToken cancellationToken);
     #endregion
   }
 }
\ No newline at end of file