// This may look like C code, but it's really -*- C++ -*-

/*

 * Copyright (C) 2008 Emweb bv, Herent, Belgium.

 *

 * See the LICENSE file for terms of use.

 */

#ifndef WFILEUPLOAD_H_

#define WFILEUPLOAD_H_

#include <Wt/WJavaScriptSlot.h>

#include <Wt/WWebWidget.h>

namespace Wt {

/*! \class WFileUpload Wt/WFileUpload.h Wt/WFileUpload.h

 *  \brief A widget that allows a file to be uploaded.

 *

 * This widget is displayed as a box in which a filename can be

 * entered and a browse button.

 *

 * Depending on availability of JavaScript, the behaviour of the widget

 * is different, but the API is designed in a way which facilitates

 * a portable use.

 *

 * When JavaScript is available, the file will not be uploaded until

 * upload() is called. This will start an asynchronous upload (and

 * thus return immediately). \if cpp While the file is being uploaded,

 * the dataReceived() signal is emitted when data is being received

 * and if the connector library provides support (see also

 * WResource::setUploadProgress() for a more detailed

 * discussion). Although you can modify the GUI from this signal, you

 * still need to have a mechanism in place to update the client

 * interface (using a WTimer or using \link

 * WApplication::enableUpdates() server-push\endlink). When the file

 * has been uploaded, the uploaded() signal is emitted, or if the file

 * was too large, the fileTooLarge() signal is emitted. You may

 * configure a progress bar that is used to show the upload progress

 * using setProgressBar(). \endif

 *

 * When no JavaScript is available, the file will be uploaded with the

 * next click event. Thus, upload() has no effect -- the file will

 * already be uploaded, and the corresponding signals will already be

 * emitted. To test if upload() will start an upload, you may check

 * using the canUpload() call.

 *

 * Thus, to properly use the widget, one needs to follow these

 * rules:

 * <ul>

 *   <li>Be prepared to handle the uploaded() or fileTooLarge() signals

 *       also when upload() was not called.</li>

 *   <li>Check using canUpload() if upload() will schedule a new

 *       upload. if (!canUpload()) then upload() will not have any

 *       effect. if (canUpload()), upload() will start a new file upload,

 *       which completes succesfully using an uploaded() signal or a

 *       fileTooLarge() signals gets emitted.

 *   </li>

 * </ul>

 *

 * The %WFileUpload widget must be hidden or deleted when a file is

 * received. In addition it is wise to prevent the user from uploading

 * the file twice as in the example below.

 *

 * The uploaded file is automatically spooled to a local temporary

 * file which will be deleted together with the WFileUpload widget,

 * unless stealSpooledFile() is called.

 *

 * \if cpp

 * Usage example:

 * \code

 * Wt::WFileUpload *upload = addWidget(std::make_unique<Wt::WFileUpload>());

 * upload->setFileTextSize(40);

 *

 * // Provide a button

 * Wt::WPushButton *uploadButton =

 *   addWidget(std::make_unique<Wt::WPushButton>("Send"));

 * // Upload when the button is clicked.

 * uploadButton->clicked().connect(upload, &Wt::WFileUpload::upload);

 * uploadButton->clicked().connect(uploadButton, &Wt::WPushButton::disable);

 *

 * // Upload automatically when the user entered a file.

 * upload->changed().connect(upload, &WFileUpload::upload);

 * upload->changed().connect(uploadButton, &Wt::WPushButton::disable);

 *

 * // React to a succesfull upload.

 * upload->uploaded().connect(this, &MyWidget::fileUploaded);

 *

 * // React to a fileupload problem.

 * upload->fileTooLarge().connect(this, &MyWidget::fileTooLarge);

 * \endcode

 * \endif

 *

 * %WFileUpload is an \link WWidget::setInline(bool) inline \endlink widget.

 *

 * <h3>CSS</h3>

 *

 * The file upload itself corresponds to a <tt>&lt;input

 * type="file"&gt;</tt> tag, but may be wrapped in a

 * <tt>&lt;form&gt;</tt> tag for an Ajax session to implement the

 * asynchronous upload action. This widget does not provide styling,

 * and styling through CSS is not well supported across browsers.

 */

class WT_API WFileUpload : public WWebWidget

{

public:

  /*! \brief Creates a file upload widget

   */

  WFileUpload();

  ~WFileUpload();

  /*! \brief Sets whether the file upload accepts multiple files.

   *

   * In browsers which support the "multiple" attribute for the file

   * upload (to be part of HTML5) control, this will allow the user to

   * select multiple files at once.

   *

   * All uploaded files are available from uploadedFiles(). The

   * single-file API will return only information on the first

   * uploaded file.

   *

   * The default value is \c false.

   */

  void setMultiple(bool multiple);

  /*! \brief Returns whether multiple files can be uploaded.

   *

   * \sa setMultiple()

   */

  bool multiple() const { return flags_.test(BIT_MULTIPLE); }

  /*! \brief Sets the size of the file input.

   */

  void setFileTextSize(int chars);

  /*! \brief Returns the size of the file input.

   */

  int fileTextSize() const { return textSize_; }

  /*! \brief Returns the spooled location of the uploaded file.

   *

   * Returns the temporary filename in which the uploaded file was

   * spooled. The file is guaranteed to exist as long as the

   * WFileUpload widget is not deleted, or a new file is not uploaded.

   *

   * When multiple files were uploaded, this returns the information

   * from the first file.

   *

   * \sa stealSpooledFile()

   * \sa uploaded

   */

  std::string spoolFileName() const;

  /*! \brief Returns the client filename.

   *

   * When multiple files were uploaded, this returns the information

   * from the first file.

   *

   * \note Depending on the browser this is an absolute path

   *       or only the file name.

   */

  WT_USTRING clientFileName() const;

  /*! \brief Returns the client content description.

   *

   * When multiple files were uploaded, this returns the information

   * from the first file.

   */

  WT_USTRING contentDescription() const;

  /*! \brief Steals the spooled file.

   *

   * By stealing the file, the spooled file will no longer be deleted

   * together with this widget, which means you need to take care of

   * managing that.

   *

   * When multiple files were uploaded, this returns the information

   * from the first file.

   */

  void stealSpooledFile();

  /*! \brief Returns whether one or more files have been uploaded.

   */

  bool empty() const;

  /*! \brief Returns the uploaded files.

   */

  const std::vector<Http::UploadedFile>& uploadedFiles() const

    { return uploadedFiles_; }

  /*! \brief Returns whether upload() will start a new file upload.

   *

   * A call to upload() will only start a new file upload if there is

   * no JavaScript support. Otherwise, the most recent file will

   * already be uploaded.

   */

  bool canUpload() const { return fileUploadTarget_ != nullptr; }

  /*! \brief Use the click signal of another widget to open the file picker.

   *

   * This hides the default WFileUpload widget and uses the click-signal of the argument to

   * open the file picker. The upload logic is still handled by WFileUpload behind the scenes.

   * This action cannot be undone.

   *

   * WFileUpload does not take ownership of the widget, nor does it display it. You must still

   * place it in the widget tree yourself.

   */

  void setDisplayWidget(WInteractWidget *widget);

  /*! \brief %Signal emitted when a new file was uploaded.

   *

   * This signal is emitted when file upload has been completed.  It

   * is good practice to hide or delete the WFileUpload widget when a

   * file has been uploaded succesfully.

   *

   * \sa upload()

   * \sa fileTooLarge()

   */

  EventSignal<>& uploaded();

  /*! \brief %Signal emitted when the user tried to upload a too large file.

   *

   * The parameter is the (approximate) size of the file (in bytes) the user

   * tried to upload.

   *

   * The maximum file size is determined by the maximum request size,

   * which may be configured in the configuration file (<max-request-size>).

   *

   * \sa uploaded()

   * \sa WApplication::requestTooLarge()

   */

  JSignal< ::int64_t>& fileTooLarge() { return fileTooLarge_; }

  /*! \brief %Signal emitted when the user selected a new file.

   *

   * One could react on the user selecting a (new) file, by uploading

   * the file immediately.

   *

   * Caveat: this signal is not emitted with konqueror and possibly

   * other browsers. Thus, in the above scenario you should still provide

   * an alternative way to call the upload() method.

   */

  EventSignal<>& changed();

  /*! \brief Starts the file upload.

   *

   * The uploaded() signal is emitted when a file is uploaded, or the

   * fileTooLarge() signal is emitted when the file size exceeded the

   * maximum request size.

   *

   * \sa uploaded()

   * \sa canUpload()

   */

  void upload();

  /*! \brief Sets a progress bar to indicate upload progress.

   *

   * When the file is being uploaded, upload progress is indicated

   * using the provided progress bar. Both the progress bar range and

   * values are configured when the upload starts.

   *

   * The file upload itself is hidden as soon as the upload starts.

   *

   * The default progress bar is 0 (no upload progress is indicated).

   *

   * \if java

   * To update the progess bar server push is used, you should only

   * use this functionality when using a Servlet 3.0 compatible servlet

   * container.

   * \endif

   *

   * \sa dataReceived()

   */

  void setProgressBar(WProgressBar *progressBar);

  /*! \brief Sets a progress bar to indicate upload progress.

   *

   * When the file is being uploaded, upload progress is indicated

   * using the provided progress bar. Both the progress bar range and

   * values are configured when the upload starts.

   *

   * The bar becomes part of the file upload, and replaces the file

   * prompt when the upload is started.

   *

   * The default progress bar is 0 (no upload progress is indicated).

   *

   * \if java

   * To update the progess bar server push is used, you should only

   * use this functionality when using a Servlet 3.0 compatible servlet

   * container.

   * \endif

   *

   * \sa dataReceived()

   */

  void setProgressBar(std::unique_ptr<WProgressBar> progressBar);

  /*! \brief Returns the progress bar.

   *

   * \sa setProgressBar()

   */

  WProgressBar *progressBar() const { return progressBar_; }

  /*! \brief %Signal emitted while a file is being uploaded.

   *

   * When supported by the connector library, you can track the

   * progress of the file upload by listening to this signal.

   *

   * The first argument is the number of bytes received so far,

   * and the second argument is the total number of bytes.

   */

  Signal< ::uint64_t, ::uint64_t>& dataReceived() { return dataReceived_; }

  virtual void enableAjax() override;

  ///

  /// \brief Sets input accept attributes

  ///

  /// The accept attribute may be specified to provide user agents with a hint

  /// of what file types will be accepted.

  /// Use html input accept attributes as input.

  ///

  /// \code

  /// WFileUpload *fu = new WFileUpload(root());

  /// fu->setFilters("image/*");

  /// \endcode

  ///

  void setFilters(const std::string& acceptAttributes);

private:

  static const char *CHANGE_SIGNAL;

  static const char *UPLOADED_SIGNAL;

  static const int BIT_DO_UPLOAD                = 0;

  static const int BIT_ENABLE_AJAX              = 1;

  static const int BIT_UPLOADING                = 2;

  static const int BIT_MULTIPLE                 = 3;

  static const int BIT_ENABLED_CHANGED          = 4;

  static const int BIT_ACCEPT_ATTRIBUTE_CHANGED = 5;

  static const int BIT_USE_DISPLAY_WIDGET       = 6;

  std::bitset<7> flags_;

  int textSize_;

  std::vector<Http::UploadedFile> uploadedFiles_;

  JSignal< ::int64_t> fileTooLarge_;

  Signal< ::uint64_t, ::uint64_t> dataReceived_;

  Core::observing_ptr<WInteractWidget> displayWidget_;

  JSlot displayWidgetRedirect_;

  std::unique_ptr<WResource> fileUploadTarget_;

  std::unique_ptr<WProgressBar> containedProgressBar_;

  WProgressBar *progressBar_;

  std::string acceptAttributes_;

  void create();

  void onData(::uint64_t current, ::uint64_t total);

  void onDataExceeded(::uint64_t dataExceeded);

  std::string displayWidgetClickJS();

  virtual void setRequestTooLarge(::int64_t size) override;

protected:

  virtual void           updateDom(DomElement& element, bool all) override;

  virtual DomElement    *createDomElement(WApplication *app) override;

  virtual DomElementType domElementType() const override;

  virtual void           propagateRenderOk(bool deep) override;

  virtual void           getDomChanges(std::vector<DomElement *>& result,

                                       WApplication *app) override;

  virtual void propagateSetEnabled(bool enabled) override;

  virtual std::string renderRemoveJs(bool recursive) override;

private:

  void handleFileTooLarge(::int64_t fileSize);

  void onUploaded();

  virtual void setFormData(const FormData& formData) override;

  void setFiles(const std::vector<Http::UploadedFile>& files);

  friend class WFileUploadResource;

};

}

#endif // WFILEUPLOAD_H_