Added SDK

include/Ultralight/platform/FileSystem.h

@@ -0,0 +1,105 @@
+/**************************************************************************************************
+ *  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