/**
 * @file XTPPropExchangeArchive.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(__XTPPROPEXCHANGEARCHIVE_H__)
#	define __XTPPROPEXCHANGEARCHIVE_H__
/** @endcond */

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

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

/**
 * @brief
 * CXTPPropExchangeArchive is CXTPPropExchange derived class.
 * The CXTPPropExchangeArchive class allows you to save a complex network of objects in a
 * permanent binary form (usually disk storage) that persists after those objects are deleted.
 * Later you can load the objects from persistent storage, reconstituting them in memory. This
 * process of making data persistent is called 'serialization.'
 *
 * <b>Example:</b>
 * <pre>
 * CFile myFile("myfile", CFile::modeCreate | CFile::modeWrite);
 *
 * // Create a storing archive.
 * CArchive arStore(&myFile, CArchive::store);
 * CXTPPropExchangeArchive px(arStore);
 * PX_String(&px, _T("Caption"), m_strCaption);
 * </pre>
 */
class _XTP_EXT_CLASS CXTPPropExchangeArchive : public CXTPPropExchange
{
	/** @cond */
	DECLARE_DYNAMIC(CXTPPropExchangeArchive)
	/** @endcond */
public:
	/**
	 * @brief
	 * Constructs a CXTPPropExchangeArchive object.
	 * @param ar A reference to the CArchive object that is the ultimate source or destination of
	 * the persistent data.
	 */
	CXTPPropExchangeArchive(CArchive& ar);

	/**
	 * @brief
	 * Exchanges a property between a storage medium and the control.
	 * @param pszPropName The name of the property being exchanged.
	 * @param vtProp      A symbol specifying the type of the property being
	 * exchanged.
	 * @param pvProp      A pointer to the property's value.
	 * @param pvDefault   Pointer to a default value for the property.
	 * @details
	 * Possible values of properties are:
	 * <pre>
	 * Symbol         Property Type
	 * -------------  -------------
	 * VT_I2          short
	 * VT_I4          long
	 * VT_BOOL        BOOL
	 * VT_BSTR        CString
	 * VT_CY          CY
	 * VT_R4          float
	 * VT_R8          double
	 * </pre>
	 * @return
	 * Nonzero if the exchange was successful; 0 if unsuccessful.
	 */
	virtual BOOL ExchangeProp(LPCTSTR pszPropName, VARTYPE vtProp, void* pvProp,
							  const void* pvDefault = NULL);

	/**
	 * @brief
	 * This method serializes a property that stores binary large object (BLOB) data.
	 * @param pszPropName The name of the property being exchanged.
	 * @param pData       A pointer to a user-supplied buffer that contains the data to be
	 * serialized
	 * @param nBytes      An integer that specifies the number of bytes to be read or written.
	 * @return
	 * Nonzero if the exchange was successful; 0 if unsuccessful.
	 */
	virtual BOOL ExchangeBlobProp(LPCTSTR pszPropName, BYTE*& pData, DWORD& nBytes);

	/**
	 * @brief
	 * Exchanges a CRuntimeClass between a storage and the class.
	 * @param pszPropName   The name of the property being exchanged.
	 * @param pClass        CRuntimeClass class pointer.
	 * @param pDefaultClass Pointer to a default runtime class for the property.
	 * @return
	 * Nonzero if the exchange was successful; 0 if unsuccessful.
	 */
	virtual BOOL ExchangeRuntimeClass(LPCTSTR pszPropName, CRuntimeClass*& pClass,
									  CRuntimeClass* pDefaultClass);

	/**
	 * @brief
	 * Exchanges a class instance.
	 * @param pObject        Object being exchanged.
	 * @param pObjectRuntime Default RUntime class of object
	 * @return
	 * Nonzero if the exchange was successful; 0 if unsuccessful.
	 */
	virtual BOOL ExchangeObjectInstance(CObject*& pObject, CRuntimeClass* pObjectRuntime);

	/**
	 * @brief
	 * This method create new Archive to serialize.
	 * @param pszPropName The name of the property being exchanged.
	 * @return
	 * CArchive pointer. You must call ReleaseArchive to free memory.
	 * @see ReleaseArchive
	 */
	virtual CArchive* GetArchive(LPCTSTR pszPropName);

	/**
	 * @brief
	 * This method releases CArchive pointer.
	 * @param pszPropName The name of the property being exchanged.
	 * @param pArchive    Archive pointer was previously returned by GetArchive member.
	 * @see GetArchive
	 */
	virtual void ReleaseArchive(LPCTSTR pszPropName, CArchive* pArchive);

	/**
	 * @brief
	 * Writes a specified number of bytes.
	 * @param pszPropName The name of the property being exchanged.
	 * @param lpBuf       A pointer to a user-supplied buffer that contains the data to be written.
	 * @param nCount      An integer that specifies the number of bytes to be written.
	 */
	virtual void Write(LPCTSTR pszPropName, const void* lpBuf, UINT nCount);

	/**
	 * @brief
	 * Reads a specified number of bytes.
	 * @param pszPropName The name of the property being exchanged.
	 * @param lpBuf       A pointer to a user-supplied buffer that is to receive the data
	 * @param nCount      An unsigned integer specifying the number of bytes to be read from the
	 * archive.
	 * @return
	 * An unsigned integer containing the number of bytes actually read.
	 */
	virtual UINT Read(LPCTSTR pszPropName, void* lpBuf, UINT nCount);

	/**
	 * @brief
	 * Call this method to determine if storage supported default values.
	 * @return
	 * TRUE if storage allows default values
	 */
	virtual BOOL IsAllowDefaultValues() const;

	/**
	 * @brief
	 * Call this method to determine if storage allows exchange plain blob values.
	 * @return
	 * TRUE if storage allows exchange plain blob values.
	 */
	virtual BOOL IsAllowBlobValues() const;

	/**
	 * @brief
	 * This method creates new section for text base storages (CXTPPropExchangeXMLNode and
	 * CXTPPropExchangeRegistry)
	 * @param lpszSection The name of the section.
	 * @return
	 * CXTPPropExchange pointer to new section. You must delete this pointer or use
	 * CXTPPropExchangeSection to manage it.
	 *
	 * <b>Example:</b>
	 * <pre>
	 * CXTPPropExchangeSection pxTaskPanel(px.GetSection(_T("TaskPanel")));
	 * m_wndTaskPanel.GetGroups()->DoPropExchange(&pxTaskPanel);
	 * </pre>
	 */
	CXTPPropExchange* GetSection(LPCTSTR lpszSection);

	/**
	 * @brief
	 * Use this member function to write DWORD number to storage
	 * @param dwCount DWORD number
	 * @see ReadCount
	 */
	virtual void WriteCount(DWORD dwCount);

	/**
	 * @brief
	 * Use this member function to read DWORD number from storage
	 * @return
	 * DWORD number
	 * @see WriteCount
	 */
	virtual DWORD ReadCount();

	CArchive& GetSelfArchive();

private:
	CXTPPropExchangeArchive& operator=(const CXTPPropExchangeArchive&)
	{
		_ASSERTE(FALSE);
		return *this;
	}

protected:
	/** @cond */
	virtual void ExchangeSchemaSafe();

	class CSelfArchive : public CArchive
	{
	public:
		CSelfArchive(CFile* pFile, UINT nMode, int nBufSize = 4096, void* lpBuf = NULL);
		friend class CXTPPropExchangeArchive;
	};
	/** @endcond */

	CSelfArchive& m_ar; /**< Contains the underlying CArchive for this CXTPPropExchangeArchive
						   object. */
};
/** @cond */
AFX_INLINE BOOL CXTPPropExchangeArchive::IsAllowDefaultValues() const
{
	return FALSE;
}

AFX_INLINE BOOL CXTPPropExchangeArchive::IsAllowBlobValues() const
{
	return TRUE;
}

AFX_INLINE CArchive& CXTPPropExchangeArchive::GetSelfArchive()
{
	return m_ar;
}
/** @endcond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // !defined(__XTPPROPEXCHANGEARCHIVE_H__)
/** @endcond */