/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIBackgroundFileSaverObserver;
interface nsIFile;

/**
 * Allows saving data to a file, while handling all the input/output on a
 * background thread, including the initial file name assignment and any
 * subsequent renaming of the target file.
 *
 * This interface is designed for file downloads.  Generally, they start in the
 * temporary directory, while the user is selecting the final name.  Then, they
 * are moved to the chosen target directory with a ".part" extension appended to
 * the file name.  Finally, they are renamed when the download is completed.
 *
 * Components implementing both nsIBackgroundFileSaver and nsIStreamListener
 * allow data to be fed using an implementation of OnDataAvailable that never
 * blocks the calling thread.  They suspend the request that drives the stream
 * listener in case too much data is being fed, and resume it when the data has
 * been written.  Calling OnStopRequest does not necessarily close the target
 * file, and the Finish method must be called to complete the operation.
 *
 * Components implementing both nsIBackgroundFileSaver and nsIAsyncOutputStream
 * allow data to be fed directly to the non-blocking output stream, that however
 * may return NS_BASE_STREAM_WOULD_BLOCK in case too much data is being fed.
 * Closing the output stream does not necessarily close the target file, and the
 * Finish method must be called to complete the operation.
 *
 * @remarks Implementations may require the consumer to always call Finish.  If
 *          the object reference is released without calling Finish, a memory
 *          leak may occur, and the target file might be kept locked. All
 *          public methods of the interface may only be called from the main
 *          thread.
 */
[scriptable, uuid(17a2ff32-918f-11e2-8fc9-f9626188709b)]
interface nsIBackgroundFileSaver : nsISupports
{
  /**
   * This observer receives notifications when the target file name changes and
   * when the operation completes, successfully or not.
   *
   * @remarks A strong reference to the observer is held.  Notification events
   *          are dispatched to the thread that created the object that
   *          implements nsIBackgroundFileSaver.
   */
  attribute nsIBackgroundFileSaverObserver observer;

  /**
   * The SHA256 hash in raw bytes associated with the file that was downloaded.
   *
   * @remarks Reading this will throw NS_ERROR_NOT_AVAILABLE unless
   *          sha256enabled is true and onSaveComplete has been called.
   */
  readonly attribute ACString sha256Hash;

  /**
   * Compute SHA256.
   *
   * @remarks This must be set on the main thread before the first call to
   *          setTarget.
   */
  void enableSha256();

  /**
   * Sets the name of the output file to be written.  The output file may
   * already exist, in which case it will be overwritten.  The target can be
   * changed after data has already been fed, in which case the existing file
   * will be moved to the new destination.
   *
   * No file will be written until this function is called at least once.  It's
   * recommended not to feed any data until the output file is set.
   *
   * If an input/output error occurs with the specified file, the save operation
   * fails.  Failure is notified asynchronously through the observer.
   *
   * @param aTarget
   *        New output file to be written.
   * @param aKeepPartial
   *        Indicates whether aFile should be kept as partially completed,
   *        rather than deleted, if the operation fails or is canceled.  This is
   *        generally set for downloads that use temporary ".part" files.
   */
  void setTarget(in nsIFile aTarget, in bool aKeepPartial);

  /**
   * Terminates access to the output file, then notifies the observer with the
   * specified status code.  A failure code will force the operation to be
   * canceled, in which case the output file will be deleted if requested.
   *
   * This forces the involved streams to be closed, thus no more data should be
   * fed to the component after this method has been called.
   *
   * This is the last method that should be called on this object, and the
   * target file name cannot be changed anymore after this method has been
   * called.  Conversely, before calling this method, the file can still be
   * renamed even if all the data has been fed.
   *
   * @param aStatus
   *        Result code that determines whether the operation should succeed or
   *        be canceled, and is notified to the observer.  If the operation
   *        fails meanwhile for other reasons, or the observer has been already
   *        notified of completion, this status code is ignored.
   */
  void finish(in nsresult aStatus);
};

[scriptable, uuid(ee7058c3-6e54-4411-b76b-3ce87b76fcb6)]
interface nsIBackgroundFileSaverObserver : nsISupports
{
  /**
   * Called when the name of the output file has been determined.  This function
   * may be called more than once if the target file is renamed while saving.
   *
   * @param aSaver
   *        Reference to the object that raised the notification.
   * @param aTarget
   *        Name of the file that is being written.
   */
  void onTargetChange(in nsIBackgroundFileSaver aSaver, in nsIFile aTarget);

  /**
   * Called when the operation completed, and the target file has been closed.
   * If the operation succeeded, the target file is ready to be used, otherwise
   * it might have been already deleted.
   *
   * @param aSaver
   *        Reference to the object that raised the notification.
   * @param aStatus
   *        Result code that determines whether the operation succeded or
   *        failed, as well as the failure reason.
   */
  void onSaveComplete(in nsIBackgroundFileSaver aSaver, in nsresult aStatus);
};