annotate data/fileio/FileSource.h @ 831:12aff5a181bc

When switching to "literal mode" for a local file path, use the original file path as passed to the FileSource ctor rather than going through QUrl. This avoids filename becoming encoded and QUrl::toString failing to decode it (as is happening with Windows paths using Qt5 currently).
author Chris Cannam <chris.cannam@eecs.qmul.ac.uk>
date Wed, 24 Jul 2013 18:12:57 +0100
parents 95d4a59295b7
children c6f2b93a7d52
rev   line source
Chris@208 1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
Chris@208 2
Chris@208 3 /*
Chris@208 4 Sonic Visualiser
Chris@208 5 An audio file viewer and annotation editor.
Chris@208 6 Centre for Digital Music, Queen Mary, University of London.
Chris@208 7 This file copyright 2007 QMUL.
Chris@208 8
Chris@208 9 This program is free software; you can redistribute it and/or
Chris@208 10 modify it under the terms of the GNU General Public License as
Chris@208 11 published by the Free Software Foundation; either version 2 of the
Chris@208 12 License, or (at your option) any later version. See the file
Chris@208 13 COPYING included with this distribution for more information.
Chris@208 14 */
Chris@208 15
Chris@465 16 #ifndef _FILE_SOURCE_H_
Chris@465 17 #define _FILE_SOURCE_H_
Chris@208 18
Chris@208 19 #include <QUrl>
Chris@208 20 #include <QMutex>
Chris@208 21 #include <QString>
Chris@210 22 #include <QTimer>
Chris@762 23 #include <QNetworkReply>
Chris@208 24
Chris@304 25 #include <map>
Chris@304 26
Chris@686 27 #include "base/Debug.h"
Chris@686 28
Chris@208 29 class QFile;
Chris@392 30 class ProgressReporter;
Chris@208 31
Chris@325 32 /**
Chris@325 33 * FileSource is a class used to refer to the contents of a file that
Chris@325 34 * may be either local or at a remote location such as a HTTP URL.
Chris@325 35 *
Chris@325 36 * When a FileSource object is constructed, the file or URL passed to
Chris@325 37 * its constructor is tested for validity, and if it refers to a
Chris@325 38 * remote HTTP or FTP location it is retrieved asynchronously (the Qt
Chris@325 39 * event loop must be running) and cached locally. You can then query
Chris@325 40 * a local path for the file and refer to that as a normal filename.
Chris@325 41 *
Chris@325 42 * Use isAvailable() to test whether the file or remote URL exists,
Chris@325 43 * and isOK() to test for internal validity or transmission errors.
Chris@325 44 * Call waitForStatus() to block until the availability and validity
Chris@325 45 * of the URL have been established so that isAvailable may be called,
Chris@325 46 * and waitForData() to block until the entire file has been cached.
Chris@325 47 *
Chris@325 48 * FileSource handles reference counting for cache files. You can
Chris@325 49 * construct many FileSource objects with the same URL and you will
Chris@325 50 * receive the same cached file for each; it is also reasonable to
Chris@325 51 * pass FileSource objects by value. FileSource only makes sense for
Chris@325 52 * stateless URLs that result in the same data on each request.
Chris@325 53 *
Chris@469 54 * Cached files share a lifetime with their "owning" FileSource
Chris@469 55 * objects; when the last FileSource referring to a given URL is
Chris@469 56 * deleted or goes out of scope, its cached file (if any) is also
Chris@469 57 * removed.
Chris@325 58 */
Chris@317 59 class FileSource : public QObject
Chris@208 60 {
Chris@208 61 Q_OBJECT
Chris@208 62
Chris@208 63 public:
Chris@325 64 /**
Chris@325 65 * Construct a FileSource using the given local file path or URL.
Chris@357 66 * The URL may be raw or encoded.
Chris@357 67 *
Chris@392 68 * If a ProgressReporter is provided, it will be updated with
Chris@392 69 * progress status. Note that the progress() signal will also be
Chris@392 70 * emitted regularly during retrieval, even if no reporter is
Chris@392 71 * supplied here. Caller retains ownership of the reporter object.
Chris@325 72 */
Chris@520 73 FileSource(QString fileOrUrl,
Chris@520 74 ProgressReporter *reporter = 0,
Chris@520 75 QString preferredContentType = "");
Chris@325 76
Chris@325 77 /**
Chris@357 78 * Construct a FileSource using the given remote URL.
Chris@357 79 *
Chris@392 80 * If a ProgressReporter is provided, it will be updated with
Chris@392 81 * progress status. Note that the progress() signal will also be
Chris@392 82 * emitted regularly during retrieval, even if no reporter is
Chris@392 83 * supplied here. Caller retains ownership of the reporter object.
Chris@325 84 */
Chris@469 85 FileSource(QUrl url, ProgressReporter *reporter = 0);
Chris@325 86
Chris@317 87 FileSource(const FileSource &);
Chris@316 88
Chris@317 89 virtual ~FileSource();
Chris@208 90
Chris@325 91 /**
Chris@325 92 * Block on a sub-event-loop until the availability of the file or
Chris@325 93 * remote URL is known.
Chris@325 94 */
Chris@325 95 void waitForStatus();
Chris@325 96
Chris@325 97 /**
Chris@325 98 * Block on a sub-event-loop until the whole of the data has been
Chris@325 99 * retrieved (if it is remote).
Chris@325 100 */
Chris@325 101 void waitForData();
Chris@325 102
Chris@325 103 /**
Chris@325 104 * Return true if the FileSource object is valid and no error
Chris@325 105 * occurred in looking up the file or remote URL. Non-existence
Chris@325 106 * of the file or URL is not an error -- call isAvailable() to
Chris@325 107 * test for that.
Chris@325 108 */
Chris@325 109 bool isOK() const;
Chris@325 110
Chris@325 111 /**
Chris@325 112 * Return true if the file or remote URL exists. This may block
Chris@325 113 * on a sub-event-loop (calling waitForStatus) if the status is
Chris@325 114 * not yet available.
Chris@325 115 */
Chris@210 116 bool isAvailable();
Chris@210 117
Chris@325 118 /**
Chris@325 119 * Return true if the entire file has been retrieved and is
Chris@325 120 * available.
Chris@325 121 */
Chris@325 122 bool isDone() const;
Chris@316 123
Chris@325 124 /**
Chris@706 125 * Return true if this FileSource is referring to a QRC resource.
Chris@706 126 */
Chris@706 127 bool isResource() const;
Chris@706 128
Chris@706 129 /**
Chris@325 130 * Return true if this FileSource is referring to a remote URL.
Chris@325 131 */
Chris@325 132 bool isRemote() const;
Chris@325 133
Chris@325 134 /**
Chris@325 135 * Return the location filename or URL as passed to the
Chris@325 136 * constructor.
Chris@325 137 */
Chris@325 138 QString getLocation() const;
Chris@325 139
Chris@325 140 /**
Chris@325 141 * Return the name of the local file this FileSource refers to.
Chris@325 142 * This is the filename that should be used when reading normally
Chris@325 143 * from the FileSource. If the filename passed to the constructor
Chris@325 144 * was a local file, this will return the same filename; otherwise
Chris@325 145 * this will be the name of the temporary cache file owned by the
Chris@325 146 * FileSource.
Chris@325 147 */
Chris@325 148 QString getLocalFilename() const;
Chris@325 149
Chris@325 150 /**
Chris@678 151 * Return the base name, i.e. the final path element (including
Chris@678 152 * extension, if any) of the location.
Chris@678 153 */
Chris@678 154 QString getBasename() const;
Chris@678 155
Chris@678 156 /**
Chris@325 157 * Return the MIME content type of this file, if known.
Chris@325 158 */
Chris@325 159 QString getContentType() const;
Chris@325 160
Chris@325 161 /**
Chris@325 162 * Return the file extension for this file, if any.
Chris@325 163 */
Chris@325 164 QString getExtension() const;
Chris@325 165
Chris@325 166 /**
Chris@325 167 * Return an error message, if isOK() is false.
Chris@325 168 */
Chris@325 169 QString getErrorString() const;
Chris@325 170
Chris@325 171 /**
Chris@325 172 * Specify whether any local, cached file should remain on disc
Chris@325 173 * after this FileSource has been destroyed. The default is false
Chris@469 174 * (cached files share their FileSource owners' lifespans).
Chris@325 175 */
Chris@316 176 void setLeaveLocalFile(bool leave);
Chris@208 177
Chris@325 178 /**
Chris@325 179 * Return true if the given filename or URL refers to a remote
Chris@325 180 * URL.
Chris@325 181 */
Chris@325 182 static bool isRemote(QString fileOrUrl);
Chris@210 183
Chris@325 184 /**
Chris@325 185 * Return true if FileSource can handle the retrieval scheme for
Chris@325 186 * the given URL (or if the URL is for a local file).
Chris@325 187 */
Chris@208 188 static bool canHandleScheme(QUrl url);
Chris@208 189
Chris@208 190 signals:
Chris@325 191 /**
Chris@325 192 * Emitted during URL retrieval, when the retrieval progress
Chris@325 193 * notches up to a new percentage.
Chris@325 194 */
Chris@208 195 void progress(int percent);
Chris@325 196
Chris@325 197 /**
Chris@325 198 * Emitted when the file's existence has been tested and/or
Chris@325 199 * response header received. Calls to isAvailable() after this
Chris@325 200 * has been emitted will not block.
Chris@325 201 */
Chris@325 202 void statusAvailable();
Chris@325 203
Chris@325 204 /**
Chris@325 205 * Emitted when the entire file data has been retrieved and the
Chris@325 206 * local file is complete (if no error has occurred).
Chris@325 207 */
Chris@208 208 void ready();
Chris@208 209
Chris@208 210 protected slots:
Chris@764 211 void metaDataChanged();
Chris@762 212 void readyRead();
Chris@762 213 void replyFailed(QNetworkReply::NetworkError);
Chris@762 214 void replyFinished();
Chris@762 215 void downloadProgress(qint64 done, qint64 total);
Chris@210 216 void cancelled();
Chris@208 217
Chris@208 218 protected:
Chris@317 219 FileSource &operator=(const FileSource &); // not provided
Chris@316 220
chris@831 221 QString m_rawFileOrUrl;
Chris@304 222 QUrl m_url;
Chris@208 223 QFile *m_localFile;
Chris@762 224 QNetworkReply *m_reply;
Chris@208 225 QString m_localFilename;
Chris@208 226 QString m_errorString;
Chris@315 227 QString m_contentType;
Chris@520 228 QString m_preferredContentType;
Chris@208 229 bool m_ok;
Chris@210 230 int m_lastStatus;
Chris@706 231 bool m_resource;
Chris@316 232 bool m_remote;
Chris@208 233 bool m_done;
Chris@316 234 bool m_leaveLocalFile;
Chris@392 235 ProgressReporter *m_reporter;
Chris@208 236
Chris@304 237 typedef std::map<QUrl, int> RemoteRefCountMap;
Chris@304 238 typedef std::map<QUrl, QString> RemoteLocalMap;
Chris@304 239 static RemoteRefCountMap m_refCountMap;
Chris@304 240 static RemoteLocalMap m_remoteLocalMap;
Chris@304 241 static QMutex m_mapMutex;
Chris@316 242 bool m_refCounted;
Chris@316 243
Chris@357 244 void init();
Chris@762 245 void initRemote();
Chris@304 246
Chris@211 247 void cleanup();
Chris@211 248
Chris@316 249 // Create a local file for m_url. If it already existed, return true.
Chris@316 250 // The local filename is stored in m_localFilename.
Chris@316 251 bool createCacheFile();
Chris@316 252 void deleteCacheFile();
Chris@208 253
Chris@208 254 static QMutex m_fileCreationMutex;
Chris@208 255 static int m_count;
Chris@208 256 };
Chris@208 257
Chris@208 258 #endif