/**
 * @file XTPMemFile.h
 *
 * @copyright
 * (c) 1998-2025 Codejock Software, All Rights Reserved.
 *
 * This source file is the property of Codejock Software and must not be
 * redistributed by any means without the explicit written permission of
 * Codejock Software.
 *
 * The use of this source code is governed by the terms and conditions specified
 * in the Toolkit Pro license agreement. Codejock Software grants you, as a
 * single software developer, the limited right to use this software on one
 * computer only.
 *
 * Contact Information:
 * support@codejock.com
 * http://www.codejock.com
 *
 */

/** @cond */
#if !defined(__XTMEMFILE_H__)
#	define __XTMEMFILE_H__
/** @endcond */

#	if _MSC_VER > 1000
#		pragma once
#	endif // _MSC_VER > 1000

#	include "Common/Base/Diagnostic/XTPDisableNoisyWarnings.h"

/**
 * @brief
 * CXTPMemFile is a CMemFile derived class. It is used to create a CXTPMemFile
 * object to support memory files.
 * @details
 * These memory files behave like disk files except that the file is stored
 * in RAM rather than on disk. A memory file is useful for fast temporary
 * storage or for transferring raw bytes or serialized objects between
 * independent processes.
 *
 * CXTPMemFile objects can automatically allocate their own memory, or you
 * can attach your own memory block to the CXTPMemFile object by calling
 * Attach. In either case, memory for growing the memory file automatically
 * is allocated in nGrowBytes-sized increments if 'nGrowBytes' is not zero.
 *
 * The memory block will automatically be deleted upon destruction of the
 * CXTPMemFile object if the memory was originally allocated by the CXTPMemFile
 * object. Otherwise, you are responsible for de-allocating the memory you
 * attached to the object.
 *
 * You can access the memory block through the pointer supplied when you
 * detach it from the CXTPMemFile object by calling Detach.
 *
 * The most common use of CXTPMemFile is to create a CXTPMemFile object and
 * use it by calling CFile member functions. Note that creating a CXTPMemFile
 * automatically opens it: you do not call CFile::Open, which is only used
 * for disk files. Because CXTPMemFile doesn't use a disk file, the data
 * member CFile::m_hFile is not used and has no meaning.
 *
 * The CFile member functions Duplicate, LockRange, and UnlockRange are
 * not implemented for CXTPMemFile. If you call these functions on a CXTPMemFile
 * object, you will get a CNotSupportedException.
 *
 * CXTPMemFile uses the run-time library functions malloc, realloc, and
 * free to allocate, reallocate, and deallocate memory and the intrinsic
 * memcpy to block copy memory when reading and writing. If you would like
 * to change this behavior or the behavior when CXTPMemFile grows a file,
 * derive your own class from CXTPMemFile and override the appropriate functions.
 */
class _XTP_EXT_CLASS CXTPMemFile : public CMemFile
{
public:
	/**
	 * @brief
	 * Constructs a CXTPMemFile object. This overload opens an empty memory
	 * file. Note that the file is opened by the constructor and that you
	 * should not call CFile::Open.
	 * @param nGrowBytes   The memory allocation increment in bytes.
	 */
	CXTPMemFile(UINT nGrowBytes = 1024);

	/**
	 * @brief
	 * Constructs a CXTPMemFile object. This overload opens an empty memory
	 * file. Note that the file is opened by the constructor and that you
	 * should not call CFile::Open.
	 * @param nGrowBytes   The memory allocation increment in bytes.
	 * @param lpBuffer     Pointer to the buffer to be attached to CXTPMemFile.
	 * @param nBufferSize  An integer that specifies the size of the buffer in bytes.
	 */
	CXTPMemFile(BYTE* lpBuffer, UINT nBufferSize, UINT nGrowBytes = 0);

	/**
	 * @brief
	 * Constructs a CXTPMemFile object. This overload opens an empty memory
	 * file. Note that the file is opened by the constructor and that you
	 * should not call CFile::Open.
	 * @param lpszFileName A string that is the path to the desired file. The path
	 * can be relative, absolute, or a network name (UNC).
	 * @param uiOpenFlags  A UINT that defines the file's sharing and access mode.
	 * It specifies the action to take when opening the file. You
	 * can combine options by using the bitwise-OR (|) operator.
	 * One access permission and one share option are required.
	 * The modeCreate and modeNoInherit modes are optional. See the
	 * CFile constructor for a list of mode options.
	 */
	CXTPMemFile(LPCTSTR lpszFileName, UINT uiOpenFlags);

	/**
	 * @brief
	 * Destroys a CXTPMemFile object, handles cleanup and deallocation.
	 */
	virtual ~CXTPMemFile();

public:
	/**
	 * @brief
	 * This member function forces any data remaining in the file buffer
	 * to be written to the file. The use of Flush does not guarantee flushing
	 * of CArchive buffers. If you are using an archive, call CArchive::Flush
	 * first.
	 */
	virtual void Flush();

#	if _MSC_VER > 1200 // MFC 7.0
	using CMemFile::Open;
#	endif

	/**
	 * @brief
	 * This member function opens and loads a physical file into memory.
	 * @param lpszFileName Specifies a NULL-terminated string that is the path to
	 * the desired file.
	 * @param nOpenFlags   Specifies a UINT that defines the sharing and access mode in
	 * the file. It specifies the action to take when opening the
	 * file. You can combine options by using the bitwise-OR (|)
	 * operator. One access permission and one share option are
	 * required. The modeCreate and modeNoInherit modes are optional.
	 * See the CFile constructor for a list of mode options.
	 * @param pError       Specifies a pointer to an existing file-exception object
	 * that receives the status of a failed operation.
	 * @return
	 * true if successful, or false if it fails.
	 */
	virtual BOOL Open(LPCTSTR lpszFileName, UINT nOpenFlags, CFileException* pError = NULL);

	/**
	 * @brief
	 * This member function saves the contents of the memory to the disk
	 * and closes it.
	 */
	virtual void Close();

	/**
	 * @brief
	 * This member function reads a string.
	 * @param rString A CString reference to an object to receive the string
	 * that is read.
	 * @return
	 * TRUE if successful, or FALSE if there is an error.
	 */
	virtual BOOL ReadString(CString& rString);

	/**
	 * @brief
	 * This method writes data from a buffer to the file associated with
	 * the CArchive object. The terminating null character, \\0, is not written
	 * to the file, nor is a newline character automatically written.
	 * @param lpsz  Specifies a pointer to a buffer containing a NULL-terminated text
	 * string.
	 */
	virtual void WriteString(LPCTSTR lpsz);

#	if _MSC_VER > 1200 // MFC 7.0
	using CMemFile::Duplicate;
#	endif // MFC 7.0

	/**
	 * @brief
	 * This member function will initialize the CXTPMemFile object with
	 * the information specified in the 'fDuplicate' object.
	 * @param fDuplicate A pointer to a valid CFile object.
	 * @return
	 * true if successful, otherwise false.
	 */
	virtual bool Duplicate(CFile* fDuplicate);

	/**
	 * @brief
	 * This member function will initialize the CXTPMemFile object with
	 * the information specified in the 'fDuplicate' object.
	 * @param strDup A NULL-terminated string.
	 * @return
	 * true if successful, otherwise false.
	 */
	virtual bool Duplicate(LPCTSTR strDup);

	/**
	 * @brief
	 * This member function discards all changes to the file since Open()
	 * or last Flush().
	 * @return
	 * true if successful, otherwise false.
	 */
	virtual bool Discard();

	/**
	 * @brief
	 * This member function inserts any file and retrieves the length of
	 * the actual copied bytes.
	 * @param fSrc        A pointer to a valid CFile object.
	 * @param dwSourcePos Represents the source file position.
	 * @param dwDestPos   Represents the destination file position.
	 * @param dwBytes     Number of bytes to insert.
	 * @return
	 * A DWORD value that represents the length of the copied bytes.
	 */
	virtual DWORD Insert(CFile* fSrc, DWORD dwSourcePos, DWORD dwDestPos, DWORD dwBytes);

	/**
	 * @brief
	 * This member function inserts any file and retrieves the length of
	 * the actual copied bytes.
	 * @param strSrc      Specifies a NULL-terminated string that is the path
	 *                    to the desired file.
	 * @param dwSourcePos Represents the source file position.
	 * @param dwDestPos   Represents the destination file position.
	 * @param dwBytes     Number of bytes to insert.
	 * @return
	 * A DWORD value that represents the length of the copied bytes.
	 */
	virtual DWORD Insert(LPCTSTR strSrc, DWORD dwSourcePos, DWORD dwDestPos, DWORD dwBytes);

	/**
	 * @brief
	 * This member function extracts bytes to a file and retrieves the
	 * length of the actual copied bytes.
	 * @param fDest      A pointer to a valid CFile object.
	 * @param dwStartPos Represents the starting position.
	 * @param dwBytes    Number of bytes to extract.
	 * @return
	 * A DWORD value that represents the length of the copied bytes.
	 */
	virtual DWORD Extract(CFile* fDest, DWORD dwStartPos, DWORD dwBytes);

	/**
	 * @brief
	 * This member function extracts bytes to a file and retrieves the
	 * length of the actual copied bytes.
	 * @param strDest    Specifies a NULL-terminated string that is the path
	 *                   to the desired file.
	 * @param dwStartPos Represents the starting position.
	 * @param dwBytes    Number of bytes to extract.
	 * @return
	 * A DWORD value that represents the length of the copied bytes.
	 */
	virtual DWORD Extract(LPCTSTR strDest, DWORD dwStartPos, DWORD dwBytes);

	/**
	 * @brief
	 * This member function finds data in the file.
	 * @param pData     Pointer to the buffer to receive the data found.
	 * @param dwDataLen Size of the data to find.
	 * @param lStartPos Starting position.
	 * @return
	 * A LONG data type.
	 */
	LONG FindData(void* pData, DWORD dwDataLen, LONG lStartPos);

	/**
	 * @brief
	 * This member operator will initialize the CXTPMemFile object with
	 * the object specified by 'fDup'.
	 * @param fDup A pointer to a valid CFile object.
	 */
	void operator=(CFile* fDup);

	/**
	 * @brief
	 * This member operator will initialize the CXTPMemFile object with
	 * the object specified by 'strDup'.
	 * @param strDup Specifies a NULL-terminated string that is the path to
	 * the desired file.
	 */
	void operator=(CString strDup);

	/**
	 * @brief
	 * This member operator will adjust the file position.
	 * @param dwFilePos A DWORD value that specifies the file position.
	 */
	void operator=(DWORD dwFilePos);

	/**
	 * @brief
	 * This member operator will append the CXTPMemFile object with the
	 * object specified by 'fApp'.
	 * @param fApp A pointer to a valid CFile object.
	 */
	void operator+=(CFile* fApp);

	/**
	 * @brief
	 * This member operator will append the CXTPMemFile object with the
	 * object specified by 'strApp'.
	 * @param strApp Specifies a NULL-terminated string that is the path to
	 * the desired file.
	 */
	void operator+=(CString strApp);

	/**
	 * @brief
	 * This member operator will perform indexing operations for the
	 * CXTPMemFile object.
	 * @param dwFilePos A DWORD value that specifies the file position.
	 * @return
	 * A BYTE data type.
	 */
	BYTE operator[](DWORD dwFilePos);

protected:
	/**
	 * @brief
	 * This member function loads the file into memory.
	 * @return
	 * true if successful, otherwise false.
	 */
	virtual bool Load();

	/**
	 * @brief
	 * This member function saves the file to disk.
	 * @return
	 * true if successful, otherwise false.
	 */
	virtual bool Save();

	/**
	 * @brief
	 * This member function imports the data of a CFile derived object
	 * (operator=).
	 * @param fImp A pointer to a valid CFile object.
	 * @return
	 * true if successful, otherwise false.
	 */
	virtual bool Import(CFile* fImp);

	/**
	 * @brief
	 * This member function appends a CFile derived object to the file
	 * (operator+=).
	 * @param fApp A pointer to a valid CFile object.
	 * @return
	 * true if successful, otherwise false.
	 */
	virtual bool Append(CFile* fApp);

private:
	// Unsupported APIs
	virtual CFile* Duplicate() const;

private:
	UINT m_uiOpenFlags;
	bool m_bOpen;
	CFile m_File;
};

#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // #if !defined(__XTMEMFILE_H__)
	   /** @endcond */