/**
* @file XTPPropExchangeXMLNode.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(__XTPPROPEXCHANGEXMLNODE_H__)
# define __XTPPROPEXCHANGEXMLNODE_H__
/** @endcond */
# if _MSC_VER > 1000
# pragma once
# endif // _MSC_VER > 1000
# ifndef _XTP_EXCLUDE_XML
# include "Common/Base/Diagnostic/XTPDisableNoisyWarnings.h"
/**
* @brief
* CXTPPropExchangeXMLNode is CXTPPropExchange derived class.
* The CXTPPropExchangeXMLNode class allows you to save a complex network of objects in a XML
* file 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.'
*
* Example:
*
* CXTPPropExchangeXMLNode px(TRUE, 0, _T("Settings"));
* if (px.LoadFromFile(m_strIniFileName))
* {
* m_wndTaskPanel.GetGroups()->DoPropExchange(&px);
* }
*
*/
class _XTP_EXT_CLASS CXTPPropExchangeXMLNode : public CXTPPropExchange
{
class CXMLEnumerator;
/** @cond */
DECLARE_DYNAMIC(CXTPPropExchangeXMLNode)
/** @endcond */
public:
/**
* @brief
* Constructs CXTPPropExchangeXMLNode a object.
* @param bLoading A flag that specifies whether objects will be loaded from or stored.
* @param xmlParentNode Parent node element. Can be NULL.
* @param lpszSection Points to a null-terminated string that specifies the section containing
* the entry.
*/
CXTPPropExchangeXMLNode(BOOL bLoading, CXTPDOMNodePtr xmlParentNode, LPCTSTR lpszSection);
public:
/**
* @brief
* Determines if XML installed in System (IE 4.0)
* @return True if XML is installed in system, false is not
*/
static BOOL AFX_CDECL IsXMLSupported();
public:
/**
* @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:
*
* Symbol Property Type
* ------------- -------------
* VT_I2 short
* VT_I4 long
* VT_BOOL BOOL
* VT_BSTR CString
* VT_CY CY
* VT_R4 float
* VT_R8 double
*
* @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 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.
*
* Example:
*
* CXTPPropExchangeSection pxTaskPanel(px.GetSection(_T("TaskPanel")));
* m_wndTaskPanel.GetGroups()->DoPropExchange(&pxTaskPanel);
*
*/
virtual CXTPPropExchange* GetSection(LPCTSTR lpszSection);
/**
* @brief
* Call this method to free section information before storing
*/
virtual void EmptySection();
/**
* @brief
* Call this method to enumerate child sections.
* @param lpszSection child section name.
* @return
* Returns an enumerator for child sections.
*
* Example:
*
* extern CXTPPropExchange* pPX;
*
* CXTPPropExchangeEnumeratorPtr pEnumerator(pPX->GetEnumerator(_T("Icon")));
* POSITION posEnum = pEnumerator->GetPosition();
*
* while (posEnum)
* {
* CXTPPropExchangeSection secIcon(pEnumerator->GetNext(posEnum));
* }
*
* @see CXTPPropExchangeEnumerator
*/
virtual CXTPPropExchangeEnumerator* GetEnumerator(LPCTSTR lpszSection);
public:
/**
* @brief
* Call this method to check if property entry exists.
* @param pszPropName The name of the property being checked.
* @return True of property entry exist
*/
BOOL IsPropertyExists(LPCTSTR pszPropName);
/**
* @brief
* Call this method to check if section exists.
* @param lpszSection The name of the section being checked.
* @return True if section exist
*/
BOOL IsSectionExists(LPCTSTR lpszSection);
/**
* @brief
* Retrieves section name of the XML node.
* @return
* Name of the XML node.
*/
CString GetSectionName();
/**
* @brief
* Call this method to store data in compact mode (To use node attributes instead nodes)
* @param bCompactMode TRUE to use compact mode (default)
*/
void SetCompactMode(BOOL bCompactMode);
/**
* @brief
* Loads the contents of an existing file into a XML.
* @param lpszFileName A CString value that contains the name of a file to be loaded into the
* XML
* @return
* TRUE if successful; otherwise FALSE.
*/
BOOL LoadFromFile(LPCTSTR lpszFileName);
/**
* @brief
* Loads the contents of string to XML.
* @param lpszState A pointer to a value that contains XML nodes
* @return
* TRUE if successful; otherwise FALSE.
*/
BOOL LoadFromString(LPCSTR lpszState);
/**
* @brief
* Loads the contents of string to XML.
* @param lpszState A pointer to a value that contains XML nodes
* @return
* TRUE if successful; otherwise FALSE.
*/
BOOL LoadFromString(LPCWSTR lpszState);
/**
* @brief
* Loads the contents of string to XML.
* @param bstrState BSTR value that contains XML nodes
* @return
* TRUE if successful; otherwise FALSE.
*/
BOOL LoadFromString(BSTR bstrState);
/**
* @brief
* Loads the contents of the encoded string to XML.
* @param lpszState Buffer that contains XML nodes.
* @return
* TRUE if successful; otherwise FALSE.
*/
BOOL LoadFromEncodedString(LPCSTR lpszState);
/**
* @brief
* Loads the contents of the encoded string to XML.
* @param lpszState Buffer that contains XML nodes.
* @return
* TRUE if successful; otherwise FALSE.
*/
BOOL LoadFromEncodedString(LPCWSTR lpszState);
/**
* @brief
* Loads the resource by the specified type.
* @param hInstance Resource instance handle.
* @param lpszResourceName Resource name.
* @param lpszResourceType Resource type.
* @return
* TRUE if successful; otherwise FALSE.
*/
BOOL LoadFromResource(HINSTANCE hInstance, LPCTSTR lpszResourceName, LPCTSTR lpszResourceType);
/**
* @brief
* Retrieves the XML representation of the node and all its descendants.
* @param bFormatted TRUE to format XML/encoded XML output
* @return
* XML/encoded XML representation of this node and all its descendants.
*/
CString GetXML(BOOL bFormatted = FALSE);
/**
* @brief
* Retrieves the encoded XML representation of the node and all its descendants.
* @param bFormatted TRUE to format XML/encoded XML output
* @return
* XML/encoded XML representation of this node and all its descendants.
*/
CString GetEncodedXML(BOOL bFormatted = FALSE);
/**
* @brief
* Saves an XML document to the specified location.
* @param lpszFileName Destination file name.
* @param bFormatted TRUE to format XML output
* @return S_OK if successful, an error code otherwise.
*/
HRESULT SaveToFile(LPCTSTR lpszFileName, BOOL bFormatted = TRUE);
/**
* @brief
* This method is called before exchange properties.
* @return
* TRUE if storage ready to exchange properties.
*/
virtual BOOL OnBeforeExchange();
/**
* @brief
* Call this member to change loading flag.
*
* @param bLoading A flag that specifies whether objects will be loaded from or stored.
*/
void SetLoading(BOOL bLoading);
/**
* @brief
* Call this member to append one section to another
* @param pNode Section to be append.
* @return True if successful
*/
BOOL PutSection(CXTPPropExchangeXMLNode* pNode);
/**
* @brief
* Creates cloned version of the section
* @param bRecursive TRUE to clone recursively
* @return TRUE if successful; otherwise FALSE.
*/
CXTPPropExchangeXMLNode* Clone(BOOL bRecursive);
/**
* @brief
* Call this method to set encoding for XML output
* @param lpszEncoding encoding that will be used in XML file
* @details
* Default encoding is UTF-8
*
* Example:
* px.SetEncoding(_T("windows-1251"));
*/
void SetEncoding(LPCTSTR lpszEncoding);
/**
* @brief
* Call this member to get access to dom xml node for current section
* @return Section XML DOM node pointer.
*/
CXTPDOMNodePtr GetSectionNode() const
{
return m_xmlSectionNode;
}
/**
* @brief
* Creates new XML node and put it as Child
*
* @param pszSection New section name
* @return A newly created XML node property excahge object pointer.
*/
CXTPPropExchangeXMLNode* CreateSection(LPCTSTR pszSection);
public:
CXTPDOMDocumentPtr GetDocumentPtr() const;
CString GetEncoding() const;
protected:
/**
* @brief
* Retrieves profile node.
* @param lpszSection Section name of profile node
* @return
* Profile node.to be used
*/
CXTPDOMNodePtr GetProfileNode(LPCTSTR lpszSection);
/**
* @brief
* Retrieves entry node which the value is to be written.
* @param lpszEntry Points to a null-terminated string that contains the entry into which the
* @param bCreate TRUE to create if doesn't exist.
* @return
* Entry node to be used
*/
CXTPDOMNodePtr GetEntryNode(LPCTSTR lpszEntry, BOOL bCreate);
private:
void UpdateDocumentEncoding();
BOOL CreateDocumentInstance();
void FormatFile(LPCTSTR lpszFileName);
void TraceParseError();
CString BstrToString(BSTR bstrVal);
void FormatString(CString& str);
protected:
CXTPDOMDocumentPtr m_xmlDocPtr; /**< XML Document pointer */
CXTPDOMNodePtr m_xmlParentNode; /**< XML Parent node pointer */
CXTPDOMNodePtr m_xmlSectionNode; /**< XML Section node pointer */
CString m_strSectionName; /**< Section name */
CString m_strEncoding; /**< XML encoding. */
BOOL m_bCompactMode; /**< TRUE to use compact mode. */
friend class CXMLEnumerator;
friend class CPropExchangeCtrl;
};
/** @cond */
AFX_INLINE CXTPDOMDocumentPtr CXTPPropExchangeXMLNode::GetDocumentPtr() const
{
return m_xmlDocPtr;
}
AFX_INLINE CString CXTPPropExchangeXMLNode::GetEncoding() const
{
return m_strEncoding;
}
/** @endcond */
# include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
# endif // _XTP_EXCLUDE_XML
/** @cond */
#endif // !defined(__XTPPROPEXCHANGEXMLNODE_H__)
/** @endcond */