Initial commit

engines/ags/engine/ac/path_helper.h

@@ -0,0 +1,126 @@
+/* ScummVM - Graphic Adventure Engine
+ *
+ * ScummVM is the legal property of its developers, whose names
+ * are too numerous to list here. Please refer to the COPYRIGHT
+ * file distributed with this source distribution.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+//=============================================================================
+//
+// Functions related to constructing game and script paths.
+//
+// TODO: We need some kind of a "file manager" which deals with opening files
+// in defined set of directories. To ensure that rest of the engine code does
+// not work with explicit paths or creates directories on its own.
+//
+//=============================================================================
+
+#ifndef AGS_ENGINE_AC_PATH_HELPER_H
+#define AGS_ENGINE_AC_PATH_HELPER_H
+
+#include "ags/shared/util/path.h"
+
+namespace AGS3 {
+
+using AGS::Shared::String;
+
+// Filepath tokens, which are replaced by platform-specific directory names
+extern const char *UserSavedgamesRootToken;
+extern const char *GameSavedgamesDirToken;
+extern const char *GameDataDirToken;
+extern const char *DefaultConfigFileName;
+
+// Subsitutes illegal characters with '_'. This function uses illegal chars array
+// specific to current platform.
+void FixupFilename(char *filename);
+
+// FSLocation describes a file system location defined by two parts:
+// a secure path that engine does not own, and sub-path that it owns.
+// The meaning of this is that engine is only allowed to create
+// sub-path subdirectories, and only if secure path exists.
+struct FSLocation {
+	String BaseDir; // base directory, which we assume already exists; not our responsibility
+	String SubDir;  // sub-directory, relative to BaseDir
+	String FullDir; // full path to location
+	FSLocation() {}
+	FSLocation(const String &base) : BaseDir(base), FullDir(base) {
+	}
+	FSLocation(const String &base, const String &subdir)
+		: BaseDir(base), SubDir(subdir),
+		FullDir(AGS::Shared::Path::ConcatPaths(base, subdir)) {
+	}
+	inline bool IsValid() const {
+		return !FullDir.IsEmpty();
+	}
+	// Concats the given path to the existing full dir
+	inline FSLocation Concat(const String &path) const {
+		return FSLocation(BaseDir, AGS::Shared::Path::ConcatPaths(FullDir, path));
+	}
+	// Sets full path as a relative to the existing base dir
+	inline FSLocation Rebase(const String &path) const {
+		return FSLocation(BaseDir, AGS::Shared::Path::ConcatPaths(BaseDir, path));
+	}
+};
+// Tests the input path, if it's an absolute path then returns it unchanged;
+// if it's a relative path then resolves it into absolute, using install dir as a base.
+String PathFromInstallDir(const String &path);
+FSLocation PathFromInstallDir(const FSLocation &fsloc);
+// Makes sure that given system location is available, makes directories if have to (and if it's allowed to)
+// Returns full file path on success, empty string on failure.
+String PreparePathForWriting(const FSLocation &fsloc, const String &filename);
+
+// Following functions calculate paths to directories according to game setup
+// Returns the directory where global user config is to be found
+FSLocation GetGlobalUserConfigDir();
+// Returns the directory where this game's user config is to be found
+FSLocation GetGameUserConfigDir();
+// Returns the directory where this game's shared app files are to be found
+FSLocation GetGameAppDataDir();
+// Returns the directory where this game's saves and user data are to be found
+FSLocation GetGameUserDataDir();
+
+// ResolvedPath describes an actual location pointed by a user path (e.g. from script)
+struct ResolvedPath {
+	FSLocation Loc;  // location (directory)
+	String FullPath; // full path, including filename
+	String AltPath;  // alternative read-only full path, for backwards compatibility
+	bool AssetMgr = false; // file is to be accessed through the asset manager
+	ResolvedPath() = default;
+	ResolvedPath(const String & file, const String & alt = "")
+		: FullPath(file), AltPath(alt) {
+	}
+	ResolvedPath(const FSLocation & loc, const String & file, const String & alt = "")
+		: Loc(loc), FullPath(AGS::Shared::Path::ConcatPaths(loc.FullDir, file)), AltPath(alt) {
+	}
+};
+// Resolves a file path provided by user (e.g. script) into actual file path,
+// by substituting special keywords with actual platform-specific directory names.
+// Fills in ResolvedPath object on success.
+// Returns 'true' on success, and 'false' if either path is impossible to resolve
+// or if the file path is forbidden to be accessed in current situation.
+bool ResolveScriptPath(const String &sc_path, bool read_only, ResolvedPath &rp);
+// Resolves a user file path for writing, and makes sure all the sub-directories are
+// created along the actual path.
+// Returns 'true' on success, and 'false' if either path is impossible to resolve,
+// forbidden for writing, or if failed to create any subdirectories.
+bool ResolveWritePathAndCreateDirs(const String &sc_path, ResolvedPath &rp);
+// Creates all necessary subdirectories inside the safe parent location.
+bool CreateFSDirs(const FSLocation &fs);
+
+} // namespace AGS3
+
+#endif