Andrew Zambazos
106 lines
4.5 KiB
C++
106 lines
4.5 KiB
C++
/**************************************************************************************************
|
|
* This file is a part of Ultralight. *
|
|
* *
|
|
* See <https://ultralig.ht> for licensing and more. *
|
|
* *
|
|
* (C) 2024 Ultralight, Inc. *
|
|
**************************************************************************************************/
|
|
#pragma once
|
|
#include <Ultralight/Defines.h>
|
|
#include <Ultralight/String.h>
|
|
#include <Ultralight/Buffer.h>
|
|
|
|
namespace ultralight {
|
|
|
|
///
|
|
/// User-defined file system interface.
|
|
///
|
|
/// The library uses this to load file data (ie, raw file bytes) for a given file URL
|
|
/// (eg, `file:///page.html`) .
|
|
///
|
|
/// You can provide the library with your own FileSystem implementation so that file data is
|
|
/// provided directly by your application (eg, from memory, from a virtual file system, etc).
|
|
///
|
|
/// ## Default Implementation
|
|
///
|
|
/// A platform-specific implementation of FileSystem is provided for you when you call
|
|
/// App::Create().
|
|
///
|
|
/// If you are using Renderer::Create(), you **must** provide your own. You can still use AppCore's
|
|
/// implementation however-- see the helper functions defined in <AppCore/Platform.h>.
|
|
///
|
|
/// ## Setting the File System
|
|
///
|
|
/// To provide your own custom FileSystem implementation, you should inherit from this class,
|
|
/// handle the virtual member functions, and then pass an instance of your class to
|
|
/// Platform::set_file_system() before calling Renderer::Create() or App::Create().
|
|
///
|
|
class UExport FileSystem {
|
|
public:
|
|
virtual ~FileSystem();
|
|
|
|
///
|
|
/// Check if a file exists within the file system.
|
|
///
|
|
/// @param file_path Relative file path (the string following the file:/// prefix)
|
|
///
|
|
/// @return Returns whether or not a file exists at the path specified.
|
|
///
|
|
virtual bool FileExists(const String& file_path) = 0;
|
|
|
|
///
|
|
/// Get the mime-type of a file (eg "text/html").
|
|
///
|
|
/// This is usually determined by analyzing the file extension.
|
|
///
|
|
/// If a mime-type cannot be determined, this should return "application/unknown".
|
|
///
|
|
/// @param file_path Relative file path (the string following the file:/// prefix)
|
|
///
|
|
/// @return Returns whether or not a file exists at the path specified.
|
|
///
|
|
virtual String GetFileMimeType(const String& file_path) = 0;
|
|
|
|
///
|
|
/// Get the charset / encoding of a file (eg "utf-8", "iso-8859-1").
|
|
///
|
|
/// @note This is only applicable for text-based files (eg, "text/html", "text/plain") and is
|
|
/// usually determined by analyzing the contents of the file.
|
|
///
|
|
/// @param file_path Relative file path (the string following the file:/// prefix)
|
|
///
|
|
/// @return Returns the charset of the specified file. If a charset cannot be determined, a safe
|
|
/// default to return is "utf-8".
|
|
///
|
|
virtual String GetFileCharset(const String& file_path) = 0;
|
|
|
|
///
|
|
/// Open a file for reading and map it to a Buffer.
|
|
///
|
|
/// To minimize copies, you should map the requested file into memory and use Buffer::Create()
|
|
/// to wrap the data pointer (unmapping should be performed in the destruction callback).
|
|
///
|
|
/// @note
|
|
/// \parblock
|
|
/// File data addresses returned from this function should generally be aligned to 16-byte
|
|
/// boundaries (the default alignment on most operating systems-- if you're using C stdlib or
|
|
/// C++ STL functions this is already handled for you).
|
|
///
|
|
/// This requirement is currently necessary when loading the ICU data file (eg, icudt67l.dat),
|
|
/// and may be relaxed for other files (but you may still see a performance benefit due to cache
|
|
/// line alignment).
|
|
///
|
|
/// If you can't guarantee alignment or are unsure, you can use Buffer::CreateFromCopy to copy
|
|
/// the file data content to an aligned block (at the expense of data duplication).
|
|
/// \endparblock
|
|
///
|
|
/// @param file_path Relative file path (the string following the file:/// prefix)
|
|
///
|
|
/// @return If the file was able to be opened, this returns a Buffer object representing the
|
|
/// contents of the file. If the file was unable to be opened, you should return nullptr.
|
|
///
|
|
virtual RefPtr<Buffer> OpenFile(const String& file_path) = 0;
|
|
};
|
|
|
|
} // namespace ultralight
|