comparison data/fileio/FileSource.h @ 325:82a2d3161e14

* Document FileSource
author Chris Cannam
date Thu, 01 Nov 2007 12:34:17 +0000
parents 9cdc7a4efde2
children 1d656dcda8ef
comparison
equal deleted inserted replaced
324:9cdc7a4efde2 325:82a2d3161e14
27 class QHttp; 27 class QHttp;
28 class QFile; 28 class QFile;
29 class QProgressDialog; 29 class QProgressDialog;
30 class QHttpResponseHeader; 30 class QHttpResponseHeader;
31 31
32 /**
33 * FileSource is a class used to refer to the contents of a file that
34 * may be either local or at a remote location such as a HTTP URL.
35 *
36 * When a FileSource object is constructed, the file or URL passed to
37 * its constructor is tested for validity, and if it refers to a
38 * remote HTTP or FTP location it is retrieved asynchronously (the Qt
39 * event loop must be running) and cached locally. You can then query
40 * a local path for the file and refer to that as a normal filename.
41 *
42 * Use isAvailable() to test whether the file or remote URL exists,
43 * and isOK() to test for internal validity or transmission errors.
44 * Call waitForStatus() to block until the availability and validity
45 * of the URL have been established so that isAvailable may be called,
46 * and waitForData() to block until the entire file has been cached.
47 *
48 * FileSource handles reference counting for cache files. You can
49 * construct many FileSource objects with the same URL and you will
50 * receive the same cached file for each; it is also reasonable to
51 * pass FileSource objects by value. FileSource only makes sense for
52 * stateless URLs that result in the same data on each request.
53 *
54 * Cached files share a lifetime with their "owning" FileSource
55 * objects; when the last FileSource referring to a given URL is
56 * deleted or goes out of scope, its cached file (if any) is also
57 * removed.
58 */
32 class FileSource : public QObject 59 class FileSource : public QObject
33 { 60 {
34 Q_OBJECT 61 Q_OBJECT
35 62
36 public: 63 public:
64
65 /**
66 * Construct a FileSource using the given local file path or URL.
67 * The URL may be raw or encoded. If showProgress is true, a
68 * progress dialog will be shown for any network transfers.
69 */
37 FileSource(QString fileOrUrl, bool showProgress = false); 70 FileSource(QString fileOrUrl, bool showProgress = false);
71
72 /**
73 * Construct a FileSource using the given remote URL. If
74 * showProgress is true, a progress dialog will be shown for any
75 * network transfers.
76 */
38 FileSource(QUrl url, bool showProgress = false); 77 FileSource(QUrl url, bool showProgress = false);
78
39 FileSource(const FileSource &); 79 FileSource(const FileSource &);
40 80
41 virtual ~FileSource(); 81 virtual ~FileSource();
42 82
83 /**
84 * Block on a sub-event-loop until the availability of the file or
85 * remote URL is known.
86 */
87 void waitForStatus();
88
89 /**
90 * Block on a sub-event-loop until the whole of the data has been
91 * retrieved (if it is remote).
92 */
93 void waitForData();
94
95 /**
96 * Return true if the FileSource object is valid and no error
97 * occurred in looking up the file or remote URL. Non-existence
98 * of the file or URL is not an error -- call isAvailable() to
99 * test for that.
100 */
101 bool isOK() const;
102
103 /**
104 * Return true if the file or remote URL exists. This may block
105 * on a sub-event-loop (calling waitForStatus) if the status is
106 * not yet available.
107 */
43 bool isAvailable(); 108 bool isAvailable();
44 109
45 void waitForStatus(); 110 /**
46 void waitForData(); 111 * Return true if the entire file has been retrieved and is
47 112 * available.
113 */
114 bool isDone() const;
115
116 /**
117 * Return true if this FileSource is referring to a remote URL.
118 */
119 bool isRemote() const;
120
121 /**
122 * Return the location filename or URL as passed to the
123 * constructor.
124 */
125 QString getLocation() const;
126
127 /**
128 * Return the name of the local file this FileSource refers to.
129 * This is the filename that should be used when reading normally
130 * from the FileSource. If the filename passed to the constructor
131 * was a local file, this will return the same filename; otherwise
132 * this will be the name of the temporary cache file owned by the
133 * FileSource.
134 */
135 QString getLocalFilename() const;
136
137 /**
138 * Return the MIME content type of this file, if known.
139 */
140 QString getContentType() const;
141
142 /**
143 * Return the file extension for this file, if any.
144 */
145 QString getExtension() const;
146
147 /**
148 * Return an error message, if isOK() is false.
149 */
150 QString getErrorString() const;
151
152 /**
153 * Specify whether any local, cached file should remain on disc
154 * after this FileSource has been destroyed. The default is false
155 * (cached files share their FileSource owners' lifespans).
156 */
48 void setLeaveLocalFile(bool leave); 157 void setLeaveLocalFile(bool leave);
49 158
50 bool isOK() const; 159 /**
51 bool isDone() const; 160 * Return true if the given filename or URL refers to a remote
52 bool isRemote() const; 161 * URL.
53 162 */
54 QString getLocation() const;
55 QString getLocalFilename() const;
56 QString getContentType() const;
57 QString getExtension() const;
58
59 QString getErrorString() const;
60
61 static bool isRemote(QString fileOrUrl); 163 static bool isRemote(QString fileOrUrl);
164
165 /**
166 * Return true if FileSource can handle the retrieval scheme for
167 * the given URL (or if the URL is for a local file).
168 */
62 static bool canHandleScheme(QUrl url); 169 static bool canHandleScheme(QUrl url);
63 170
64 signals: 171 signals:
172 /**
173 * Emitted during URL retrieval, when the retrieval progress
174 * notches up to a new percentage.
175 */
65 void progress(int percent); 176 void progress(int percent);
177
178 /**
179 * Emitted when the file's existence has been tested and/or
180 * response header received. Calls to isAvailable() after this
181 * has been emitted will not block.
182 */
183 void statusAvailable();
184
185 /**
186 * Emitted when the entire file data has been retrieved and the
187 * local file is complete (if no error has occurred).
188 */
66 void ready(); 189 void ready();
67 190
68 protected slots: 191 protected slots:
69 void dataReadProgress(int done, int total); 192 void dataReadProgress(int done, int total);
70 void httpResponseHeaderReceived(const QHttpResponseHeader &resp); 193 void httpResponseHeaderReceived(const QHttpResponseHeader &resp);