// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2008 Emweb bvba, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
  */
#ifndef WFILE_RESOURCE_H_
#define WFILE_RESOURCE_H_

#include <string>
#include <Wt/WResource>

namespace Wt {

/*! \class WFileResource Wt/WFileResource Wt/WFileResource
 *  \brief A resource which streams data from a local file
 *
 * To update the resource, either use setFileName() to point it to a
 * new file, or emit the WResource::dataChanged() signal when only the
 * file contents has changed, but not the filename.
 *
 * The resource makes use of continuations to transmit data piecewise,
 * without blocking a thread or requiring the entire file to be read
 * in memory. The size of the buffer can be changed using
 * setBufferSize().
 *
 * \if cpp
 * Usage examples:
 * \code
 * Wt::WFileResource *csvFile = new Wt::WFileResource("text/csv", "/opt/files/afile.csv");
 * csvFile->suggestFileName("data.csv");
 * Wt::WAnchor *anchor = new Wt::WAnchor(csvFile, "CSV data");
 *
 * Wt::WFileResource *imageFile = new Wt::WFileResource("image/png", "/opt/files/image.png");
 * imageFile->suggestFileName("data.png");
 * Wt::WImage *image = new Wt::WImage(imageFile, "PNG version");
 * \endcode
 * \endif
 *
 * \sa WMemoryResource
 */
class WT_API WFileResource : public WResource
{
public:
  /*! \brief Creates a new resource with given mime-type and contents stored
   *         in filename.
   */
  WFileResource(const std::string& mimeType, const std::string& fileName,
		WObject *parent = 0);

  /*! \brief Destructor.
   *
   * It is up to the user to make sure that the resource is no longer
   * in use (by e.g. a WImage).
   */
  ~WFileResource();

  /*! \brief Sets a (different) filename.
   *
   * Set the location of the file on the local filesystem which must be
   * streamed for this resource.
   */
  void setFileName(const std::string& fileName);

  /*! \brief Returns the filename.
   */
  const std::string& fileName() const { return fileName_; }

  /*! \brief Sets the mime-type.
   */
  void setMimeType(const std::string& mimeType);

  /*! \brief Returns the mime-type.
   */
  const std::string& mimeType() const { return mimeType_; }

  /*! \brief Configures the buffer size.
   *
   * This configures the size of the buffer used to transmit the file
   * piece by piece.
   */
  void setBufferSize(int size);

  /*! \brief Returns the buffer size.
   *
   * \sa setBufferSize()
   */
  int bufferSize() const { return bufferSize_; }

protected:
  virtual void handleRequest(const Http::Request& request,
			     Http::Response& response);

private:
  std::string mimeType_;
  std::string fileName_;
  int         bufferSize_;
};

}

#endif // WFILE_RESOURCE_H_
