cancellationToken for ALL methods - completed; remove obsolete methods in preparation for v3

2013-11-08 01:44:32 +01:00
parent 10e9575303
commit bf5d8a50ce
3 changed files with 345 additions and 27 deletions
@@ -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);
    }
  }
 }
@@ -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()
@@ -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
  }
 }