Clarify file size limits and V2 requirements in docs

Updated XML documentation comments to specify that file sizes above 4GB require V2 protocol, and V2 requires Android 11 or above in most cases. Added remarks about 4 GiB cutoff due to 32-bit unsigned integer usage in file statistics. These clarifications affect device, sync service, and model classes, as well as issue templates.

Author: wherewhere

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -2,6 +2,7 @@ name: Bug report
 description: Create a report to help us improve
 title: Bug title
 labels: [bug]
+type: Bug
 body:
   - type: textarea
     validations:

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -2,6 +2,7 @@ name: Feature request
 description: Suggest an idea for this project
 title: Feature title
 labels: [enhancement]
+type: Feature
 body:
   - type: textarea
     validations:

AdvancedSharpAdbClient/DeviceCommands/DeviceExtensions.Async.cs

@@ -223,7 +223,7 @@ public static Task StopAppAsync(this IAdbClient client, DeviceData device, strin
         /// <param name="useV2"><see langword="true"/> to use <see cref="SyncCommand.RCV2"/> and <see cref="SyncCommand.STA2"/>; otherwise, <see langword="false"/> use <see cref="SyncCommand.RECV"/> and <see cref="SyncCommand.STAT"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task"/> which represents the asynchronous operation.</returns>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static async Task PullAsync(this IAdbClient client, DeviceData device,
             string remotePath, Stream stream,
             Action<SyncProgressChangedEventArgs>? callback = null,
@@ -265,6 +265,7 @@ public static async Task PushAsync(this IAdbClient client, DeviceData device,
         /// <param name="path">The path to the file.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task{FileStatistics}"/> which returns a <see cref="FileStatistics"/> object that contains information about the file.</returns>
+        /// <remarks>The file size will be cut off at 4 GiB due to the use of a 32-bit unsigned integer.</remarks>
         public static async Task<FileStatistics> StatAsync(this IAdbClient client, DeviceData device, string path, CancellationToken cancellationToken = default)
         {
             using ISyncService service = Factories.SyncServiceFactory(client, device);
@@ -294,6 +295,7 @@ public static async Task<FileStatisticsEx> StatExAsync(this IAdbClient client, D
         /// <param name="useV2"><see langword="true"/> to use <see cref="StatAsync(IAdbClient, DeviceData, string, CancellationToken)"/>; otherwise, use <see cref="StatExAsync"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task{IFileStatistics}"/> which returns a <see cref="IFileStatistics"/> object that contains information about the file.</returns>
+        /// <remarks>The file size will be cut off at 4 GiB due to the use of a 32-bit unsigned integer.</remarks>
         public static Task<IFileStatistics> StatAsync(this IAdbClient client, DeviceData device, string path, bool useV2, CancellationToken cancellationToken = default) =>
             useV2 ? client.StatExAsync(device, path, cancellationToken).ContinueWith(x => x.Result as IFileStatistics) : client.StatAsync(device, path, cancellationToken).ContinueWith(x => x.Result as IFileStatistics);
 
@@ -305,6 +307,7 @@ public static Task<IFileStatistics> StatAsync(this IAdbClient client, DeviceData
         /// <param name="remotePath">The path to the directory on the device.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task{List}"/> which returns for each child item of the directory, a <see cref="FileStatistics"/> object with information of the item.</returns>
+        /// <remarks>The file size will be cut off at 4 GiB due to the use of a 32-bit unsigned integer.</remarks>
         public static async Task<List<FileStatistics>> GetDirectoryListingAsync(this IAdbClient client, DeviceData device, string remotePath, CancellationToken cancellationToken = default)
         {
             using ISyncService service = Factories.SyncServiceFactory(client, device);
@@ -334,6 +337,7 @@ public static async Task<List<FileStatisticsEx>> GetDirectoryListingExAsync(this
         /// <param name="useV2"><see langword="true"/> to use <see cref="GetDirectoryListingAsync(IAdbClient, DeviceData, string, CancellationToken)"/>; otherwise, use <see cref="GetDirectoryListingExAsync"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task{IEnumerable}"/> which returns for each child item of the directory, a <see cref="IFileStatistics"/> object with information of the item.</returns>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static Task<IEnumerable<IFileStatistics>> GetDirectoryListingAsync(this IAdbClient client, DeviceData device, string remotePath, bool useV2, CancellationToken cancellationToken = default) =>
 #if NETFRAMEWORK && !NET40_OR_GREATER
             useV2 ? client.GetDirectoryListingExAsync(device, remotePath, cancellationToken).ContinueWith(x => x.Result.OfType<IFileStatistics>()) : client.GetDirectoryListingAsync(device, remotePath, cancellationToken).ContinueWith(x => x.Result.OfType<IFileStatistics>());
@@ -350,6 +354,7 @@ public static Task<IEnumerable<IFileStatistics>> GetDirectoryListingAsync(this I
         /// <param name="remotePath">The path to the directory on the device.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>An <see cref="IAsyncEnumerable{FileStatistics}"/> which returns for each child item of the directory, a <see cref="FileStatistics"/> object with information of the item.</returns>
+        /// <remarks>The file size will be cut off at 4 GiB due to the use of a 32-bit unsigned integer.</remarks>
         public static async IAsyncEnumerable<FileStatistics> GetDirectoryAsyncListing(this IAdbClient client, DeviceData device, string remotePath, [EnumeratorCancellation] CancellationToken cancellationToken = default)
         {
             using ISyncService service = Factories.SyncServiceFactory(client, device);
@@ -385,6 +390,7 @@ public static async IAsyncEnumerable<FileStatisticsEx> GetDirectoryAsyncListingE
         /// <param name="useV2"><see langword="true"/> to use <see cref="GetDirectoryListingAsync(IAdbClient, DeviceData, string, CancellationToken)"/>; otherwise, use <see cref="GetDirectoryListingExAsync"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>An <see cref="IAsyncEnumerable{IFileStatistics}"/> which returns for each child item of the directory, a <see cref="IFileStatistics"/> object with information of the item.</returns>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static IAsyncEnumerable<IFileStatistics> GetDirectoryAsyncListing(this IAdbClient client, DeviceData device, string remotePath, bool useV2, CancellationToken cancellationToken = default) =>
             useV2 ? client.GetDirectoryAsyncListingEx(device, remotePath, cancellationToken) : client.GetDirectoryAsyncListing(device, remotePath, cancellationToken);
 #endif
@@ -497,7 +503,7 @@ public static Task InstallMultiplePackageAsync(this IAdbClient client, DeviceDat
         /// <param name="useV2"><see langword="true"/> to use <see cref="SyncCommand.RCV2"/> and <see cref="SyncCommand.STA2"/>; otherwise, <see langword="false"/> use <see cref="SyncCommand.RECV"/> and <see cref="SyncCommand.STAT"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task"/> which represents the asynchronous operation.</returns>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static async Task PullAsync(this IAdbClient client, DeviceData device,
             string remotePath, Stream stream,
             IProgress<SyncProgressChangedEventArgs>? progress,

AdvancedSharpAdbClient/DeviceCommands/DeviceExtensions.cs

@@ -183,7 +183,7 @@ public static void StopApp(this IAdbClient client, DeviceData device, string pac
         /// <param name="callback">An optional parameter which, when specified, returns progress notifications. The progress is reported as a value between 0 and 100, representing the percentage of the file which has been transferred.</param>
         /// <param name="useV2"><see langword="true"/> to use <see cref="SyncCommand.RCV2"/> and <see cref="SyncCommand.STA2"/>; otherwise, <see langword="false"/> use <see cref="SyncCommand.RECV"/> and <see cref="SyncCommand.STAT"/>.</param>
         /// <param name="isCancelled">A <see cref="bool"/> that can be used to cancel the task.</param>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static void Pull(this IAdbClient client, DeviceData device,
             string remotePath, Stream stream,
             Action<SyncProgressChangedEventArgs>? callback = null,
@@ -224,6 +224,7 @@ public static void Push(this IAdbClient client, DeviceData device,
         /// <param name="device">The device on which to look for the file.</param>
         /// <param name="path">The path to the file.</param>
         /// <returns>A <see cref="FileStatistics"/> object that represents the file.</returns>
+        /// <remarks>The file size will be cut off at 4 GiB due to the use of a 32-bit unsigned integer.</remarks>
         public static FileStatistics Stat(this IAdbClient client, DeviceData device, string path)
         {
             using ISyncService service = Factories.SyncServiceFactory(client, device);
@@ -252,7 +253,7 @@ public static FileStatisticsEx StatEx(this IAdbClient client, DeviceData device,
         /// <param name="path">The path to the file.</param>
         /// <param name="useV2"><see langword="true"/> to use <see cref="Stat(IAdbClient, DeviceData, string)"/>; otherwise, use <see cref="StatEx"/>.</param>
         /// <returns>A <see cref="IFileStatistics"/> object that represents the file.</returns>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 8 or above.</remarks>
         public static IFileStatistics Stat(this IAdbClient client, DeviceData device, string path, bool useV2) =>
             useV2 ? client.StatEx(device, path) : client.Stat(device, path);
 
@@ -403,7 +404,7 @@ public static void InstallMultiplePackage(this IAdbClient client, DeviceData dev
         /// <param name="progress">An optional parameter which, when specified, returns progress notifications. The progress is reported as a value between 0 and 100, representing the percentage of the file which has been transferred.</param>
         /// <param name="useV2"><see langword="true"/> to use <see cref="SyncCommand.RCV2"/> and <see cref="SyncCommand.STA2"/>; otherwise, <see langword="false"/> use <see cref="SyncCommand.RECV"/> and <see cref="SyncCommand.STAT"/>.</param>
         /// <param name="isCancelled">A <see cref="bool"/> that can be used to cancel the task.</param>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static void Pull(this IAdbClient client, DeviceData device,
             string remotePath, Stream stream,
             IProgress<SyncProgressChangedEventArgs>? progress = null,

AdvancedSharpAdbClient/Extensions/SyncServiceExtensions.Async.cs

@@ -21,7 +21,7 @@ public static partial class SyncServiceExtensions
         /// <param name="useV2"><see langword="true"/> to use <see cref="ISyncService.StatAsync"/>; otherwise, use <see cref="ISyncService.StatExAsync"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task{IFileStatistics}"/> which returns a <see cref="IFileStatistics"/> object that contains information about the file.</returns>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 8 or above.</remarks>
         public static Task<IFileStatistics> StatAsync(this ISyncService service, string remotePath, bool useV2 = false, CancellationToken cancellationToken = default) =>
             useV2 ? service.StatExAsync(remotePath, cancellationToken).ContinueWith(x => x.Result as IFileStatistics) : service.StatAsync(remotePath, cancellationToken).ContinueWith(x => x.Result as IFileStatistics);
 
@@ -33,6 +33,7 @@ public static Task<IFileStatistics> StatAsync(this ISyncService service, string
         /// <param name="useV2"><see langword="true"/> to use <see cref="ISyncService.GetDirectoryListingAsync"/>; otherwise, use <see cref="ISyncService.GetDirectoryListingExAsync"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task{IEnumerable}"/> which returns for each child item of the directory, a <see cref="IFileStatistics"/> object with information of the item.</returns>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static Task<IEnumerable<IFileStatistics>> GetDirectoryListingAsync(this ISyncService service, string remotePath, bool useV2 = false, CancellationToken cancellationToken = default) =>
 #if NETFRAMEWORK && !NET40_OR_GREATER
             useV2 ? service.GetDirectoryListingExAsync(remotePath, cancellationToken).ContinueWith(x => x.Result.OfType<IFileStatistics>()) : service.GetDirectoryListingAsync(remotePath, cancellationToken).ContinueWith(x => x.Result.OfType<IFileStatistics>());
@@ -49,6 +50,7 @@ public static Task<IEnumerable<IFileStatistics>> GetDirectoryListingAsync(this I
         /// <param name="useV2"><see langword="true"/> to use <see cref="ISyncService.GetDirectoryListingAsync"/>; otherwise, use <see cref="ISyncService.GetDirectoryListingExAsync"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>An <see cref="IAsyncEnumerable{IFileStatistics}"/> which returns for each child item of the directory, a <see cref="FileStatistics"/> object with information of the item.</returns>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static IAsyncEnumerable<IFileStatistics> GetDirectoryAsyncListing(this ISyncService service, string remotePath, bool useV2 = false, CancellationToken cancellationToken = default) =>
             useV2 ? service.GetDirectoryAsyncListingEx(remotePath, cancellationToken) : service.GetDirectoryAsyncListing(remotePath, cancellationToken);
 #endif
@@ -79,7 +81,7 @@ public static Task PushAsync(this ISyncService service, Stream stream, string re
         /// <param name="useV2"><see langword="true"/> to use <see cref="SyncCommand.RCV2"/> and <see cref="SyncCommand.STA2"/>; otherwise, <see langword="false"/> use <see cref="SyncCommand.RECV"/> and <see cref="SyncCommand.STAT"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task"/> which represents the asynchronous operation.</returns>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static Task PullAsync(this ISyncService service, string remotePath, Stream stream, IProgress<SyncProgressChangedEventArgs>? progress = null, bool useV2 = false, CancellationToken cancellationToken = default) =>
             service.PullAsync(remotePath, stream, progress.AsAction(), useV2, cancellationToken);
 
@@ -109,7 +111,7 @@ public static Task PushAsync(this ISyncService.IWinRT service, IInputStream stre
         /// <param name="useV2"><see langword="true"/> to use <see cref="SyncCommand.RCV2"/> and <see cref="SyncCommand.STA2"/>; otherwise, <see langword="false"/> use <see cref="SyncCommand.RECV"/> and <see cref="SyncCommand.STAT"/>.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> that can be used to cancel the task.</param>
         /// <returns>A <see cref="Task"/> which represents the asynchronous operation.</returns>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static Task PullAsync(this ISyncService.IWinRT service, string remotePath, IOutputStream stream, IProgress<SyncProgressChangedEventArgs>? progress = null, bool useV2 = false, CancellationToken cancellationToken = default) =>
             service.PullAsync(remotePath, stream, progress.AsAction(), useV2, cancellationToken);
 #endif

AdvancedSharpAdbClient/Extensions/SyncServiceExtensions.cs

@@ -21,7 +21,7 @@ public static partial class SyncServiceExtensions
         /// <param name="remotePath">The path of the file on the device.</param>
         /// <param name="useV2"><see langword="true"/> to use <see cref="ISyncService.Stat"/>; otherwise, use <see cref="ISyncService.StatEx"/>.</param>
         /// <returns>A <see cref="IFileStatistics"/> object that contains information about the file.</returns>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 8 or above.</remarks>
         public static IFileStatistics Stat(this ISyncService service, string remotePath, bool useV2 = false) =>
             useV2 ? service.StatEx(remotePath) : service.Stat(remotePath);
 
@@ -65,7 +65,7 @@ public static void Push(this ISyncService service, Stream stream, string remoteP
         /// <param name="progress">An optional parameter which, when specified, returns progress notifications. The progress is reported as <see cref="SyncProgressChangedEventArgs"/>, representing the state of the file which has been transferred.</param>
         /// <param name="useV2"><see langword="true"/> to use <see cref="SyncCommand.RCV2"/> and <see cref="SyncCommand.STA2"/>; otherwise, <see langword="false"/> use <see cref="SyncCommand.RECV"/> and <see cref="SyncCommand.STAT"/>.</param>
         /// <param name="isCancelled">A <see cref="bool"/> that can be used to cancel the task.</param>
-        /// <remarks>V2 need Android 8 or above.</remarks>
+        /// <remarks>File size bigger than 4GB need V2, and V2 need Android 11 or above.</remarks>
         public static void Pull(this ISyncService service, string remotePath, Stream stream, IProgress<SyncProgressChangedEventArgs>? progress = null, bool useV2 = false, in bool isCancelled = false) =>
             service.Pull(remotePath, stream, progress.AsAction(), useV2, isCancelled);