# HG changeset patch # User Chris Cannam # Date 1193920457 0 # Node ID 82a2d3161e140679527101361aaca63442c1b97c # Parent 9cdc7a4efde2f9e6068ab681ffbd5a792f3a542e * Document FileSource diff -r 9cdc7a4efde2 -r 82a2d3161e14 data/fileio/FileSource.cpp --- a/data/fileio/FileSource.cpp Thu Nov 01 10:45:28 2007 +0000 +++ b/data/fileio/FileSource.cpp Thu Nov 01 12:34:17 2007 +0000 @@ -85,6 +85,11 @@ init(showProgress); } } + + if (!isRemote()) { + emit statusAvailable(); + emit ready(); + } } FileSource::FileSource(QUrl url, bool showProgress) : @@ -481,7 +486,8 @@ std::cerr << "FileSource::responseHeaderReceived: " << m_lastStatus << std::endl; if (resp.hasContentType()) m_contentType = resp.contentType(); - } + } + emit statusAvailable(); } void diff -r 9cdc7a4efde2 -r 82a2d3161e14 data/fileio/FileSource.h --- a/data/fileio/FileSource.h Thu Nov 01 10:45:28 2007 +0000 +++ b/data/fileio/FileSource.h Thu Nov 01 12:34:17 2007 +0000 @@ -29,40 +29,163 @@ class QProgressDialog; class QHttpResponseHeader; +/** + * FileSource is a class used to refer to the contents of a file that + * may be either local or at a remote location such as a HTTP URL. + * + * When a FileSource object is constructed, the file or URL passed to + * its constructor is tested for validity, and if it refers to a + * remote HTTP or FTP location it is retrieved asynchronously (the Qt + * event loop must be running) and cached locally. You can then query + * a local path for the file and refer to that as a normal filename. + * + * Use isAvailable() to test whether the file or remote URL exists, + * and isOK() to test for internal validity or transmission errors. + * Call waitForStatus() to block until the availability and validity + * of the URL have been established so that isAvailable may be called, + * and waitForData() to block until the entire file has been cached. + * + * FileSource handles reference counting for cache files. You can + * construct many FileSource objects with the same URL and you will + * receive the same cached file for each; it is also reasonable to + * pass FileSource objects by value. FileSource only makes sense for + * stateless URLs that result in the same data on each request. + * + * Cached files share a lifetime with their "owning" FileSource + * objects; when the last FileSource referring to a given URL is + * deleted or goes out of scope, its cached file (if any) is also + * removed. + */ class FileSource : public QObject { Q_OBJECT public: + + /** + * Construct a FileSource using the given local file path or URL. + * The URL may be raw or encoded. If showProgress is true, a + * progress dialog will be shown for any network transfers. + */ FileSource(QString fileOrUrl, bool showProgress = false); + + /** + * Construct a FileSource using the given remote URL. If + * showProgress is true, a progress dialog will be shown for any + * network transfers. + */ FileSource(QUrl url, bool showProgress = false); + FileSource(const FileSource &); virtual ~FileSource(); + /** + * Block on a sub-event-loop until the availability of the file or + * remote URL is known. + */ + void waitForStatus(); + + /** + * Block on a sub-event-loop until the whole of the data has been + * retrieved (if it is remote). + */ + void waitForData(); + + /** + * Return true if the FileSource object is valid and no error + * occurred in looking up the file or remote URL. Non-existence + * of the file or URL is not an error -- call isAvailable() to + * test for that. + */ + bool isOK() const; + + /** + * Return true if the file or remote URL exists. This may block + * on a sub-event-loop (calling waitForStatus) if the status is + * not yet available. + */ bool isAvailable(); - void waitForStatus(); - void waitForData(); + /** + * Return true if the entire file has been retrieved and is + * available. + */ + bool isDone() const; + /** + * Return true if this FileSource is referring to a remote URL. + */ + bool isRemote() const; + + /** + * Return the location filename or URL as passed to the + * constructor. + */ + QString getLocation() const; + + /** + * Return the name of the local file this FileSource refers to. + * This is the filename that should be used when reading normally + * from the FileSource. If the filename passed to the constructor + * was a local file, this will return the same filename; otherwise + * this will be the name of the temporary cache file owned by the + * FileSource. + */ + QString getLocalFilename() const; + + /** + * Return the MIME content type of this file, if known. + */ + QString getContentType() const; + + /** + * Return the file extension for this file, if any. + */ + QString getExtension() const; + + /** + * Return an error message, if isOK() is false. + */ + QString getErrorString() const; + + /** + * Specify whether any local, cached file should remain on disc + * after this FileSource has been destroyed. The default is false + * (cached files share their FileSource owners' lifespans). + */ void setLeaveLocalFile(bool leave); - bool isOK() const; - bool isDone() const; - bool isRemote() const; + /** + * Return true if the given filename or URL refers to a remote + * URL. + */ + static bool isRemote(QString fileOrUrl); - QString getLocation() const; - QString getLocalFilename() const; - QString getContentType() const; - QString getExtension() const; - - QString getErrorString() const; - - static bool isRemote(QString fileOrUrl); + /** + * Return true if FileSource can handle the retrieval scheme for + * the given URL (or if the URL is for a local file). + */ static bool canHandleScheme(QUrl url); signals: + /** + * Emitted during URL retrieval, when the retrieval progress + * notches up to a new percentage. + */ void progress(int percent); + + /** + * Emitted when the file's existence has been tested and/or + * response header received. Calls to isAvailable() after this + * has been emitted will not block. + */ + void statusAvailable(); + + /** + * Emitted when the entire file data has been retrieved and the + * local file is complete (if no error has occurred). + */ void ready(); protected slots: