svcore  1.9
FileSource Class Reference

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. More...

#include <FileSource.h>

Collaboration diagram for FileSource:

List of all members.

Signals

void progress (int percent)
 Emitted during URL retrieval, when the retrieval progress notches up to a new percentage.
void statusAvailable ()
 Emitted when the file's existence has been tested and/or response header received.
void ready ()
 Emitted when the entire file data has been retrieved and the local file is complete (if no error has occurred).

Public Member Functions

 FileSource (QString fileOrUrl, ProgressReporter *reporter=0, QString preferredContentType="")
 Construct a FileSource using the given local file path or URL.
 FileSource (QUrl url, ProgressReporter *reporter=0)
 Construct a FileSource using the given remote URL.
 FileSource (const FileSource &)
virtual ~FileSource ()
void waitForStatus ()
 Block on a sub-event-loop until the availability of the file or remote URL is known.
void waitForData ()
 Block on a sub-event-loop until the whole of the data has been retrieved (if it is remote).
bool isOK () const
 Return true if the FileSource object is valid and neither error nor cancellation occurred while retrieving the file or remote URL.
bool isAvailable ()
 Return true if the file or remote URL exists.
bool isDone () const
 Return true if the entire file has been retrieved and is available.
bool wasCancelled () const
 Return true if the operation was cancelled by the user through the ProgressReporter interface.
bool isResource () const
 Return true if this FileSource is referring to a QRC resource.
bool isRemote () const
 Return true if this FileSource is referring to a remote URL.
QString getLocation () const
 Return the location filename or URL as passed to the constructor.
QString getLocalFilename () const
 Return the name of the local file this FileSource refers to.
QString getBasename () const
 Return the base name, i.e.
QString getContentType () const
 Return the MIME content type of this file, if known.
QString getExtension () const
 Return the file extension for this file, if any.
QString getErrorString () const
 Return an error message, if isOK() is false.
void setLeaveLocalFile (bool leave)
 Specify whether any local, cached file should remain on disc after this FileSource has been destroyed.

Static Public Member Functions

static bool isRemote (QString fileOrUrl)
 Return true if the given filename or URL refers to a remote URL.
static bool canHandleScheme (QUrl url)
 Return true if FileSource can handle the retrieval scheme for the given URL (or if the URL is for a local file).

Protected Types

typedef std::map< QUrl, int > RemoteRefCountMap
typedef std::map< QUrl, QString > RemoteLocalMap

Protected Slots

void metaDataChanged ()
void readyRead ()
void replyFailed (QNetworkReply::NetworkError)
void replyFinished ()
void downloadProgress (qint64 done, qint64 total)
void cancelled ()

Protected Member Functions

FileSourceoperator= (const FileSource &)
void init ()
void initRemote ()
void cleanup ()
bool createCacheFile ()
void deleteCacheFile ()

Protected Attributes

QString m_rawFileOrUrl
QUrl m_url
QFile * m_localFile
QNetworkReply * m_reply
QString m_localFilename
QString m_errorString
QString m_contentType
QString m_preferredContentType
bool m_ok
bool m_cancelled
int m_lastStatus
bool m_resource
bool m_remote
bool m_done
bool m_leaveLocalFile
ProgressReporterm_reporter
bool m_refCounted

Static Protected Attributes

static RemoteRefCountMap m_refCountMap
static RemoteLocalMap m_remoteLocalMap
static QMutex m_mapMutex
static QMutex m_fileCreationMutex
static int m_count = 0

Detailed Description

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.

Definition at line 59 of file FileSource.h.


Member Typedef Documentation

typedef std::map<QUrl, int> FileSource::RemoteRefCountMap [protected]

Definition at line 246 of file FileSource.h.

typedef std::map<QUrl, QString> FileSource::RemoteLocalMap [protected]

Definition at line 247 of file FileSource.h.


Constructor & Destructor Documentation

FileSource::FileSource ( QString  fileOrUrl,
ProgressReporter reporter = 0,
QString  preferredContentType = "" 
)

Construct a FileSource using the given local file path or URL.

The URL may be raw or encoded.

If a ProgressReporter is provided, it will be updated with progress status. Note that the progress() signal will also be emitted regularly during retrieval, even if no reporter is supplied here. Caller retains ownership of the reporter object.

Definition at line 73 of file FileSource.cpp.

References canHandleScheme(), deleteCacheFile(), init(), isAvailable(), isRemote(), m_done, m_errorString, m_lastStatus, m_ok, m_resource, m_url, ready(), statusAvailable(), and waitForStatus().

FileSource::FileSource ( QUrl  url,
ProgressReporter reporter = 0 
)

Construct a FileSource using the given remote URL.

If a ProgressReporter is provided, it will be updated with progress status. Note that the progress() signal will also be emitted regularly during retrieval, even if no reporter is supplied here. Caller retains ownership of the reporter object.

Definition at line 166 of file FileSource.cpp.

References canHandleScheme(), init(), m_errorString, and m_url.

FileSource::~FileSource ( ) [virtual]

Definition at line 256 of file FileSource.cpp.

References cleanup(), deleteCacheFile(), isRemote(), m_leaveLocalFile, and m_url.


Member Function Documentation

Block on a sub-event-loop until the availability of the file or remote URL is known.

Definition at line 540 of file FileSource.cpp.

References m_done, m_lastStatus, and m_ok.

Referenced by FileSource(), and isAvailable().

Block on a sub-event-loop until the whole of the data has been retrieved (if it is remote).

Definition at line 549 of file FileSource.cpp.

References m_done, and m_ok.

Referenced by RDFImporterImpl::getDataModelsAudio(), PlaylistFileReader::init(), CachedFile::retrieve(), and WaveFileModel::WaveFileModel().

bool FileSource::isOK ( ) const

Return true if the FileSource object is valid and neither error nor cancellation occurred while retrieving the file or remote URL.

Non-existence of the file or URL is not an error -- call isAvailable() to test for that.

Definition at line 565 of file FileSource.cpp.

References m_ok.

Referenced by AudioFileReaderFactory::create(), CachedFile::retrieve(), and WaveFileModel::WaveFileModel().

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.

Definition at line 523 of file FileSource.cpp.

References m_lastStatus, m_ok, and waitForStatus().

Referenced by AudioFileReaderFactory::create(), FileSource(), RDFImporterImpl::getDataModelsAudio(), PlaylistFileReader::init(), PlaylistFileReader::PlaylistFileReader(), and CachedFile::retrieve().

bool FileSource::isDone ( ) const

Return true if the entire file has been retrieved and is available.

Definition at line 571 of file FileSource.cpp.

References m_done.

bool FileSource::wasCancelled ( ) const

Return true if the operation was cancelled by the user through the ProgressReporter interface.

Note that the cancelled() signal will have been emitted, and isOK() will also return false in this case.

Definition at line 577 of file FileSource.cpp.

References m_cancelled.

bool FileSource::isResource ( ) const

Return true if this FileSource is referring to a QRC resource.

Definition at line 583 of file FileSource.cpp.

References m_resource.

Referenced by init().

bool FileSource::isRemote ( ) const

Return true if this FileSource is referring to a remote URL.

Definition at line 589 of file FileSource.cpp.

References m_remote.

Referenced by deleteCacheFile(), FileSource(), PlaylistFileReader::init(), init(), PlaylistFileReader::load(), PluginRDFIndexer::pullURL(), and ~FileSource().

QString FileSource::getLocalFilename ( ) 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.

Definition at line 601 of file FileSource.cpp.

References m_localFilename.

Referenced by RDFImporterImpl::getDataModelsAudio(), PlaylistFileReader::init(), and CachedFile::retrieve().

QString FileSource::getBasename ( ) const

Return the base name, i.e.

the final path element (including extension, if any) of the location.

Definition at line 607 of file FileSource.cpp.

References m_localFilename.

QString FileSource::getContentType ( ) const

Return the MIME content type of this file, if known.

Definition at line 613 of file FileSource.cpp.

References m_contentType.

Referenced by AudioFileReaderFactory::create(), WavFileReader::supports(), MP3FileReader::supports(), and OggVorbisFileReader::supports().

QString FileSource::getExtension ( ) const

Return the file extension for this file, if any.

Definition at line 619 of file FileSource.cpp.

References m_localFilename, and m_url.

Referenced by WavFileReader::supports(), MP3FileReader::supports(), and OggVorbisFileReader::supports().

QString FileSource::getErrorString ( ) const

Return an error message, if isOK() is false.

Definition at line 629 of file FileSource.cpp.

References m_errorString.

Referenced by AudioFileReaderFactory::create().

void FileSource::setLeaveLocalFile ( bool  leave)

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).

Definition at line 559 of file FileSource.cpp.

References m_leaveLocalFile.

bool FileSource::isRemote ( QString  fileOrUrl) [static]

Return true if the given filename or URL refers to a remote URL.

Definition at line 504 of file FileSource.cpp.

bool FileSource::canHandleScheme ( QUrl  url) [static]

Return true if FileSource can handle the retrieval scheme for the given URL (or if the URL is for a local file).

Definition at line 513 of file FileSource.cpp.

Referenced by FileSource(), and PluginRDFIndexer::pullURL().

void FileSource::progress ( int  percent) [signal]

Emitted during URL retrieval, when the retrieval progress notches up to a new percentage.

Referenced by downloadProgress(), init(), replyFailed(), and replyFinished().

void FileSource::statusAvailable ( ) [signal]

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.

Referenced by FileSource(), and metaDataChanged().

void FileSource::ready ( ) [signal]

Emitted when the entire file data has been retrieved and the local file is complete (if no error has occurred).

Referenced by FileSource(), replyFailed(), and replyFinished().

void FileSource::readyRead ( ) [protected, slot]

Definition at line 635 of file FileSource.cpp.

References m_localFile, and m_reply.

Referenced by initRemote().

void FileSource::replyFailed ( QNetworkReply::NetworkError  ) [protected, slot]

Definition at line 773 of file FileSource.cpp.

References cleanup(), m_done, m_errorString, m_ok, m_reply, progress(), and ready().

Referenced by initRemote().

void FileSource::replyFinished ( ) [protected, slot]
void FileSource::downloadProgress ( qint64  done,
qint64  total 
) [protected, slot]

Definition at line 709 of file FileSource.cpp.

References progress().

Referenced by initRemote().

void FileSource::cancelled ( ) [protected, slot]

Definition at line 716 of file FileSource.cpp.

References cleanup(), m_cancelled, m_done, m_errorString, and m_ok.

Referenced by init().

FileSource& FileSource::operator= ( const FileSource ) [protected]
void FileSource::cleanup ( ) [protected]

Member Data Documentation

QString FileSource::m_rawFileOrUrl [protected]

Definition at line 229 of file FileSource.h.

Referenced by init().

QFile* FileSource::m_localFile [protected]

Definition at line 231 of file FileSource.h.

Referenced by cleanup(), init(), metaDataChanged(), readyRead(), and replyFinished().

QNetworkReply* FileSource::m_reply [protected]

Definition at line 232 of file FileSource.h.

Referenced by cleanup(), initRemote(), metaDataChanged(), readyRead(), and replyFailed().

QString FileSource::m_contentType [protected]

Definition at line 235 of file FileSource.h.

Referenced by getContentType(), and metaDataChanged().

Definition at line 236 of file FileSource.h.

Referenced by initRemote().

bool FileSource::m_cancelled [protected]

Definition at line 238 of file FileSource.h.

Referenced by cancelled(), and wasCancelled().

int FileSource::m_lastStatus [protected]
bool FileSource::m_resource [protected]

Definition at line 240 of file FileSource.h.

Referenced by FileSource(), init(), and isResource().

bool FileSource::m_remote [protected]

Definition at line 241 of file FileSource.h.

Referenced by init(), and isRemote().

bool FileSource::m_leaveLocalFile [protected]

Definition at line 243 of file FileSource.h.

Referenced by setLeaveLocalFile(), and ~FileSource().

Definition at line 244 of file FileSource.h.

Referenced by init().

Definition at line 249 of file FileSource.h.

Referenced by createCacheFile(), FileSource(), and init().

QMutex FileSource::m_mapMutex [static, protected]

Definition at line 250 of file FileSource.h.

Referenced by createCacheFile(), deleteCacheFile(), FileSource(), and init().

bool FileSource::m_refCounted [protected]

Definition at line 251 of file FileSource.h.

Referenced by createCacheFile(), deleteCacheFile(), FileSource(), init(), and metaDataChanged().

QMutex FileSource::m_fileCreationMutex [static, protected]

Definition at line 263 of file FileSource.h.

Referenced by createCacheFile(), and deleteCacheFile().

int FileSource::m_count = 0 [static, protected]

Definition at line 264 of file FileSource.h.

Referenced by createCacheFile().


The documentation for this class was generated from the following files: