StorageReference.cs

/*
 * Copyright 2017 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

usingSystem;
usingSystem.IO;
usingSystem.Runtime.InteropServices;
usingSystem.Threading;
usingSystem.Threading.Tasks;
usingFirebase.Storage.Internal;

namespaceFirebase.Storage{
/// <summary>Represents a reference to a Google Cloud Storage object.</summary>
/// <remarks>
/// Represents a reference to a Google Cloud Storage object. Developers can upload and download
/// objects, get/set object metadata, and delete an object at a specified path.
/// (see <a href="https://cloud.google.com/storage/">Google Cloud Storage</a>)
/// </remarks>
publicsealedclassStorageReference{

/// <summary>
/// Extracts the cancellation status and exception from a task generated by a
/// firebase::Future.
/// </summary>
privateclassTaskCompletionStatus{

/// <summary>
/// true if the task completed successfully.
/// </summary>
publicboolIsSuccessful{get;privateset;}

/// <summary>
/// true if the task was canceled.
/// </summary>
publicboolIsCanceled{get;privateset;}

/// <summary>
/// Non-null if the task failed.
/// </summary>
publicSystem.ExceptionException{get;privateset;}

/// <summary>
/// Extract the completion status from the specified task.
/// </summary>
/// <param name="task">Task to extract completion status from.</param>
/// <param name="operationDescription">Description of the operation performed by the
/// task used to log task status.</param>
/// <param name="logger">Used to log task completion status.</param>
publicTaskCompletionStatus(Tasktask,stringoperationDescription,ModuleLoggerlogger){
if(task.IsCompleted&&!task.IsFaulted&&!task.IsCanceled){
IsSuccessful=true;
logger.LogMessage(LogLevel.Debug,String.Format("{0} completed successfully.",
operationDescription));
return;
}
StorageExceptionstorageException=
task.IsFaulted?StorageException.CreateFromException(task.Exception):null;
// When an operation is canceled a C++ future will complete with a cancellation error code
// so cancel the task when the cancelation error code is detected.
if(task.IsCanceled||(storageException!=null&&
storageException.ErrorCode==StorageException.ErrorCanceled)){
logger.LogMessage(LogLevel.Debug,String.Format("{0} canceled.",operationDescription));
IsCanceled=true;
return;
}

Exception=storageException;
if(Exception!=null){
logger.LogMessage(LogLevel.Debug,String.Format("{0} failed {1}.",operationDescription,
Exception.Message));
return;
}
logger.LogMessage(LogLevel.Debug,String.Format("{0} failed due to an unknown error.",
operationDescription));
Exception=newInvalidOperationException(String.Format("{0} failed.",
operationDescription));
}

/// <summary>
/// Create a task from this object's status.
/// </summary>
/// <returns>A completed Task from this object's status.</returns>
publicTaskToTask(){
vartaskCompletionSource=newTaskCompletionSource<bool>();
if(IsSuccessful){
taskCompletionSource.SetResult(true);
}elseif(IsCanceled){
// Emulates Task.FromCanceled in .NET 4.5.
taskCompletionSource.SetCanceled();
}else{
// Emulates Task.FromException in .NET 4.5.
taskCompletionSource.SetException(this.Exception);
}
returntaskCompletionSource.Task;
}
}

// Storage object this reference was created from.
privatereadonlyFirebaseStoragefirebaseStorage;

/// <summary>
/// Construct a wrapper around the StorageReferenceInternal object.
/// </summary>
internalStorageReference(FirebaseStoragestorage,
StorageReferenceInternalstorageReferenceInternal){
firebaseStorage=storage;
Internal=storageReferenceInternal;
Logger=newModuleLogger(parentLogger:firebaseStorage.Logger){
Tag=String.Format("StorageReference {0}",ToString())
};
}

/// <summary>
/// Logger for this reference.
/// </summary>
// Logger for this reference.
internalModuleLoggerLogger{get;privateset;}

/// <summary>
/// Returns a new instance of
/// <see cref="StorageReference" />
/// pointing to the parent location or null
/// if this instance references the root location.
/// For example:
/// <pre>
/// <c>
/// path = foo/bar/baz parent = foo/bar
/// path = foo parent = (root)
/// path = (root) parent = (null)
/// </c>
/// </pre>
/// </summary>
/// <returns>
/// the parent
/// <see cref="StorageReference" />
/// .
/// </returns>
publicStorageReferenceParent{
get{returnnewStorageReference(firebaseStorage,Internal.GetParent());}
}

/// <summary>
/// Returns a new instance of
/// <see cref="StorageReference" />
/// pointing to the root location.
/// </summary>
/// <returns>
/// the root
/// <see cref="StorageReference" />
/// .
/// </returns>
publicStorageReferenceRoot{get{returnfirebaseStorage.RootReference;}}

/// <summary>Returns the short name of this object.</summary>
/// <returns>the name.</returns>
publicstringName{get{returnInternal.Name;}}

/// <summary>
/// Returns the full path to this object, not including the Google Cloud Storage bucket.
/// </summary>
/// <returns>the path.</returns>
publicstringPath{get{returnInternal.FullPath;}}

/// <summary>Return the Google Cloud Storage bucket that holds this object.</summary>
/// <returns>the bucket.</returns>
publicstringBucket{get{returnInternal.Bucket;}}

/// <summary>
/// Returns the
/// <see cref="FirebaseStorage" />
/// service which created this reference.
/// </summary>
/// <returns>
/// The
/// <see cref="FirebaseStorage" />
/// service.
/// </returns>
publicFirebaseStorageStorage{get{returnfirebaseStorage;}}

/// <summary>
/// Returns a new instance of
/// <see cref="StorageReference" />
/// pointing to a child location of the current
/// reference. All leading and trailing slashes will be removed, and consecutive slashes will
/// be compressed to single slashes. For example:
/// <pre>
/// <c>
/// child = /foo/bar path = foo/bar
/// child = foo/bar/ path = foo/bar
/// child = foo///bar path = foo/bar
/// </c>
/// </pre>
/// </summary>
/// <param name="pathString">The relative path from this reference.</param>
/// <returns>
/// the child
/// <see cref="StorageReference" />
/// .
/// </returns>
publicStorageReferenceChild(stringpathString){
returnnewStorageReference(firebaseStorage,Internal.Child(pathString));
}

/// <summary>
/// Uploads byte data to this
/// <see cref="StorageReference" />
/// .
/// This is not recommended for large files. Instead upload a file via
/// <see>
/// <cref>PutFile</cref>
/// </see>
/// or a Stream via
/// <see>
/// <cref>PutStream</cref>
/// </see>
/// .
/// </summary>
/// <param name="bytes">The byte[] to upload.</param>
/// <param name="customMetadata">
/// <see cref="MetadataChange" />
/// containing additional information (MIME type, etc.)
/// about the object being uploaded.
/// </param>
/// <param name="progressHandler">
/// usually an instance of <see cref="StorageProgress"/> that will
/// receive periodic updates during the operation. This value can
/// be null.</param>
/// <param name="cancelToken">A CancellationToken to control the operation
/// and possibly later cancel it. This value may be CancellationToken.None
/// to indicate no value.</param>
/// <param name="previousSessionUri">A Uri previously obtained by
/// <see cref="UploadState.UploadSessionUri"/> that can be used to resume
/// a previously interrupted upload.</param>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the upload.
/// </returns>
publicTask<StorageMetadata>PutBytesAsync(
byte[]bytes,
MetadataChangecustomMetadata=null,
IProgress<UploadState>progressHandler=null,
CancellationTokencancelToken=default(CancellationToken),
UripreviousSessionUri=null){
returnPutBytesUsingCompletionSourceAsync(bytes,customMetadata,progressHandler,cancelToken,
previousSessionUri,
newTaskCompletionSource<StorageMetadata>());
}

/// <summary>
/// Call Internal.PutBytesUsingMonitorControllerAsync while maintaining a reference to
// monitorController and metadata until the operation is complete.
/// </summary>
/// <param name="buffer">Address of pinned buffer to upload.</param>
/// <param name="bufferSize">Size of buffer in bytes.</param>
/// <param name="metadata">Metadata to upload or null to use defaults.</param>
/// <param name="monitorController">Object that can be used to monitor and control the
/// transfer.</param>
/// <param name="cancellationToken">Token which can be used to cancel the upload.</param>
/// <returns>Task that indicates when the upload is complete.
/// NOTE: This task is the object constructed from firebase::Future.</returns>
privateTask<MetadataInternal>PutBytesUsingMonitorControllerAsync(
IntPtrbuffer,uintbufferSize,MetadataInternalmetadata,
MonitorControllerInternalmonitorController,CancellationTokencancellationToken){
vartask=Internal.PutBytesUsingMonitorControllerAsync(buffer,bufferSize,metadata,
monitorController);
monitorController.RegisterCancellationToken(cancellationToken);
returntask.ContinueWith((completedTask)=>{
monitorController.Dispose();
if(metadata!=null)metadata.Dispose();
returncompletedTask;
}).Unwrap();
}

/// <summary>
/// Uploads an array of bytes signally the specified completion source when complete.
/// </summary>
/// <param name="bytes">Array of bytes to upload.</param>
/// <param name="customMetadata">Metadata to upload.</param>
/// <param name="progressHandler">Handler to report progress to.</param>
/// <param name="cancelToken">Token used to signal task cancellation.</param>
/// <param name="previousSessionUri">URL used to resume upload.</param>
/// <param name="completionSource">Completion source that is signalled when the operation is
/// complete.</param>
/// <returns>Task that indicates when the upload is complete.</returns>
privateTask<StorageMetadata>PutBytesUsingCompletionSourceAsync(
byte[]bytes,
MetadataChangecustomMetadata,
IProgress<UploadState>progressHandler,
CancellationTokencancelToken,
UripreviousSessionUri,
TaskCompletionSource<StorageMetadata>completionSource){
varuploadState=newUploadState(this,bytes.Length);
vartransferStateUpdater=newTransferStateUpdater<UploadState>(
this,progressHandler,uploadState,uploadState.State);
// TODO(smiles): Add support for resumable uploads when b/68320317 is resolved.
varbytesHandle=GCHandle.Alloc(bytes,GCHandleType.Pinned);
PutBytesUsingMonitorControllerAsync(
bytesHandle.AddrOfPinnedObject(),(uint)bytes.Length,
StorageMetadata.BuildMetadataInternal(customMetadata),
transferStateUpdater.MonitorController,cancelToken)
.ContinueWith(task =>{
bytesHandle.Free();
CompleteTask(task,completionSource,
()=>{
varmetadata=newStorageMetadata(this,task.Result);
transferStateUpdater.SetMetadata(metadata);
returnmetadata;
},"PutBytes");
});
returncompletionSource.Task;
}

/// <summary>
/// Call Internal.PutFileUsingMonitorControllerAsync while maintaining a reference to
// monitorController and metadata until the operation is complete.
/// </summary>
/// <param name="path">Path (URI string) of the file to upload.</param>
/// <param name="metadata">Metadata to upload or null to use defaults.</param>
/// <param name="monitorController">Object that can be used to monitor and control the
/// transfer.</param>
/// <param name="cancellationToken">Token which can be used to cancel the upload.</param>
/// <returns>Task that indicates when the upload is complete.
/// NOTE: This task is the object constructed from firebase::Future.</returns>
internalTask<MetadataInternal>PutFileUsingMonitorControllerAsync(
stringpath,MetadataInternalmetadata,MonitorControllerInternalmonitorController,
CancellationTokencancellationToken){
vartask=Internal.PutFileUsingMonitorControllerAsync(path,metadata,monitorController);
monitorController.RegisterCancellationToken(cancellationToken);
returntask.ContinueWith(completedTask =>{
monitorController.Dispose();
if(metadata!=null)metadata.Dispose();
returncompletedTask;
}).Unwrap();
}

/// <summary>
/// Uploads from a content URI to this
/// <see cref="StorageReference" />
/// .
/// </summary>
/// <param name="filePath">
/// The source of the upload.
/// This should be a file system URI representing the path the object
/// should be uploaded from.
/// </param>
/// <param name="customMetadata">
/// <see cref="MetadataChange" />
/// containing additional information (MIME
/// type, etc.) about the object being uploaded.
/// </param>
/// <param name="progressHandler">
/// usually an instance of <see cref="StorageProgress"/> that will
/// receive periodic updates during the operation. This value can
/// be null.</param>
/// <param name="cancelToken">A CancellationToken to control the operation
/// and possibly later cancel it. This value may be CancellationToken.None
/// to indicate no value.</param>
/// <param name="previousSessionUri">A Uri previously obtained by
/// <see cref="UploadState.UploadSessionUri"/> that can be used to resume
/// a previously interrupted upload.</param>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the upload.
/// </returns>
publicTask<StorageMetadata>PutFileAsync(
stringfilePath,
MetadataChangecustomMetadata=null,
IProgress<UploadState>progressHandler=null,
CancellationTokencancelToken=default(CancellationToken),
UripreviousSessionUri=null){
Preconditions.CheckArgument(filePath!=null,"filePath cannot be null");
varresult=newTaskCompletionSource<StorageMetadata>();
stringfilePathUriOrLocalPath=filePath.StartsWith("file://")?
(newUri(filePath)).LocalPath:filePath;
if(File.Exists(filePathUriOrLocalPath)){
varuploadState=newUploadState(this,(newFileInfo(filePathUriOrLocalPath)).Length);
vartransferStateUpdater=newTransferStateUpdater<UploadState>(
this,progressHandler,uploadState,uploadState.State);
PutFileUsingMonitorControllerAsync(
filePath,StorageMetadata.BuildMetadataInternal(customMetadata),
transferStateUpdater.MonitorController,cancelToken).ContinueWith(task =>{
CompleteTask(task,result,
()=>{
varmetadata=newStorageMetadata(this,task.Result);
transferStateUpdater.SetMetadata(metadata);
returnmetadata;
},"PutFile");
});
}else{
result.SetException(newFileNotFoundException(String.Format("{0} not found",
filePathUriOrLocalPath),
filePath));
}
returnresult.Task;
}

/// <summary>
/// Uploads a stream of data to this
/// <see cref="StorageReference" />
/// .
/// The stream will remain open at the end of the upload.
/// </summary>
/// <param name="stream">
/// The
/// <see cref="Stream" />
/// to upload.
/// </param>
/// <param name="customMetadata">
/// <see cref="MetadataChange" />
/// containing additional information (MIME type, etc.)
/// about the object being uploaded.
/// </param>
/// <param name="progressHandler">
/// usually an instance of <see cref="StorageProgress"/> that will
/// receive periodic updates during the operation. This value can
/// be null.</param>
/// <param name="cancelToken">A CancellationToken to control the operation
/// and possibly later cancel it. This value may be CancellationToken.None
/// to indicate no value.</param>
/// <param name="previousSessionUri">A Uri previously obtained by
/// <see cref="UploadState.UploadSessionUri"/> that can be used to resume
/// a previously interrupted upload.</param>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the upload.
/// </returns>
publicTask<StorageMetadata>PutStreamAsync(
Streamstream,
MetadataChangecustomMetadata=null,
IProgress<UploadState>progressHandler=null,
CancellationTokencancelToken=default(CancellationToken),
UripreviousSessionUri=null){
Preconditions.CheckArgument(stream!=null,"stream cannot be null");
varresult=newTaskCompletionSource<StorageMetadata>();
// TODO(smiles): *STOP SHIP* This is awful as it copies the *entire* stream into memory then
// copies it *again* into a byte array that can be passed to PutBytes(). b/68200113
(newThread(()=>{
byte[]buffer=newbyte[512];
using(MemoryStreammemoryStream=newMemoryStream()){
while(true){
intread=stream.Read(buffer,0,buffer.Length);
if(read<=0)break;
memoryStream.Write(buffer,0,read);
}
PutBytesUsingCompletionSourceAsync(memoryStream.ToArray(),customMetadata,
progressHandler,cancelToken,previousSessionUri,
result);
}
})).Start();
returnresult.Task;
}

/// <summary>
/// Retrieves metadata associated with an object at this
/// <see cref="StorageReference" />
/// .
/// </summary>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the operation and obtain the result.
/// </returns>
publicTask<StorageMetadata>GetMetadataAsync(){
varresult=newTaskCompletionSource<StorageMetadata>();
Internal.GetMetadataAsync().ContinueWith(task =>{
CompleteTask(task,result,()=>{returnnewStorageMetadata(this,task.Result);},
"GetMetadata");
});
returnresult.Task;
}

/// <summary>
/// Retrieves a long lived download URL with a revokable token.
/// </summary>
/// <remarks>
/// Retrieves a long lived download URL with a revokable token.
/// This can be used to share the file with others, but can be revoked by a developer
/// in the Firebase Console if desired.
/// </remarks>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the operation and obtain the result.
/// </returns>
publicTask<Uri>GetDownloadUrlAsync(){
varresult=newTaskCompletionSource<Uri>();
Internal.GetDownloadUrlAsync().ContinueWith(task =>{
CompleteTask(task,result,
()=>{
varurl=task.Result;
if(String.IsNullOrEmpty(url))returnnull;
returnFirebaseStorage.ConstructFormattedUri(url);
},"GetDownloadUrl.");
});
returnresult.Task;
}

/// <summary>
/// Updates the metadata associated with this
/// <see cref="StorageReference" />
/// .
/// </summary>
/// <param name="metadata">
/// A
/// <see cref="MetadataChange" />
/// object with the metadata to update.
/// </param>
/// <returns>
/// a
/// <see cref="System.Threading.Tasks.Task" />
/// that will return the final
/// <see cref="StorageMetadata" />
/// once the operation
/// is complete.
/// </returns>
publicTask<StorageMetadata>UpdateMetadataAsync(MetadataChangemetadata){
Preconditions.CheckNotNull(metadata);
varresult=newTaskCompletionSource<StorageMetadata>();
varmetadataInternal=metadata.Build().Internal;
Internal.UpdateMetadataAsync(metadataInternal).ContinueWith(
 task =>{
metadataInternal.Dispose();
CompleteTask(task,result,()=>{returnnewStorageMetadata(this,task.Result);},
"UpdateMetadata");
});
returnresult.Task;
}

/// <summary>
/// Downloads the object from this
/// <see cref="StorageReference" />
/// A byte array will be allocated large enough to hold the entire file in memory.
/// Therefore, using this method will impact memory usage of your process. If you are
/// downloading many large files,
/// <see>
/// <cref>GetStream(StreamDownloadTask.StreamProcessor)</cref>
/// </see>
/// may be a better option.
/// </summary>
/// <param name="maxDownloadSizeBytes">
/// The maximum allowed size in bytes that will be allocated.
/// Set this parameter to prevent out of memory conditions from
/// occurring. If the download exceeds this limit, the task will
/// fail and an
/// <see cref="System.IndexOutOfRangeException" />
/// will be returned.
/// </param>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the operation and obtain the result.
/// </returns>
publicTask<byte[]>GetBytesAsync(longmaxDownloadSizeBytes){
returnGetBytesAsync(maxDownloadSizeBytes,progressHandler:null,
cancelToken:default(CancellationToken));
}

/// <summary>
/// Call Internal.GetBytesUsingMonitorControllerAsync while maintaining a reference to
/// monitorController until the operation is complete.
/// </summary>
/// <param name="buffer">Address of pinned buffer to read into.</param>
/// <param name="bufferSize">Size of buffer in bytes.</param>
/// <param name="monitorController">Object that can be used to monitor and control the
/// transfer.</param>
/// <param name="cancellationToken">Token which can be used to cancel the transfer.</param>
/// <returns>Task that indicates when the download is complete.
/// NOTE: This task is the object constructed from firebase::Future.</returns>
internalTask<long>GetBytesUsingMonitorControllerAsync(
System.IntPtrbuffer,uintbufferSize,MonitorControllerInternalmonitorController,
CancellationTokencancellationToken){
vartask=Internal.GetBytesUsingMonitorControllerAsync(buffer,bufferSize,
monitorController);
monitorController.RegisterCancellationToken(cancellationToken);
returntask.ContinueWith(completedTask =>{
monitorController.Dispose();
returncompletedTask;
}).Unwrap();
}

/// <summary>
/// Downloads the object from this
/// <see cref="StorageReference" />
/// A byte array will be allocated large enough to hold the entire file in memory.
/// Therefore, using this method will impact memory usage of your process. If you are
/// downloading many large files,
/// <see>
/// <cref>GetStream(StreamDownloadTask.StreamProcessor)</cref>
/// </see>
/// may be a better option.
/// </summary>
/// <param name="maxDownloadSizeBytes">
/// The maximum allowed size in bytes that will be allocated.
/// Set this parameter to prevent out of memory conditions from
/// occurring. If the download exceeds this limit, the task will
/// fail and an
/// <see cref="System.IndexOutOfRangeException" />
/// will be returned.
/// </param>
/// <param name="progressHandler">
/// usually an instance of <see cref="StorageProgress"/> that will
/// receive periodic updates during the operation. This value can
/// be null.</param>
/// <param name="cancelToken">A CancellationToken to control the operation
/// and possibly later cancel it. This value may be CancellationToken.None
/// to indicate no value.</param>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the operation and obtain the result.
/// </returns>
publicTask<byte[]>GetBytesAsync(longmaxDownloadSizeBytes,
IProgress<DownloadState>progressHandler,
CancellationTokencancelToken=default(CancellationToken)){
Logger.LogMessage(LogLevel.Debug,
String.Format("Get up to {0} bytes.",maxDownloadSizeBytes>0?
maxDownloadSizeBytes.ToString():"all"));
varresult=newTaskCompletionSource<byte[]>();
GetMetadataAsync().ContinueWith(metadataTask =>{
varsuccessful=CompleteTask(
metadataTask,result,()=>{
// If the returned metadata describes a zero sized file, abort.
if(metadataTask.Result.SizeBytes<=0){
returnnull;
}
// NOTE: This value is unused, we just return a non-null value here to indicate
// success.
returnnewbyte[1];
},
"Get file size",setCompletionSourceResult:false);
if(successful==null)return;
varmetadata=metadataTask.Result;
varsizeBytes=metadata.SizeBytes;
Logger.LogMessage(LogLevel.Debug,String.Format("Fetched metadata: {0}",
metadata.AsString()));
ExceptionfaultException=null;
if(maxDownloadSizeBytes>0&&sizeBytes>maxDownloadSizeBytes){
faultException=newIndexOutOfRangeException(
String.Format("File size {0} is larger than the maximum download size {1}",
sizeBytes,maxDownloadSizeBytes));
}

// Clamp the download size to sizeBytes if maxDownloadSizeBytes is specified
// (i.e not zero) and greater than the size of the file.
vardownloadSizeBytes=(maxDownloadSizeBytes>0&&maxDownloadSizeBytes<sizeBytes)?
maxDownloadSizeBytes:sizeBytes;
Logger.LogMessage(LogLevel.Debug,String.Format("Downloading {0} bytes",
downloadSizeBytes));
vardownloadState=newDownloadState(this,downloadSizeBytes);
vartransferStateUpdater=newTransferStateUpdater<DownloadState>(
this,progressHandler,downloadState,downloadState.State);
varbytes=newbyte[downloadSizeBytes];
varbytesHandle=GCHandle.Alloc(bytes,GCHandleType.Pinned);
GetBytesUsingMonitorControllerAsync(
bytesHandle.AddrOfPinnedObject(),(uint)bytes.Length,
transferStateUpdater.MonitorController,cancelToken).ContinueWith(downloadTask =>{
bytesHandle.Free();
CompleteTask(downloadTask,result,()=>{
if(faultException!=null){
result.SetException(faultException);
}
returnbytes;
},"GetBytes");
});
});
returnresult.Task;
}

/// <summary>
/// Call Internal.GetFileUsingMonitorControllerAsync while maintaining a reference to
/// monitorController until the operation is complete.
/// </summary>
/// <param name="path">Path (URI string) of the file to read to.</param>
/// <param name="monitorController">Object that can be used to monitor and control the
/// transfer.</param>
/// <param name="cancellationToken">Token which can be used to cancel the transfer.</param>
/// <returns>Task that indicates when the download is complete.
/// NOTE: This task is the object constructed from firebase::Future.</returns>
privateTask<long>GetFileUsingMonitorControllerAsync(
stringpath,MonitorControllerInternalmonitorController,
CancellationTokencancellationToken){
vartask=Internal.GetFileUsingMonitorControllerAsync(path,monitorController);
monitorController.RegisterCancellationToken(cancellationToken);
returntask.ContinueWith(completedTask =>{
monitorController.Dispose();
returncompletedTask;
}).Unwrap();
}

/// <summary>
/// Downloads the object at this
/// <see cref="StorageReference" />
/// to a specified system
/// filepath.
/// </summary>
/// <param name="destinationFilePath">
/// A file system URI representing the path the object should be
/// downloaded to.
/// </param>
/// <param name="progressHandler">
/// usually an instance of <see cref="StorageProgress"/> that will
/// receive periodic updates during the operation. This value can
/// be null.</param>
/// <param name="cancelToken">A CancellationToken to control the operation
/// and possibly later cancel it. This value may be CancellationToken.None
/// to indicate no value.</param>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the operation and obtain the result.
/// </returns>
publicTaskGetFileAsync(stringdestinationFilePath,
IProgress<DownloadState>progressHandler=null,
CancellationTokencancelToken=default(CancellationToken)){
Logger.LogMessage(LogLevel.Debug,String.Format("Downloading to {0}.",
destinationFilePath));
vardownloadState=newDownloadState(this,-1);
vartransferStateUpdater=newTransferStateUpdater<DownloadState>(
this,progressHandler,downloadState,downloadState.State);
returnGetFileUsingMonitorControllerAsync(
destinationFilePath,transferStateUpdater.MonitorController,
cancelToken).ContinueWith((task)=>{
return(newTaskCompletionStatus(task,"GetFile",Logger)).ToTask();
}).Unwrap();
}

/// <summary>
/// Downloads the object at this
/// <see cref="StorageReference" />
/// via a
/// <see cref="Stream" />
/// .
/// The resulting InputStream should be not be accessed on the main thread
/// because calling into it may block the calling thread.
/// </summary>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the operation.
/// </returns>
publicTask<Stream>GetStreamAsync(){
varresult=newTaskCompletionSource<Stream>();
// TODO(smiles): Fix this interface as it's totally odd. Reading an entire file into a stream
// seems broken rather than simply providing a stream with a small-ish buffer that blocks
// downloading when it's not being read and is complete when it is closed.
// Also, this doesn't support progress reporting or cancellation.
GetBytesAsync(0).ContinueWith(task =>{
CompleteTask(task,result,()=>{
varbytes=task.Result;
returnbytes!=null?newMemoryStream(bytes):null;
},
"GetStreamAsync");
});
returnresult.Task;
}

/// <summary>
/// Downloads the object at this
/// <see cref="StorageReference" />
/// via a
/// <see cref="Stream" />
/// .
/// </summary>
/// <param name="streamProcessor">
/// A delegate
/// that is responsible for
/// reading data from the
/// <see cref="Stream" />
/// .
/// The delegate
/// is called on a background
/// thread and exceptions thrown from this object will be returned as
/// a failure to the Task
/// </param>
/// <param name="progressHandler">
/// usually an instance of <see cref="StorageProgress"/> that will
/// receive periodic updates during the operation. This value can
/// be null.</param>
/// <param name="cancelToken">A CancellationToken to control the operation
/// and possibly later cancel it. This value may be CancellationToken.None
/// to indicate no value.</param>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the operation and obtain the result.
/// </returns>
publicTaskGetStreamAsync(Action<Stream>streamProcessor,
IProgress<DownloadState>progressHandler=null,
CancellationTokencancelToken=default(CancellationToken)){
// TODO(smiles): *STOP SHIP* Fix streaming support. b/68200113
returnGetBytesAsync(0,progressHandler:progressHandler,
cancelToken:cancelToken).ContinueWith(task =>{
if(!task.IsFaulted&&!task.IsCanceled){
varbytes=task.Result;
if(bytes!=null){
streamProcessor(newMemoryStream(bytes));
}
}
returntask;
}).Unwrap();
}

/// <summary>
/// Deletes the object at this
/// <see cref="StorageReference" />
/// .
/// </summary>
/// <returns>
/// A <see cref="Task"/>
/// which can be used to monitor the operation and obtain the result.
/// </returns>
publicTaskDeleteAsync(){
returnInternal.DeleteAsync().ContinueWith((task)=>{
if(task.IsFaulted&&(task.Exception!=null)){
returnTask.Run(()=>{throwStorageException.CreateFromException(task.Exception);});
}
returntask;
}).Unwrap();
}

/// <returns>
/// This object in URI form, which can then be shared and passed into
/// <see cref="FirebaseStorage.GetReferenceFromUrl" />
/// .
/// </returns>
publicoverridestringToString(){
returnString.Format("gs://{0}{1}",Bucket,Path);
}

/// <summary>
/// Compares two storage reference URIs.
/// </summary>
/// <returns>true if two references point to the same path, false otherwise.</returns>
publicoverrideboolEquals(objectother){
if(!(otherisStorageReference)){
returnfalse;
}
varotherStorage=(StorageReference)other;
returnotherStorage.ToString().Equals(ToString());
}

/// <summary>
/// Create a hash of the URI string used by this reference.
/// </summary>
/// <returns>Hash of this reference's URI.</returns>
publicoverrideintGetHashCode(){
returnToString().GetHashCode();
}

// C# proxy for the firebase::storage::StorageReference object.
internalStorageReferenceInternalInternal{get;privateset;}

/// <summary>
/// Complete the specified task by either setting a result on the completion source or
/// forwarding the failures status from the completion source.
/// </summary>
/// <param name="task">Task to read completion status from.</param>
/// <param name="completionSource">Completion source to set the result on.</param>
/// <param name="getResult">Function that is called if the task successfully completed. This
/// function should return the result if it succeeded or null if it failed.</param>
/// <param name="operationDescription">Description of the operation being completed. This is
/// used to log the completion and to form the exception string when setting an
/// InvalidOperationException on the task, if the task failed but didn't contain an exception.
/// </param>
/// <param name="setCompletionSourceResult">Whether to set the result on the task completion
/// source. This can be disabled if the completion of the completionSource should occur
/// outside of this method.</param>
/// <param name="operationDescription">Description of the operation being completed used when
/// logging is enabled.</param>
/// <returns>Value returned by setResult() if successful, null otherwise.</returns>
privateOCompleteTask<I,O>(Task<I>task,TaskCompletionSource<O>completionSource,
Func<O>getResult,stringoperationDescription,
boolsetCompletionSourceResult=true){
Oresult=default(O);
varstatus=newTaskCompletionStatus(task,operationDescription,Logger);
if(status.IsSuccessful){
result=getResult();
if(result!=null){
if(setCompletionSourceResult)completionSource.SetResult(result);
returnresult;
}
}
if(status.IsCanceled){
completionSource.SetCanceled();
returnresult;
}
completionSource.SetException(status.Exception);
returnresult;
}
}
}