Merge pull request #151 from box/support-content-md5-for-file-upload

Support content md5 for file upload

Author: cburnette

Box.V2.Test/app.config

@@ -82,6 +82,7 @@
     <Compile Include="Models\Permissions\BoxItemPermission.cs" />
     <Compile Include="Models\BoxSortOrder.cs" />
     <Compile Include="Models\Request\BoxMetadataFilterRequest.cs" />
+    <Compile Include="Models\Request\BoxPreflightCheckRequest.cs" />
     <Compile Include="Models\Request\BoxRetentionPolicyAssignmentRequest.cs" />
     <Compile Include="Models\Request\BoxRetentionPolicyRequest.cs" />
     <Compile Include="Models\Request\BoxUserInviteRequest.cs" />

Box.V2/Box.V2.csproj

@@ -2,7 +2,7 @@
 <package >
   <metadata>
     <id>Box.V2</id>
-    <version>2.9.0</version>
+    <version>2.10.0</version>
     <title>Box Windows SDK V2</title>
     <authors>Box, Inc.</authors>
     <owners>Box, Inc.</owners>

Box.V2/Box.V2.nuspec

@@ -7,7 +7,7 @@ namespace Box.V2.Config
 {
     public class BoxConfig : IBoxConfig
     {
-        private const string DefaultUserAgent = "Box Windows SDK v2.7.0";
+        private const string DefaultUserAgent = "Box Windows SDK v2.10.0";
 
         /// <summary>
         /// Instantiates a Box config with all of the standard defaults
@@ -74,7 +74,9 @@ public BoxConfig(string clientId, string clientSecret, string enterpriseId,
         public virtual Uri FoldersEndpointUri { get { return new Uri(BoxApiUri, Constants.FoldersString); } }
         public virtual Uri FilesEndpointUri { get { return new Uri(BoxApiUri, Constants.FilesString); } }
         public virtual Uri FilesUploadEndpointUri { get { return new Uri(BoxUploadApiUri, Constants.FilesUploadString); } }
-        public virtual Uri FilesNewVersionEndpointUri { get { return new Uri(BoxUploadApiUri, Constants.FilesNewVersionString); } }
+        //public virtual Uri FilesNewVersionEndpointUri { get { return new Uri(BoxUploadApiUri, Constants.FilesNewVersionString); } }
+        public virtual Uri FilesPreflightCheckUri { get { return new Uri(BoxApiUri, Constants.FilesUploadString); } }
+        //public virtual Uri FilesPreflightCheckNewVersionUri { get { return new Uri(BoxApiUri, Constants.FilesNewVersionString); } }
         public virtual Uri CommentsEndpointUri { get { return new Uri(BoxApiUri, Constants.CommentsString); } }
         public virtual Uri SearchEndpointUri { get { return new Uri(BoxApiUri, Constants.SearchString); } }
         public virtual Uri UserEndpointUri { get { return new Uri(BoxApiUri, Constants.UserString); } }

Box.V2/Config/BoxConfig.cs

@@ -42,6 +42,7 @@ public static class Constants
         public const string FilesEndpointString = BoxApiUriString + FilesString;
         public const string FilesUploadEndpointString = BoxUploadApiUriString + FilesUploadString;
         public const string FilesNewVersionEndpointString = BoxUploadApiUriString + FilesNewVersionString;
+        public const string FilesPreflightCheckNewVersionString = BoxApiUriString + FilesNewVersionString;
         public const string CommentsEndpointString = BoxApiUriString + CommentsString;
         public const string SearchEndpointString = BoxApiUriString + SearchString;
         public const string UserEndpointString = BoxApiUriString + UserString;
@@ -116,6 +117,8 @@ public static class RequestParameters
 
             public const string AsUser = "As-User";
 
+            public const string ContentMD5 = "Content-MD5";
+
             /*** Values ***/
             public const string RefreshToken = "refresh_token";
             public const string AuthorizationCode = "authorization_code";

Box.V2/Config/Constants.cs

@@ -35,6 +35,8 @@ public interface IBoxConfig
         Uri FoldersEndpointUri { get; }
         Uri FilesEndpointUri { get; }
         Uri FilesUploadEndpointUri { get; }
+        Uri FilesPreflightCheckUri { get; }
+        //Uri FilesPreflightCheckNewVersionUri { get; }
         Uri CommentsEndpointUri { get; }
         Uri SearchEndpointUri { get; }
         Uri UserEndpointUri { get; }

Box.V2/Config/IBoxConfig.cs

@@ -10,6 +10,7 @@
 using System.Linq;
 using System.Net;
 using System.Net.Http.Headers;
+using System.Text;
 using System.Threading.Tasks;
 
 namespace Box.V2.Managers
@@ -81,6 +82,47 @@ public async Task<Uri> GetDownloadUriAsync(string id, string versionId = null)
             return locationUri;
         }
 
+        /// <summary>
+        /// Verify that a file will be accepted by Box before you send all the bytes over the wire.
+        /// </summary>
+        /// <param name="preflightCheckRequest"></param>
+        /// <returns></returns>
+        public async Task PreflightCheck(BoxPreflightCheckRequest preflightCheckRequest)
+        {
+            preflightCheckRequest.ThrowIfNull("preflightCheckRequest")
+                .Name.ThrowIfNullOrWhiteSpace("preflightCheckRequest.Name");
+            preflightCheckRequest.Parent.ThrowIfNull("preflightCheckRequest.Parent")
+                .Id.ThrowIfNullOrWhiteSpace("preflightCheckRequest.Parent.Id");
+
+            BoxRequest request = new BoxRequest(_config.FilesPreflightCheckUri)
+                .Method(RequestMethod.Options);
+
+            request.Payload = _converter.Serialize(preflightCheckRequest);
+            request.ContentType = Constants.RequestParameters.ContentTypeJson;
+
+            IBoxResponse<BoxEntity> response = await ToResponseAsync<BoxEntity>(request).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Verify that a new version of a file will be accepted by Box before you send all the bytes over the wire.
+        /// </summary>
+        /// <param name="fileId"></param>
+        /// <param name="preflightCheckRequest"></param>
+        /// <returns></returns>
+        public async Task PreflightCheckNewVersion(string fileId, BoxPreflightCheckRequest preflightCheckRequest)
+        {
+            if (preflightCheckRequest.Size <= 0)
+                throw new ArgumentException("Size in bytes must be greater than zero (otherwise preflight check for new version would always succeed)", "sizeinBytes");
+            
+            BoxRequest request = new BoxRequest(new Uri(string.Format(Constants.FilesPreflightCheckNewVersionString, fileId)))
+                .Method(RequestMethod.Options);
+
+            request.Payload = _converter.Serialize(preflightCheckRequest);
+            request.ContentType = Constants.RequestParameters.ContentTypeJson;
+
+            IBoxResponse<BoxEntity> response = await ToResponseAsync<BoxEntity>(request).ConfigureAwait(false);
+        }
+
         /// <summary>
         /// Uploads a provided file to the target parent folder 
         /// If the file already exists, an error will be thrown.
@@ -90,15 +132,20 @@ public async Task<Uri> GetDownloadUriAsync(string id, string versionId = null)
         /// <param name="stream"></param>
         /// <param name="fields"></param>
         /// <param name="timeout"></param>
+        /// <param name="contentMD5"></param>
+        /// <param name="setStreamPositionToZero"></param>
         /// <returns></returns>
-        public async Task<BoxFile> UploadAsync(BoxFileRequest fileRequest, Stream stream, List<string> fields = null, TimeSpan? timeout = null)
+        public async Task<BoxFile> UploadAsync(BoxFileRequest fileRequest, Stream stream, List<string> fields = null, TimeSpan? timeout = null, byte[] contentMD5 = null, bool setStreamPositionToZero = true)
         {
             stream.ThrowIfNull("stream");
             fileRequest.ThrowIfNull("fileRequest")
                 .Name.ThrowIfNullOrWhiteSpace("filedRequest.Name");
             fileRequest.Parent.ThrowIfNull("fileRequest.Parent")
                 .Id.ThrowIfNullOrWhiteSpace("fileRequest.Parent.Id");
 
+            if (setStreamPositionToZero)
+                stream.Position = 0;
+
             BoxMultiPartRequest request = new BoxMultiPartRequest(_config.FilesUploadEndpointUri) { Timeout = timeout }
                 .Param(ParamFields, fields)
                 .FormPart(new BoxStringFormPart()
@@ -113,6 +160,9 @@ public async Task<BoxFile> UploadAsync(BoxFileRequest fileRequest, Stream stream
                     FileName = fileRequest.Name
                 });
 
+            if (contentMD5 != null)
+                request.Header(Constants.RequestParameters.ContentMD5, HexStringFromBytes(contentMD5));
+
             IBoxResponse<BoxCollection<BoxFile>> response = await ToResponseAsync<BoxCollection<BoxFile>>(request).ConfigureAwait(false);
 
             // We can only upload one file at a time, so return the first entry
@@ -126,15 +176,22 @@ public async Task<BoxFile> UploadAsync(BoxFileRequest fileRequest, Stream stream
         /// A proper timeout should be provided for large uploads
         /// </summary>
         /// <param name="fileName"></param>
+        /// <param name="fileId"
         /// <param name="stream"></param>
         /// <param name="etag"></param>
+        /// <param name="fields"></param>
         /// <param name="timeout"></param>
+        /// <param name="contentMD5"></param>
+        /// <param name="setStreamPositionToZero"></param>
         /// <returns></returns>
-        public async Task<BoxFile> UploadNewVersionAsync(string fileName, string fileId, Stream stream, string etag = null, List<string> fields = null, TimeSpan? timeout = null)
+        public async Task<BoxFile> UploadNewVersionAsync(string fileName, string fileId, Stream stream, string etag = null, List<string> fields = null, TimeSpan? timeout = null, byte[] contentMD5 = null, bool setStreamPositionToZero = true)
         {
             stream.ThrowIfNull("stream");
             fileName.ThrowIfNullOrWhiteSpace("fileName");
 
+            if (setStreamPositionToZero)
+                stream.Position = 0;
+
             BoxMultiPartRequest request = new BoxMultiPartRequest(new Uri(string.Format(Constants.FilesNewVersionEndpointString, fileId))) { Timeout = timeout }
                 .Header("If-Match", etag)
                 .Param(ParamFields, fields)
@@ -145,12 +202,26 @@ public async Task<BoxFile> UploadNewVersionAsync(string fileName, string fileId,
                     FileName = fileName
                 });
 
+            if (contentMD5 != null)
+                request.Header(Constants.RequestParameters.ContentMD5, HexStringFromBytes(contentMD5));
+
             IBoxResponse<BoxCollection<BoxFile>> response = await ToResponseAsync<BoxCollection<BoxFile>>(request).ConfigureAwait(false);
 
             // We can only upload one file at a time, so return the first entry
             return response.ResponseObject.Entries.FirstOrDefault();
         }
 
+        private string HexStringFromBytes(byte[] bytes)
+        {
+            var sb = new StringBuilder();
+            foreach (byte b in bytes)
+            {
+                var hex = b.ToString("x2");
+                sb.Append(hex);
+            }
+            return sb.ToString();
+        }
+
         /// <summary>
         /// If there are previous versions of this file, this method can be used to retrieve metadata about the older versions.
         /// <remarks>Versions are only tracked for Box users with premium accounts.</remarks>

Box.V2/Managers/BoxFilesManager.cs

@@ -0,0 +1,20 @@
+using Newtonsoft.Json;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+namespace Box.V2.Models
+{
+    /// <summary>
+    /// A request class for making preflight check requests
+    /// </summary>
+    public class BoxPreflightCheckRequest : BoxItemRequest
+    {
+        /// <summary>
+        /// The size of the file in bytes. Specify 0 for unknown file-sizes
+        /// </summary>
+        [JsonProperty(PropertyName = "size")]
+        public long Size { get; set; }
+    }
+}

Box.V2/Models/Request/BoxPreflightCheckRequest.cs

@@ -1,4 +1,5 @@
-using System;
+using Box.V2.Config;
+using System;
 using System.Diagnostics;
 using System.IO;
 using System.Linq;
@@ -24,7 +25,16 @@ public async Task<IBoxResponse<T>> ExecuteAsync<T>(IBoxRequest request)
 
             // Add headers
             foreach (var kvp in request.HttpHeaders)
-                httpRequest.Headers.TryAddWithoutValidation(kvp.Key, kvp.Value);
+            {
+                if (kvp.Key == Constants.RequestParameters.ContentMD5)
+                {
+                    httpRequest.Content.Headers.Add(kvp.Key, kvp.Value);
+                } else
+                {
+                    httpRequest.Headers.TryAddWithoutValidation(kvp.Key, kvp.Value);
+                }       
+            }
+                
 
             // If we are retrieving a stream, we should return without reading the entire response
             HttpCompletionOption completionOption = isStream ?

Box.V2/Request/HttpRequestHandler.cs

@@ -120,16 +120,73 @@ BoxFileRequest request = new BoxFileRequest()
 BoxFile f = await client.FilesManager.UpdateInformationAsync(request );
 ```
 
-
 #### Upload a New File
 ```c#
+BoxFile newFile;
+
 // Create request object with name and parent folder the file should be uploaded to
-BoxFileRequest req = new BoxFileRequest()
+using (FileStream stream = new FileStream(@"C:\\example.pdf", FileMode.Open))
 {
-	Name = "NewFile",
-	Parent = new BoxRequestEntity() { Id = "0" }
-};
-BoxFile f = await client.FilesManager.UploadAsync(request, stream);
+	BoxFileRequest req = new BoxFileRequest()
+	{
+		Name = "example.pdf",
+		Parent = new BoxRequestEntity() { Id = "0" }
+	};
+	newFile = await client.FilesManager.UploadAsync(req, stream);
+}
+```
+
+#### Upload a New File with Content MD5 hash
+```c#
+BoxFile newFile;
+
+// Create request object with name and parent folder the file should be uploaded to
+using (FileStream stream = new FileStream(@"C:\\example.pdf", FileMode.Open))
+using (SHA1 sha1 = SHA1.Create())
+{
+	BoxFileRequest req = new BoxFileRequest()
+	{
+		Name = "example.pdf",
+		Parent = new BoxRequestEntity() { Id = "0" }
+	};
+	
+	byte[] md5Bytes = sha1.ComputeHash(fs);
+	
+	newFile = await client.FilesManager.UploadAsync(req, stream, contentMD5: md5Bytes);
+}
+```
+
+#### Perform Preflight Check for a new file upload
+```c#
+try
+{
+	var req = new BoxPreflightCheckRequest() { Name = "example.pdf", 
+											   Parent = new BoxRequestEntity() { Id = "0" },
+											   Size = 10000 //set the size if known, otherwise don't set (i.e. for a stream)
+											 };
+											 
+	//exception will be thrown if name collision or storage limit would be exceeded by upload									 
+	await userClient.FilesManager.PreflightCheck(req);
+}
+catch (BoxException bex)
+{
+	//Handle error
+}
+```
+
+#### Perform Preflight Check for a new version of file
+```c#
+try
+{
+	var req = new BoxPreflightCheckRequest() { Size=10926 };
+	
+	//exception will be thrown if storage limit would be exceeded by uploading new version of file
+    await userClient.FilesManager.PreflightCheckNewVersion(existingFile.Id, req);									 
+}
+catch (BoxException bex)
+{
+	//Handle error
+}
 ```
 
 #### Download a File