#pragma region CPL License
/*
Nuclex Native Framework
Copyright (C) 2002-2021 Nuclex Development Labs

This library is free software; you can redistribute it and/or
modify it under the terms of the IBM Common Public License as
published by the IBM Corporation; either version 1.0 of the
License, or (at your option) any later version.

This library 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
IBM Common Public License for more details.

You should have received a copy of the IBM Common Public
License along with this library
*/
#pragma endregion // CPL License

#ifndef NUCLEX_STORAGE_FILESYSTEM_FILEMANAGER_H
#define NUCLEX_STORAGE_FILESYSTEM_FILEMANAGER_H

#include "Nuclex/Storage/Config.h"

#include <memory>
#include <string>

namespace Nuclex { namespace Storage { namespace FileSystem {

  // ------------------------------------------------------------------------------------------- //

  class Container;
  class ContainerFileCodec;
  class ContainerFileCodecChain;
  class FileManagerBackend; // private implementation, no public header

  // ------------------------------------------------------------------------------------------- //

}}} // namespace Nuclex::Storage::FileSystem

namespace Nuclex { namespace Storage { namespace FileSystem {

  // ------------------------------------------------------------------------------------------- //

  /// <summary>Provides access to the machine's file system</summary>
  /// <remarks>
  ///   <para>
  ///     Through the file manager, you can access all of the relevant locations your
  ///     application would want to store data in. These locations may be mapped to different
  ///     places depending on the operating system the game is compiled for.
  ///   </para>
  ///   <para>
  ///     See the individual access methods for more information about what the individual
  ///     containers should be used for, but here's a short overview:
  ///   </para>
  ///   <para>
  ///     <list type="bullet">
  ///       <item>
  ///         <term>StaticData</term>
  ///         <description>
  ///           This is often identical with the game's install directory. It contains your
  ///           static data files and must not be written to.
  ///         </description>
  ///       </item>
  ///       <item>
  ///         <term>MachineSettings</term>
  ///         <description>
  ///           Settings that are specific to the machine the game is running on should be
  ///           stored here. For example, graphics/performance settings or controller ids.
  ///         </description>
  ///       </item>
  ///       <item>
  ///         <term>PlayerSettings</term>
  ///         <description>
  ///           You can store any player-specific settings in this container. This can be
  ///           key bindings, difficulty choice or HUD style, for example.
  ///         </description>
  ///       </item>
  ///       <item>
  ///         <term>PlayerData</term>
  ///         <description>
  ///           Data other than settings which is specific to the player. For example,
  ///           friends lists, high score tables and unlocked achievements.
  ///         </description>
  ///       </item>
  ///       <item>
  ///         <term>SavedGames</term>
  ///         <description>
  ///           As the name indicates, saved game states from which the player can resume
  ///           at a later time should be stored in this container.
  ///         </description>
  ///       </item>
  ///     </list>
  ///   </para>
  /// </remarks>
  class FileManager {

    //typedef std::shared_ptr<Container> SharedContainerPtr;
    //typedef std::shared_ptr<const Container> SharedConstContainerPtr;

    /// <summary>Initializes a new file system interface</summary>
    /// <param name="applicationName">Name of the running application</param>
    /// <remarks>
    ///   The application name will be used to create directories for locations where
    ///   directories are shared with other applications. Examples would be the user's
    ///   home directory on Linux or the Local and Roaming app data directories on Windows.
    /// </remarks>
    public: NUCLEX_STORAGE_API FileManager(const std::string &applicationName);

    /// <summary>Destroys the file system interface</summary>
    public: NUCLEX_STORAGE_API virtual ~FileManager();

    /// <summary>Returns the container for the application's static data location</summary>
    /// <returns>The container containing the application's static data files</returns>
    /// <remarks>
    ///   <para>
    ///     This container is read-only because many platforms will not allow you to
    ///     modify files in an application's install directory. You can access your
    ///     application's data files, resources and any other content that is shipped
    ///     together with your application's executable through this container.
    ///   </para>
    ///   <para>
    ///     On Linux systems, this container usually resolves to
    ///     <code>/opt/awesome-game/</code> but when installed via a package manager
    ///     may instead point to <code>/usr/share/games/awesome-game</code>.
    ///     On Windows systems, this container usually resolve to
    ///     <code>C:\Program Files\Awesome Game\</code>.
    ///   </para>
    /// </remarks>
    public: NUCLEX_STORAGE_API const std::shared_ptr<
      const Container
    > &GetStaticDataContainer() const {
      return this->staticDataContainer;
    }

#if 0 // Would map to /etc/opt/ on Linux and %ProgramData% on Windows, unsure if needed
    /// <summary>Returns a container in which system-specific settings can be stored</summary>
    /// <returns>A container for storage of system-specific settings</returns>
    /// <remarks>
    ///   <para>
    ///     This container should be used for configuration data relating to the machine
    ///     your game is being run on. The selected USB controller, GPU index or graphics
    ///     settings belong here.
    ///   </para>
    ///   <para>
    ///     With the exception of saved games, for which the special saved game container
    ///     accessible via <see cref="GetSavedGameContainer" /> should be used.
    ///   </para>
    ///   <para>
    ///     On Linux systems, this container usually resolves to
    ///     <code>/etc/opt/home/user/.config/awesome-game/</code>.
    ///     On Windows systems, this container usually resolves to
    ///     <code>C:\Users\UserName\AppData\Local\Awesome Game\</code>.
    ///   </para>
    ///   <para>
    ///     The above paths are not player-independent because using actual, global paths
    ///     here is not established practice. If you would still like to use machine-wide
    ///     directories, call <see cref="EnableMachineWideSettings" />.
    ///   </para>
    /// </remarks>
    public: NUCLEX_STORAGE_API std::shared_ptr<
      Container
    > &GetMachineSettingsContainer() const {
      return *this->machineSettingsContainer.get();
    }
#endif

    /// <summary>Returns a container in which player-specific settings can be stored</summary>
    /// <returns>A container for storage of player-specific settings</returns>
    /// <remarks>
    ///   <para>
    ///     This container should be used for configuration data relating to the player
    ///     (player profiles, key bindings and achievements for example) but not for
    ///     system-specific settings such as screen resolution or audio volume.
    ///     If a user has a roaming profile (one synchronized between multiple systems),
    ///     files in this container will be carried over to any systems he/she logs onto.
    ///   </para>
    ///   <para>
    ///     For saved games, use the special saved game container accessible via
    ///     <see cref="GetSaveGameContainer" />.
    ///   </para>
    ///   <para>
    ///     On Linux systems, this container usually resolves to
    ///     <code>/home/user/.config/awesome-game/settings/</code>.
    ///     On Windows systems, this container usually resolves to
    ///     <code>C:\Users\UserName\AppData\Roaming\Awesome Game\</code>.
    ///   </para>
    /// </remarks>
    public: NUCLEX_STORAGE_API const std::shared_ptr<
      Container
    > &GetPlayerSettingsContainer() const {
      return this->playerSettingsContainer;
    }

    /// <summary>Returns the container to use for storing saved game states</summary>
    /// <returns>The container in which saved game states should be stored</returns>
    /// <remarks>
    ///   <para>
    ///     The location of this container can be different depending on the operating system
    ///     on which the game runs. Some operating systems like Windows 7 and later provide
    ///     a special folder for saved games, so this will be used where available, otherwise
    ///     the file manager will tries to follow established practices.
    ///   </para>
    ///   <para>
    ///     You might also want to use this in order to make it easier to support cloud-stored
    ///     game saves (like in Steam) since you can easily derive a class from the FileManager
    ///     that provides an alternative location for the containers and use that instead.
    ///   </para>
    ///   <para>
    ///     On Linux systems, this container usually resolves to
    ///     <code>/home/user/.local/share/awesome-game/saves/</code>.
    ///     On Windows systems, this container usually resolves to
    ///     <code>C:\Users\UserName\Saved Games\Awesome Game\</code>.
    ///   </para>
    /// </remarks>
    public: NUCLEX_STORAGE_API const std::shared_ptr<
      Container
    > &GetSavedGameContainer() const {
      return this->savedGameContainer;
    }

#if 0
    /// <summary>Returns the container to use for storing computer-specific files</summary>
    /// <returns>The container in which computer-specified files can be stored</returns>
    /// <remarks>
    ///   Some settings, such as the chosen graphics adapter / 3D API, screen resolution,
    ///   details, etc. are only relevant to the system the application runs on and should not
    ///   be carried over if the same player logs in on another system.
    /// </remarks>
    public: NUCLEX_STORAGE_API Container &GetLocalContainer() const {
      return *this->localContainer.get();
    }


    /// <summary>Returns the container for a temporary location</summary>
    /// <returns>A container temporary files can be stored in</returns>
    /// <remarks>
    ///   Anything stored in this container may be erased at any time. Use it to cache
    ///   stuff that can be recreated, such as compiled shaders and scripts.
    /// </remarks>
    public: NUCLEX_STORAGE_API Container &GetTemporaryContainer() const {
      return *this->temporaryContainer.get();
    }
#endif

#if 0
    /// <summary>Accesses the container at the specified native path</summary>
    /// <param name="path">Path of  the container that will be accessed</param>
    /// <returns>The container at the specified native path</returns>
    public: virtual std::shared_ptr<Container> GetFromNativePath(
      const std::string &path
    ) const = 0;
#endif

#if 0
    /// <summary>
    ///   Registers a container file codec through which files can be opened as containers
    /// </summary>
    /// <param name="codec">Codec that will be registered to the file manager</param>
    /// <remarks>
    ///   <para>
    ///     Some files, like .zip archives for example, can contain other files themselves.
    ///     Within this library, these are referred to as &quot;container files&quot; and
    ///     can be supported in a transparent manner simply by adding a codec to
    ///     the file manager.
    ///   </para>
    ///   <para>
    ///     Once the codec is registered, any container files will enumerate as containers
    ///     and you will be able to access files and containers inside the container file
    ///     directly. The file manager already has a built-in container file codec for
    ///     .zip archives, so you can access files stored in these archives without prior
    ///     extraction or using a separate API.
    ///   </para>
    /// </remarks>
    public: NUCLEX_STORAGE_API virtual void RegisterContainerFileCodec(
      const std::shared_ptr<ContainerFileCodec> &codec
    );

    /// <summary>Registered codecs used to open files as containers</summary>
    protected: std::shared_ptr<ContainerFileCodecChain> Codecs;
#endif

    /// <summary>Container for the game's install directory</summary>
    private: std::shared_ptr<const Container> staticDataContainer;
    /// <summary>Container for player-specific settings</summary>
    private: std::shared_ptr<Container> playerSettingsContainer;
    /// <summary>Container for player-specific data</summary>
    private: std::unique_ptr<Container> playerDataContainer;
    /// <summary>Container in which saved games are stored</summary>
    private: std::shared_ptr<Container> savedGameContainer;

    /// <summary>Container in which temporary files can be stored</summary>
    private: std::unique_ptr<Container> temporaryContainer;

    /// <summary>Internal management of archive readers and open files</summary>
    private: std::unique_ptr<FileManagerBackend> backend;

  };

  // ------------------------------------------------------------------------------------------- //

}}} // namespace Nuclex::Storage::FileSystem

#endif // NUCLEX_STORAGE_FILESYSTEM_FILEMANAGER_H