libplatform/io/File.h - mp4v2 - Git at Google

 ///////////////////////////////////////////////////////////////////////////////
 //
 //  The contents of this file are subject to the Mozilla Public License
 //  Version 1.1 (the "License"); you may not use this file except in
 //  compliance with the License. You may obtain a copy of the License at
 //  http://www.mozilla.org/MPL/
 //
 //  Software distributed under the License is distributed on an "AS IS"
 //  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 //  License for the specific language governing rights and limitations
 //  under the License.
 //
 //  The Original Code is MP4v2.
 //
 //  The Initial Developer of the Original Code is Kona Blend.
 //  Portions created by Kona Blend are Copyright (C) 2008.
 //  All Rights Reserved.
 //
 //  Contributors:
 //      Kona Blend, kona8lend@@gmail.com
 //
 ///////////////////////////////////////////////////////////////////////////////

 #ifndef MP4V2_PLATFORM_IO_FILE_H
 #define MP4V2_PLATFORM_IO_FILE_H

 namespace mp4v2 { namespace platform { namespace io {

 ///////////////////////////////////////////////////////////////////////////////

 class MP4V2_EXPORT FileProvider
 {
 public:
     static FileProvider& standard();

 public:
     //! file operation mode flags
     enum Mode {
         MODE_UNDEFINED, //!< undefined
         MODE_READ,      //!< file may be read
         MODE_MODIFY,    //!< file may be read/written
         MODE_CREATE,    //!< file will be created/truncated for read/write
     };

     //! type used to represent all file sizes and offsets
     typedef int64_t Size;

 public:
     virtual ~FileProvider() { }

     virtual bool open( std::string name, Mode mode ) = 0;
     virtual bool seek( Size pos ) = 0;
     virtual bool read( void* buffer, Size size, Size& nin, Size maxChunkSize ) = 0;
     virtual bool write( const void* buffer, Size size, Size& nout, Size maxChunkSize ) = 0;
     virtual bool close() = 0;
     virtual bool getSize( Size& nout ) = 0;

 protected:
     FileProvider() { }
 };

 ///////////////////////////////////////////////////////////////////////////////
 ///
 /// File implementation.
 ///
 /// File objects model real filesystem files in a 1:1 releationship and always
 /// treated as binary; there are no translations of text content performed.
 ///
 /// The interface represents all sizes with a signed 64-bit value, thus
 /// the limit to this interface is 63-bits of size, roughly 9.22 million TB.
 ///
 ///////////////////////////////////////////////////////////////////////////////

 class MP4V2_EXPORT File : public FileProvider
 {
 public:
     ///////////////////////////////////////////////////////////////////////////
     //!
     //! Constructor.
     //!
     //! A new file object is constructed but not opened.
     //!
     //! @param name filename of file object, or empty-string.
 	//!  On Windows, this should be a UTF-8 encoded string.
     //!  On other platforms, it should be an 8-bit encoding that is
     //!  appropriate for the platform, locale, file system, etc.
     //!  (prefer to use UTF-8 when possible).
     //! @param mode bitmask specifying mode flags.
     //!     See #Mode for bit constants.
     //! @param provider a fileprovider instance. If NULL a standard file
     //!     provider will be used otherwise the supplied provider must be
     //!     new-allocated and will be delete'd via ~File().
     //!
     ///////////////////////////////////////////////////////////////////////////

     explicit File( std::string name = "", Mode mode = MODE_UNDEFINED, FileProvider* = NULL );

     ///////////////////////////////////////////////////////////////////////////
     //!
     //! Destructor.
     //!
     //! File object is destroyed. If the file is opened it is closed prior
     //! to destruction.
     //!
     ///////////////////////////////////////////////////////////////////////////

     ~File();

     ///////////////////////////////////////////////////////////////////////////
     //!
     //! Open file.
     //!
     //! @param name filename of file object, or empty-string to use #name.
 	//!     On Windows, this should be a UTF-8 encoded string.
     //!     On other platforms, it should be an 8-bit encoding that is
     //!     appropriate for the platform, locale, file system, etc.
     //!     (prefer to use UTF-8 when possible).
     //!
     //! @return true on failure, false on success.
     //!
     ///////////////////////////////////////////////////////////////////////////

     bool open( std::string name = "", Mode mode = MODE_UNDEFINED );

     ///////////////////////////////////////////////////////////////////////////
     //!
     //! Closes file.
     //!
     //! If the file has not been opened or is not considered the
     //! owner of a filehandle, no action is taken.
     //!
     //! @return true on failure, false on success.
     //!
     ///////////////////////////////////////////////////////////////////////////

     bool close();

     ///////////////////////////////////////////////////////////////////////////
     //!
     //! Set current file position in bytes.
     //!
     //! @param pos new file position in bytes.
     //!
     //! @return true on failure, false on success.
     //!
     ///////////////////////////////////////////////////////////////////////////

     bool seek( Size pos );

     ///////////////////////////////////////////////////////////////////////////
     //!
     //! Binary stream read.
     //!
     //! The function reads up to a maximum <b>size</b> bytes from file,
     //! storing them in <b>buffer</b>. The number of bytes actually read are
     //! returned in <b>nin</b>.
     //!
     //! @param buffer storage for data read from file.
     //! @param size maximum number of bytes to read from file.
     //! @param nin output indicating number of bytes read from file.
     //! @param maxChunkSize maximum chunk size for reads issued to operating
     //!     system or 0 for default.
     //!
     //! @return true on failure, false on success.
     //!
     ///////////////////////////////////////////////////////////////////////////

     bool read( void* buffer, Size size, Size& nin, Size maxChunkSize = 0 );

     ///////////////////////////////////////////////////////////////////////////
     //!
     //! Binary stream write.
     //!
     //! The function writes up to a maximum <b>size</b> bytes from
     //! <b>buffer</b> to file. The number of bytes actually written are
     //! returned in <b>nout</b>.
     //!
     //! @param buffer data to be written out to file.
     //! @param size maximum number of bytes to read from file.
     //! @param nout output indicating number of bytes written to file.
     //! @param maxChunkSize maximum chunk size for writes issued to operating
     //!     system or 0 for default.
     //!
     //! @return true on failure, false on success.
     //!
     ///////////////////////////////////////////////////////////////////////////

     bool write( const void* buffer, Size size, Size& nout, Size maxChunkSize = 0 );

     ///////////////////////////////////////////////////////////////////////////
     //!
     //! Get size of file in bytes.
     //!
     //! @param nout output indicating the size of the file in bytes.
     //!
     //! @return true on failure, false on success.
     //!
     ///////////////////////////////////////////////////////////////////////////

     bool getSize( Size& nout );

 private:
     std::string   _name;
     bool          _isOpen;
     Mode          _mode;
     Size          _size;
     Size          _position;
     FileProvider& _provider;

 public:
     const std::string& name;      //!< read-only: file pathname or empty-string if not applicable
     const bool&        isOpen;    //!< read-only: true if file is open
     const Mode&        mode;      //!< read-only: file mode
     const Size&        size;      //!< read-only: file size
     const Size&        position;  //!< read-only: file position

 public:
     void setName( const std::string& name );
     void setMode( Mode mode );
 };

 ///////////////////////////////////////////////////////////////////////////////

 class CustomFileProvider : public FileProvider
 {
 public:
     CustomFileProvider( const MP4FileProvider& );

     bool open( std::string name, Mode mode );
     bool seek( Size pos );
     bool read( void* buffer, Size size, Size& nin, Size maxChunkSize );
     bool write( const void* buffer, Size size, Size& nout, Size maxChunkSize );
     bool close();
     bool getSize( Size& nout );

 private:
     MP4FileProvider _call;
     void*           _handle;
 };

 ///////////////////////////////////////////////////////////////////////////////

 }}} // namespace mp4v2::platform::io

 #endif // MP4V2_PLATFORM_IO_FILE_H
	///////////////////////////////////////////////////////////////////////////////
	//
	// The contents of this file are subject to the Mozilla Public License
	// Version 1.1 (the "License"); you may not use this file except in
	// compliance with the License. You may obtain a copy of the License at
	// http://www.mozilla.org/MPL/
	//
	// Software distributed under the License is distributed on an "AS IS"
	// basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
	// License for the specific language governing rights and limitations
	// under the License.
	//
	// The Original Code is MP4v2.
	//
	// The Initial Developer of the Original Code is Kona Blend.
	// Portions created by Kona Blend are Copyright (C) 2008.
	// All Rights Reserved.
	//
	// Contributors:
	// Kona Blend, kona8lend@@gmail.com
	//
	///////////////////////////////////////////////////////////////////////////////

	#ifndef MP4V2_PLATFORM_IO_FILE_H
	#define MP4V2_PLATFORM_IO_FILE_H

	namespace mp4v2 { namespace platform { namespace io {

	///////////////////////////////////////////////////////////////////////////////

	class MP4V2_EXPORT FileProvider
	{
	public:
	static FileProvider& standard();

	public:
	//! file operation mode flags
	enum Mode {
	MODE_UNDEFINED, //!< undefined
	MODE_READ, //!< file may be read
	MODE_MODIFY, //!< file may be read/written
	MODE_CREATE, //!< file will be created/truncated for read/write
	};

	//! type used to represent all file sizes and offsets
	typedef int64_t Size;

	public:
	virtual ~FileProvider() { }

	virtual bool open( std::string name, Mode mode ) = 0;
	virtual bool seek( Size pos ) = 0;
	virtual bool read( void* buffer, Size size, Size& nin, Size maxChunkSize ) = 0;
	virtual bool write( const void* buffer, Size size, Size& nout, Size maxChunkSize ) = 0;
	virtual bool close() = 0;
	virtual bool getSize( Size& nout ) = 0;

	protected:
	FileProvider() { }
	};

	///////////////////////////////////////////////////////////////////////////////
	///
	/// File implementation.
	///
	/// File objects model real filesystem files in a 1:1 releationship and always
	/// treated as binary; there are no translations of text content performed.
	///
	/// The interface represents all sizes with a signed 64-bit value, thus
	/// the limit to this interface is 63-bits of size, roughly 9.22 million TB.
	///
	///////////////////////////////////////////////////////////////////////////////

	class MP4V2_EXPORT File : public FileProvider
	{
	public:
	///////////////////////////////////////////////////////////////////////////
	//!
	//! Constructor.
	//!
	//! A new file object is constructed but not opened.
	//!
	//! @param name filename of file object, or empty-string.
	//! On Windows, this should be a UTF-8 encoded string.
	//! On other platforms, it should be an 8-bit encoding that is
	//! appropriate for the platform, locale, file system, etc.
	//! (prefer to use UTF-8 when possible).
	//! @param mode bitmask specifying mode flags.
	//! See #Mode for bit constants.
	//! @param provider a fileprovider instance. If NULL a standard file
	//! provider will be used otherwise the supplied provider must be
	//! new-allocated and will be delete'd via ~File().
	//!
	///////////////////////////////////////////////////////////////////////////

	explicit File( std::string name = "", Mode mode = MODE_UNDEFINED, FileProvider* = NULL );

	///////////////////////////////////////////////////////////////////////////
	//!
	//! Destructor.
	//!
	//! File object is destroyed. If the file is opened it is closed prior
	//! to destruction.
	//!
	///////////////////////////////////////////////////////////////////////////

	~File();

	///////////////////////////////////////////////////////////////////////////
	//!
	//! Open file.
	//!
	//! @param name filename of file object, or empty-string to use #name.
	//! On Windows, this should be a UTF-8 encoded string.
	//! On other platforms, it should be an 8-bit encoding that is
	//! appropriate for the platform, locale, file system, etc.
	//! (prefer to use UTF-8 when possible).
	//!
	//! @return true on failure, false on success.
	//!
	///////////////////////////////////////////////////////////////////////////

	bool open( std::string name = "", Mode mode = MODE_UNDEFINED );

	///////////////////////////////////////////////////////////////////////////
	//!
	//! Closes file.
	//!
	//! If the file has not been opened or is not considered the
	//! owner of a filehandle, no action is taken.
	//!
	//! @return true on failure, false on success.
	//!
	///////////////////////////////////////////////////////////////////////////

	bool close();

	///////////////////////////////////////////////////////////////////////////
	//!
	//! Set current file position in bytes.
	//!
	//! @param pos new file position in bytes.
	//!
	//! @return true on failure, false on success.
	//!
	///////////////////////////////////////////////////////////////////////////

	bool seek( Size pos );

	///////////////////////////////////////////////////////////////////////////
	//!
	//! Binary stream read.
	//!
	//! The function reads up to a maximum <b>size</b> bytes from file,
	//! storing them in <b>buffer</b>. The number of bytes actually read are
	//! returned in <b>nin</b>.
	//!
	//! @param buffer storage for data read from file.
	//! @param size maximum number of bytes to read from file.
	//! @param nin output indicating number of bytes read from file.
	//! @param maxChunkSize maximum chunk size for reads issued to operating
	//! system or 0 for default.
	//!
	//! @return true on failure, false on success.
	//!
	///////////////////////////////////////////////////////////////////////////

	bool read( void* buffer, Size size, Size& nin, Size maxChunkSize = 0 );

	///////////////////////////////////////////////////////////////////////////
	//!
	//! Binary stream write.
	//!
	//! The function writes up to a maximum <b>size</b> bytes from
	//! <b>buffer</b> to file. The number of bytes actually written are
	//! returned in <b>nout</b>.
	//!
	//! @param buffer data to be written out to file.
	//! @param size maximum number of bytes to read from file.
	//! @param nout output indicating number of bytes written to file.
	//! @param maxChunkSize maximum chunk size for writes issued to operating
	//! system or 0 for default.
	//!
	//! @return true on failure, false on success.
	//!
	///////////////////////////////////////////////////////////////////////////

	bool write( const void* buffer, Size size, Size& nout, Size maxChunkSize = 0 );

	///////////////////////////////////////////////////////////////////////////
	//!
	//! Get size of file in bytes.
	//!
	//! @param nout output indicating the size of the file in bytes.
	//!
	//! @return true on failure, false on success.
	//!
	///////////////////////////////////////////////////////////////////////////

	bool getSize( Size& nout );

	private:
	std::string _name;
	bool _isOpen;
	Mode _mode;
	Size _size;
	Size _position;
	FileProvider& _provider;

	public:
	const std::string& name; //!< read-only: file pathname or empty-string if not applicable
	const bool& isOpen; //!< read-only: true if file is open
	const Mode& mode; //!< read-only: file mode
	const Size& size; //!< read-only: file size
	const Size& position; //!< read-only: file position

	public:
	void setName( const std::string& name );
	void setMode( Mode mode );
	};

	///////////////////////////////////////////////////////////////////////////////

	class CustomFileProvider : public FileProvider
	{
	public:
	CustomFileProvider( const MP4FileProvider& );

	bool open( std::string name, Mode mode );
	bool seek( Size pos );
	bool read( void* buffer, Size size, Size& nin, Size maxChunkSize );
	bool write( const void* buffer, Size size, Size& nout, Size maxChunkSize );
	bool close();
	bool getSize( Size& nout );

	private:
	MP4FileProvider _call;
	void* _handle;
	};

	///////////////////////////////////////////////////////////////////////////////

	}}} // namespace mp4v2::platform::io

	#endif // MP4V2_PLATFORM_IO_FILE_H