include/opencascade/OSD_FileSystem.hxx

0001 // Copyright (c) 2021 OPEN CASCADE SAS
0002 //
0003 // This file is part of Open CASCADE Technology software library.
0004 //
0005 // This library is free software; you can redistribute it and/or modify it under
0006 // the terms of the GNU Lesser General Public License version 2.1 as published
0007 // by the Free Software Foundation, with special exception defined in the file
0008 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0009 // distribution for complete text of the license and disclaimer of any warranty.
0010 //
0011 // Alternatively, this file may be used under the terms of Open CASCADE
0012 // commercial license or contractual agreement.
0013
0014 #ifndef _OSD_FileSystem_HeaderFile
0015 #define _OSD_FileSystem_HeaderFile
0016
0017 #include <OSD_StreamBuffer.hxx>
0018 #include <TCollection_AsciiString.hxx>
0019 #include <NCollection_DefineAlloc.hxx>
0020
0021 //! Base interface for a file stream provider.
0022 //! It is intended to be implemented for specific file protocol.
0023 class OSD_FileSystem : public Standard_Transient
0024 {
0025   DEFINE_STANDARD_RTTIEXT(OSD_FileSystem, Standard_Transient)
0026 public:
0027   //! Returns a global file system, which a selector between registered file systems
0028   //! (OSD_FileSystemSelector).
0029   Standard_EXPORT static const occ::handle<OSD_FileSystem>& DefaultFileSystem();
0030
0031   //! Registers file system within the global file system selector returned by
0032   //! OSD_FileSystem::DefaultFileSystem(). Note that registering protocols is not thread-safe
0033   //! operation and expected to be done once at application startup.
0034   //! @param[in] theFileSystem  file system to register
0035   //! @param[in] theIsPreferred add to the beginning of the list when TRUE, or add to the end
0036   //! otherwise
0037   Standard_EXPORT static void AddDefaultProtocol(const occ::handle<OSD_FileSystem>& theFileSystem,
0038                                                  bool theIsPreferred = false);
0039
0040   //! Unregisters file system within the global file system selector returned by
0041   //! OSD_FileSystem::DefaultFileSystem().
0042   Standard_EXPORT static void RemoveDefaultProtocol(
0043     const occ::handle<OSD_FileSystem>& theFileSystem);
0044
0045 public:
0046   //! Returns TRUE if URL defines a supported protocol.
0047   virtual bool IsSupportedPath(const TCollection_AsciiString& theUrl) const = 0;
0048
0049   //! Returns TRUE if current input stream is opened for reading operations.
0050   virtual bool IsOpenIStream(const std::shared_ptr<std::istream>& theStream) const = 0;
0051
0052   //! Returns TRUE if current output stream is opened for writing operations.
0053   virtual bool IsOpenOStream(const std::shared_ptr<std::ostream>& theStream) const = 0;
0054
0055   //! Opens stream for specified file URL for reading operations (std::istream).
0056   //! Default implementation create a stream from file buffer returned by
0057   //! OSD_FileSystem::OpenFileBuffer().
0058   //! @param[in] theUrl        path to open
0059   //! @param[in] theMode       flags describing the requested input mode for the stream
0060   //! (std::ios_base::in will be implicitly added)
0061   //! @param[in] theOffset     expected stream position from the beginning of the file (beginning of
0062   //! the stream by default);
0063   //!                          -1 would keep seek position undefined (in case of reusing
0064   //!                          theOldStream)
0065   //! @param[in] theOldStream  a pointer to existing stream pointing to theUrl to be reused (without
0066   //! re-opening)
0067   //! @return pointer to newly created opened stream, to theOldStream if it can be reused or NULL in
0068   //! case of failure.
0069   Standard_EXPORT virtual std::shared_ptr<std::istream> OpenIStream(
0070     const TCollection_AsciiString&       theUrl,
0071     const std::ios_base::openmode        theMode,
0072     const int64_t                        theOffset    = 0,
0073     const std::shared_ptr<std::istream>& theOldStream = std::shared_ptr<std::istream>());
0074
0075   //! Opens stream for specified file URL for writing operations (std::ostream).
0076   //! Default implementation create a stream from file buffer returned by
0077   //! OSD_FileSystem::OpenFileBuffer().
0078   //! @param[in] theUrl        path to open
0079   //! @param[in] theMode       flags describing the requested output mode for the stream
0080   //! (std::ios_base::out will be implicitly added)
0081   //! @return pointer to newly created opened stream or NULL in case of failure.
0082   Standard_EXPORT virtual std::shared_ptr<std::ostream> OpenOStream(
0083     const TCollection_AsciiString& theUrl,
0084     const std::ios_base::openmode  theMode);
0085
0086   //! Opens stream buffer for specified file URL.
0087   //! @param[in] theUrl          path to open
0088   //! @param[in] theMode         flags describing the requested input mode for the stream
0089   //! @param[in] theOffset       expected stream position from the beginning of the buffer
0090   //! (beginning of the stream buffer by default)
0091   //! @param[out] theOutBufSize  total buffer size (only if buffer is opened for read)
0092   //! @return pointer to newly created opened stream buffer or NULL in case of failure.
0093   virtual std::shared_ptr<std::streambuf> OpenStreamBuffer(const TCollection_AsciiString& theUrl,
0094                                                            const std::ios_base::openmode  theMode,
0095                                                            const int64_t theOffset = 0,
0096                                                            int64_t* theOutBufSize  = nullptr) = 0;
0097
0098   //! Constructor.
0099   Standard_EXPORT OSD_FileSystem();
0100
0101   //! Destructor.
0102   Standard_EXPORT ~OSD_FileSystem() override;
0103 };
0104 #endif // _OSD_FileSystem_HeaderFile