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
0028   //! Returns a global file system, which a selector between registered file systems (OSD_FileSystemSelector).
0029   Standard_EXPORT static const Handle(OSD_FileSystem)& DefaultFileSystem();
0030
0031   //! Registers file system within the global file system selector returned by OSD_FileSystem::DefaultFileSystem().
0032   //! Note that registering protocols is not thread-safe operation and expected to be done once at application startup.
0033   //! @param[in] theFileSystem  file system to register
0034   //! @param[in] theIsPreferred add to the beginning of the list when TRUE, or add to the end otherwise
0035   Standard_EXPORT static void AddDefaultProtocol (const Handle(OSD_FileSystem)& theFileSystem, bool theIsPreferred = false);
0036
0037   //! Unregisters file system within the global file system selector returned by OSD_FileSystem::DefaultFileSystem().
0038   Standard_EXPORT static void RemoveDefaultProtocol (const Handle(OSD_FileSystem)& theFileSystem);
0039
0040 public:
0041
0042   //! Returns TRUE if URL defines a supported protocol.
0043   virtual Standard_Boolean IsSupportedPath (const TCollection_AsciiString& theUrl) const = 0;
0044
0045   //! Returns TRUE if current input stream is opened for reading operations.
0046   virtual Standard_Boolean IsOpenIStream (const std::shared_ptr<std::istream>& theStream) const = 0;
0047
0048   //! Returns TRUE if current output stream is opened for writing operations.
0049   virtual Standard_Boolean IsOpenOStream(const std::shared_ptr<std::ostream>& theStream) const = 0;
0050
0051   //! Opens stream for specified file URL for reading operations (std::istream).
0052   //! Default implementation create a stream from file buffer returned by OSD_FileSystem::OpenFileBuffer().
0053   //! @param theUrl       [in] path to open
0054   //! @param theMode      [in] flags describing the requested input mode for the stream (std::ios_base::in will be implicitly added)
0055   //! @param theOffset    [in] expected stream position from the beginning of the file (beginning of the stream by default);
0056   //!                          -1 would keep seek position undefined (in case of re-using theOldStream)
0057   //! @param theOldStream [in] a pointer to existing stream pointing to theUrl to be reused (without re-opening)
0058   //! @return pointer to newly created opened stream, to theOldStream if it can be reused or NULL in case of failure.
0059   Standard_EXPORT virtual std::shared_ptr<std::istream> OpenIStream
0060                           (const TCollection_AsciiString& theUrl,
0061                            const std::ios_base::openmode theMode,
0062                            const int64_t theOffset = 0,
0063                            const std::shared_ptr<std::istream>& theOldStream = std::shared_ptr<std::istream>());
0064
0065   //! Opens stream for specified file URL for writing operations (std::ostream).
0066   //! Default implementation create a stream from file buffer returned by OSD_FileSystem::OpenFileBuffer().
0067   //! @param theUrl       [in] path to open
0068   //! @param theMode      [in] flags describing the requested output mode for the stream (std::ios_base::out will be implicitly added)
0069   //! @return pointer to newly created opened stream or NULL in case of failure.
0070   Standard_EXPORT virtual std::shared_ptr<std::ostream> OpenOStream (const TCollection_AsciiString& theUrl,
0071                                                                      const std::ios_base::openmode theMode);
0072
0073   //! Opens stream buffer for specified file URL.
0074   //! @param theUrl        [in]  path to open
0075   //! @param theMode       [in]  flags describing the requested input mode for the stream
0076   //! @param theOffset     [in]  expected stream position from the beginning of the buffer (beginning of the stream buffer by default)
0077   //! @param theOutBufSize [out] total buffer size (only if buffer is opened for read)
0078   //! @return pointer to newly created opened stream buffer or NULL in case of failure.
0079   virtual std::shared_ptr<std::streambuf> OpenStreamBuffer (const TCollection_AsciiString& theUrl,
0080                                                             const std::ios_base::openmode theMode,
0081                                                             const int64_t theOffset = 0,
0082                                                             int64_t* theOutBufSize = NULL) = 0;
0083
0084   //! Constructor.
0085   Standard_EXPORT OSD_FileSystem();
0086
0087   //! Destructor.
0088   Standard_EXPORT virtual ~OSD_FileSystem();
0089 };
0090 #endif // _OSD_FileSystem_HeaderFile