1 /*************************************************************************** 2 qgsprojectstorage.h 3 -------------------------------------- 4 Date : March 2018 5 Copyright : (C) 2018 by Martin Dobias 6 Email : wonder dot sk at gmail dot com 7 *************************************************************************** 8 * * 9 * This program is free software; you can redistribute it and/or modify * 10 * it under the terms of the GNU General Public License as published by * 11 * the Free Software Foundation; either version 2 of the License, or * 12 * (at your option) any later version. * 13 * * 14 ***************************************************************************/ 15 16 #ifndef QGSPROJECTSTORAGE_H 17 #define QGSPROJECTSTORAGE_H 18 19 #include "qgis_core.h" 20 #include "qgis_sip.h" 21 22 #include <QDateTime> 23 #include <QString> 24 25 class QIODevice; 26 27 class QgsReadWriteContext; 28 29 /** 30 * \ingroup core 31 * \brief Abstract interface for project storage - to be implemented by various backends 32 * and registered in QgsProjectStorageRegistry. 33 * 34 * \since QGIS 3.2 35 */ 36 class CORE_EXPORT QgsProjectStorage 37 { 38 public: 39 40 /** 41 * \ingroup core 42 * \brief Metadata associated with a project 43 * \since QGIS 3.2 44 */ 45 class Metadata 46 { 47 public: 48 //! Name of the project - equivalent to a file's base name (i.e. without path and extension). 49 QString name; 50 //! Date and local time when the file was last modified. 51 QDateTime lastModified; 52 }; 53 54 virtual ~QgsProjectStorage() = default; 55 56 /** 57 * Unique identifier of the project storage type. If type() returns "memory", all project file names 58 * starting with "memory:" will have read/write redirected through that storage implementation. 59 */ 60 virtual QString type() = 0; 61 62 /** 63 * Returns TRUE if the specified \a uri is supported by the storage provider. 64 * 65 * \note This method does not actually test whether the \a uri contains projects, but 66 * rather it is a quick test to determine if it is possible that the uri may 67 * contain projects. 68 * 69 * \since QGIS 3.22 70 */ 71 virtual bool isSupportedUri( const QString &uri ) const; 72 73 //! Returns list of all projects for given URI (specific to each storage backend) 74 virtual QStringList listProjects( const QString &uri ) = 0; 75 76 /** 77 * Reads project file content stored in the backend at the specified URI to the given device 78 * (could be e.g. a temporary file or a memory buffer). The device is expected to be empty 79 * when passed to readProject() so that the method can write all data to it and then rewind 80 * it using seek(0) to make it ready for reading in QgsProject. 81 */ 82 virtual bool readProject( const QString &uri, QIODevice *device, QgsReadWriteContext &context ) = 0; 83 84 /** 85 * Writes project file content stored in given device (could be e.g. a temporary file or a memory buffer) 86 * using the backend to the specified URI. The device is expected to contain all project file data 87 * and having position at the start of the content when passed to writeProject() so that the method 88 * can read all data from it until it reaches its end. 89 */ 90 virtual bool writeProject( const QString &uri, QIODevice *device, QgsReadWriteContext &context ) = 0; 91 92 /** 93 * Removes an existing project at the given URI. Returns TRUE if the removal 94 * was successful. 95 */ 96 virtual bool removeProject( const QString &uri ) = 0; 97 98 /** 99 * Rename an existing project at the given URI to a different URI. Returns TRUE if renaming 100 * was successful. 101 */ renameProject(const QString & uri,const QString & uriNew)102 virtual bool renameProject( const QString &uri, const QString &uriNew ) { Q_UNUSED( uri ) Q_UNUSED( uriNew ); return false; } 103 104 /** 105 * Reads project metadata (e.g. last modified time) if this is supported by the storage implementation. 106 * Returns TRUE if the metadata were read with success. 107 */ readProjectStorageMetadata(const QString & uri,QgsProjectStorage::Metadata & metadata SIP_OUT)108 virtual bool readProjectStorageMetadata( const QString &uri, QgsProjectStorage::Metadata &metadata SIP_OUT ) { Q_UNUSED( uri ) Q_UNUSED( metadata ); return false; } 109 110 /** 111 * Extracts and returns the file path from a storage backend \a uri, filesystem-based storage 112 * backends should implement this method in order to support relative paths storage. 113 * The default implementation returns an empty string. 114 * \since QGIS 3.8.1 115 */ 116 virtual QString filePath( const QString &uri ); 117 118 /** 119 * Returns human-readable name of the storage. Used as the menu item text in QGIS. Empty name 120 * indicates that the storage does not implement GUI support (showLoadGui() and showSaveGui()). 121 * The name may be translatable and ideally unique as well. 122 * \deprecated since QGIS 3.10 - use QgsProjectStorageGuiProvider for GUI-related project storage functionality 123 */ visibleName()124 Q_DECL_DEPRECATED virtual QString visibleName() SIP_DEPRECATED { return QString(); } 125 126 /** 127 * Opens GUI to allow user to select a project to be loaded (GUI specific to this storage type). 128 * Returns project URI if user has picked a project or empty string if the GUI was canceled. 129 * \deprecated since QGIS 3.10 - use QgsProjectStorageGuiProvider for GUI-related project storage functionality 130 */ showLoadGui()131 Q_DECL_DEPRECATED virtual QString showLoadGui() SIP_DEPRECATED { return QString(); } 132 133 /** 134 * Opens GUI to allow user to select where a project should be saved (GUI specific to this storage type). 135 * Returns project URI if user has picked a destination or empty string if the GUI was canceled. 136 * \deprecated since QGIS 3.10 - use QgsProjectStorageGuiProvider for GUI-related project storage functionality 137 */ showSaveGui()138 Q_DECL_DEPRECATED virtual QString showSaveGui() SIP_DEPRECATED { return QString(); } 139 140 }; 141 142 #endif // QGSPROJECTSTORAGE_H 143