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

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

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

/**
 * @brief
 * The XTP_LVITEMDATA structure is used to maintain information for
 * a particular list item in a CXTPShellListCtrl or CXTPShellListView
 * window.
 * @see
 * CXTPShellListCtrl, CXTPShellListView
 */
struct XTP_LVITEMDATA
{
	ULONG ulAttribs;		  /**< Shell item attributes. */
	LPITEMIDLIST lpi;		  /**< Pointer to an item ID list. */
	LPSHELLFOLDER lpsfParent; /**< Pointer to the parent shell folder item. */
};

/**
 * @brief
 * The XTP_TVITEMDATA structure is used to maintain information for
 * a particular tree item in a CXTPShellTreeCtrl or CXTPShellTreeView
 * window.
 * @see
 * CXTPShellTreeCtrl, CXTPShellTreeView
 */
struct XTP_TVITEMDATA
{
	LPITEMIDLIST lpi;		  /**< Pointer to an item ID list. */
	LPITEMIDLIST lpifq;		  /**< Pointer to an item ID list. */
	LPSHELLFOLDER lpsfParent; /**< Pointer to the parent shell folder item. */
};

/**
 * @brief
 * CXTPShellPidl is a standalone base class. This class is used by the
 * shell tree and list controls to handle PIDL creation and management.
 */
class _XTP_EXT_CLASS CXTPShellPidl
{
public:
	/**
	 * @brief
	 * CXTPShellPidl::CShellMalloc is a helper class that is used by
	 * CXTPShellPidl to initialize a pointer to the Shell's IMalloc
	 * interface used for allocating memory blocks.
	 */
	class _XTP_EXT_CLASS CShellMalloc
	{
	public:
		/**
		 * @brief
		 * Constructs a CXTPShellPidl::CShellMalloc object and initializes
		 * a pointer to the Shell's IMalloc interface.
		 */
		CShellMalloc()
		{
			m_lpMalloc = NULL;

			if (FAILED(::SHGetMalloc(&m_lpMalloc)))
			{
				m_lpMalloc = NULL;
			}
		}

		/**
		 * @brief
		 * Destroys a CXTPShellPidl::CShellMalloc object, handles cleanup
		 * and deallocation.
		 */
		virtual ~CShellMalloc()
		{
			if (m_lpMalloc)
			{
				m_lpMalloc->Release();
			}
		}

		/**
		 * @brief
		 * Call this member function to allocate a block of memory.
		 * @param nBytes Size, in bytes, of the memory block to be allocated.
		 * @return
		 * If successful, then Alloc returns a pointer to the allocated memory
		 * block. If insufficient memory is available, then Alloc returns NULL.
		 */
		void* Alloc(DWORD nBytes)
		{
			_ASSERTE(m_lpMalloc != NULL);
			return m_lpMalloc ? m_lpMalloc->Alloc(nBytes) : NULL;
		}

		/**
		 * @brief
		 * Call this member function to free a block of previously
		 * allocated memory.
		 * @param lpMem Pointer to the memory block to be freed.
		 */
		void Free(void* lpMem)
		{
			_ASSERTE(m_lpMalloc != NULL);
			if (m_lpMalloc)
			{
				m_lpMalloc->Free(lpMem);
			}
		}

		/**
		 * @brief
		 * Retrieves a pointer to Shell's IMalloc interface for this object.
		 * @return
		 * A pointer to Shell's IMalloc interface for this object.
		 */
		operator LPMALLOC()
		{
			return m_lpMalloc;
		}

	protected:
		LPMALLOC m_lpMalloc; /**< Pointer to Shell's IMalloc interface for this object. */
	};

	/**
	 * @brief
	 * CXTPShellPidl::CShellSpecialFolder is a helper class that is used by
	 * CXTPShellPidl to initialize a pointer to an ITEMIDLIST structure of
	 * a special folder.
	 */
	class _XTP_EXT_CLASS CShellSpecialFolder
	{
	public:
		/**
		 * @brief
		 * Constructs a CXTPShellPidl::CShellSpecialFolder object and
		 * initializes a pointer to the ITEMIDLIST structure of the
		 * special folder specified by nFolder.
		 * @param nFolder A value that identifies the folder of interest. See
		 * CSIDL in MSDN documentation for a list of constants
		 * that represent special folder locations.
		 */
		CShellSpecialFolder(int nFolder = CSIDL_DESKTOP);

		/**
		 * @brief
		 * Destroys a CXTPShellPidl::CShellSpecialFolder object, handles
		 * cleanup and deallocation.
		 */
		virtual ~CShellSpecialFolder()
		{
			if (m_lpFolder)
			{
				m_lpFolder->Release();
			}
		}

		/**
		 * @brief
		 * Retrieves a pointer to the interface for the desktop folder,
		 * which is the root of the Shell's namespace.
		 * @return
		 * A pointer to the interface for the desktop folder.
		 */
		operator LPSHELLFOLDER()
		{
			return m_lpFolder;
		}

	protected:
		LPSHELLFOLDER m_lpFolder; /**< Pointer to the interface for the desktop folder. */
	};

	/**
	 * @brief
	 * Constructs a CXTPShellPidl object.
	 */
	CXTPShellPidl();

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

	/**
	 * @brief
	 * This member function gets the fully qualified PIDL for the path string.
	 * @param path File system path string.
	 * @return
	 * A pointer to an item ID list if successful, otherwise NULL.
	 */
	LPITEMIDLIST IDLFromPath(LPCTSTR path);

	/**
	 * @brief
	 * This member function performs the OneUp or back function.
	 * @param pidlPath Fully qualified PIDL.
	 * @return
	 * A fully qualified parent PIDL.
	 */
	LPITEMIDLIST OneUpPIDL(LPITEMIDLIST pidlPath);

	/**
	 * @brief
	 * This member function gets the parent folder using PIDLs.
	 * @param path Path string.
	 * @return
	 * A path string to the parent.
	 */
	CString OneUpPATH(const CString& path);

	/**
	 * @brief
	 * This member function walks an ITEMIDLIST and points to the last one.
	 * @param pidl PIDL list.
	 * @return
	 * A pointer to the last IDL in the list.
	 */
	LPITEMIDLIST GetLastITEM(LPITEMIDLIST pidl);

	/**
	 * @brief
	 * This member function copies a whole ITEMIDLIST. Remember to Free()
	 * the old one if it is no longer needed.
	 * @param pidl Pointer to an ITEMIDLIST.
	 * @return
	 * A new pointer to a copy of the PIDL.
	 */
	LPITEMIDLIST CopyIDList(LPITEMIDLIST pidl);

	/**
	 * @brief
	 * This member function concatenates two PIDLs.
	 * @param pidl1 Pointer to an item ID list.
	 * @param pidl2 Pointer to an item ID list.
	 * @return
	 * A pointer to an item ID list.
	 */
	LPITEMIDLIST ConcatPidls(LPCITEMIDLIST pidl1, LPCITEMIDLIST pidl2);

	/**
	 * @brief
	 * This member function concatenates two PIDLs.
	 * @param lpMalloc Pointer to the shell's IMalloc interface.
	 * @param pidl1 Pointer to an item ID list.
	 * @param pidl2 Pointer to an item ID list.
	 * @return
	 * A pointer to an item ID list.
	 */
	LPITEMIDLIST ConcatPidls(LPMALLOC lpMalloc, LPCITEMIDLIST pidl1, LPCITEMIDLIST pidl2);

	/**
	 * @brief
	 * This member function gets the fully qualified PIDLs for the specified
	 * folder.
	 * @param lpsf Pointer to the parent shell folder.
	 * @param lpi  Pointer to the item ID that is relative to 'lpsf'.
	 * @return
	 * A pointer to an item ID list.
	 */
	LPITEMIDLIST GetFullyQualPidl(LPSHELLFOLDER lpsf, LPITEMIDLIST lpi);

	/**
	 * @brief
	 * This member function copies the ITEMID.
	 * @param lpMalloc Pointer to the shell's IMalloc interface.
	 * @param lpi      Pointer to the item ID that is to be copied.
	 * @return
	 * A pointer to an item ID list.
	 */
	LPITEMIDLIST DuplicateItem(LPMALLOC lpMalloc, LPITEMIDLIST lpi);

	/**
	 * @brief
	 * This member function gets the friendly name for the folder or file.
	 * @param lpsf           Pointer to the parent shell folder.
	 * @param lpi            Pointer to the item ID that is relative to 'lpsf'.
	 * @param dwFlags        Flags to determine which value to return. See SHGNO
	 * for more details.
	 * @param lpFriendlyName Buffer to receive the friendly name of the folder.
	 * @return
	 * TRUE if successful, otherwise FALSE.
	 */
	BOOL GetName(LPSHELLFOLDER lpsf, LPITEMIDLIST lpi, DWORD dwFlags, CString& lpFriendlyName);

	/**
	 * @brief
	 * This member function allocates a PIDL.
	 * @param lpMalloc Pointer to the shell's IMalloc interface.
	 * @param cbSize Initial size of the PIDL.
	 * @return
	 * A pointer to an item ID list.
	 */
	LPITEMIDLIST CreatePidl(LPMALLOC lpMalloc, UINT cbSize);

	/**
	 * @brief
	 * This member function calculates the number of item IDs in an
	 * item ID list.
	 * @param pidl Pointer to an item ID list.
	 * @return
	 * The number of item IDs in the list.
	 */
	UINT GetPidlItemCount(LPCITEMIDLIST pidl);

	/**
	 * @brief
	 * This member function retrieves the next PIDL in the list.
	 * @param pidl Pointer to an item ID list.
	 * @return
	 * A pointer to the next PIDL item in the list.
	 */
	LPITEMIDLIST GetNextPidlItem(LPCITEMIDLIST pidl);

	/**
	 * @brief
	 * This member function displays a pop-up context menu if given a parent
	 * shell folder, relative item ID, and screen location.
	 * @param hwnd       Context menu owner.
	 * @param lpsfParent Pointer to the parent shell folder.
	 * @param lpi        Pointer to the item ID that is relative to 'lpsfParent'.
	 * @param lppt       Screen location of where to pop-up the menu.
	 * @return
	 * TRUE if successful, otherwise FALSE.
	 */
	BOOL ShowContextMenu(HWND hwnd, LPSHELLFOLDER lpsfParent, LPITEMIDLIST lpi, LPPOINT lppt);

	/**
	 * @brief
	 * This member function displays a pop-up context menu if given a parent
	 * shell folder, relative item ID, and screen location.
	 * @param hwnd       Context menu owner.
	 * @param lpsfParent Pointer to the parent shell folder.
	 * @param lppi       Pointer to the item ID that is relative to 'lpsfParent'.
	 * @param nCount     Number of PIDLs.
	 * @param lppt       Screen location of where to pop-up the menu.
	 * @return
	 * TRUE if successful, otherwise FALSE.
	 */
	BOOL ShowContextMenu(HWND hwnd, LPSHELLFOLDER lpsfParent, LPCITEMIDLIST* lppi, int nCount,
						 LPPOINT lppt);

	/**
	 * @brief
	 * This member function gets the index for the current icon. The
	 * index is the index into the system image list.
	 * @param lpi    Fully qualified item ID list for the current item.
	 * @param uFlags Flags that specify what the image list retrieves. Can
	 * be a combination of the following values:<p/>
	 * <b>SHGFI_SMALLICON</b>: Return the index of small icon
	 * from the system image list.
	 * <b>SHGFI_LARGEICON</b>: Return the index of large icon
	 * from the system image list.
	 * <b>SHGFI_OPENICON</b>:  Return the index of selected icon
	 * from the system image list.
	 * @return
	 * An icon index for the current item.
	 */
	int GetItemIcon(LPITEMIDLIST lpi, UINT uFlags) const;

	/**
	 * @brief
	 * Call this member function to retrieve a string that describes the
	 * type of file specified by lpi from the Windows Shell.
	 * @param uFlags Flags that specify what the image list retrieves. Can
	 * be a combination of the following values:<p/>
	 * <b>SHGFI_SMALLICON</b>: Return the handle to the system image
	 * list that contains small icon images.
	 * <b>SHGFI_LARGEICON</b>: Return the handle to the system image
	 * list that contains large icon images.
	 * @return
	 * A handle to the system image list that contains the specified icon images.
	 */
	HIMAGELIST GetSystemImageList(UINT uFlags) const;

	/**
	 * @brief
	 * Retrieves the attributes of one or more file objects or subfolders.
	 * @param lpsf   Pointer to the parent shell folder.
	 * @param lpi    Fully qualified item ID list for the current item.
	 * @param uFlags Single ULONG value that contains the attributes that
	 * the caller is requesting.
	 * @return
	 * Requested attributes that are common to all of the specified objects.
	 */
	ULONG GetAttributes(LPSHELLFOLDER lpsf, LPITEMIDLIST lpi, ULONG uFlags) const;

	/**
	 * @brief
	 * This member function retrieves the IContextMenu, IContextMenu2 or IContextMenu3
	 * interface.
	 * @param psfFolder A pointer to a valid IShellFolder data type.
	 * @param localPidl A pointer to a valid _ITEMIDLIST structure.
	 * @param nCount    Number of items in the context menu.
	 * @param ppCM      Long pointer to a CONTEXTMENU struct.
	 * @param pcmType   A pointer to a valid int data type that represents the
	 * version number of the context menu.
	 * @return
	 * A HRESULT value.
	 */
	HRESULT GetSHContextMenu(LPSHELLFOLDER psfFolder, LPCITEMIDLIST* localPidl, int nCount,
							 void** ppCM, int* pcmType);

	/**
	 * @brief
	 * CXTPShellTreeCtrl callback sort function.
	 * @param lparam1     Corresponds to the lParam member of the TV_ITEM structure
	 * for the two items being compared.
	 * @param lparam2     Corresponds to the lParam member of the TV_ITEM structure
	 * for the two items being compared.
	 * @param lparamSort  Corresponds to the lParam member of TV_SORTCB.
	 * @details
	 * This member function is a callback function used by
	 * CXTPShellTreeCtrl and CXTPShellTreeView, and is called during a sort
	 * operation each time the relative order of two list items needs to
	 * be compared.
	 * @return
	 * A negative value if the first item should precede the second, a
	 * positive value if the first item should follow the second, or zero
	 * if the two items are equivalent.
	 */
	static int CALLBACK TreeViewCompareProc(LPARAM lparam1, LPARAM lparam2, LPARAM lparamSort);

	/**
	 * @brief
	 * CXTPShellListCtrl callback sort function.
	 * @param lparam1     Corresponds to the lParam member of the LV_ITEM structure
	 * for the two items being compared.
	 * @param lparam2     Corresponds to the lParam member of the LV_ITEM structure
	 * for the two items being compared.
	 * @param lparamSort  Corresponds to the lParam member of LV_SORTCB.
	 * @details
	 * This member function is a callback function used by
	 * CXTPShellListCtrl and CXTPShellListView, and is called during a sort
	 * operation each time the relative order of two list items needs to
	 * be compared.
	 * @return
	 * A negative value if the first item should precede the second, a
	 * positive value if the first item should follow the second, or zero
	 * if the two items are equivalent.
	 */
	static int CALLBACK ListViewCompareProc(LPARAM lparam1, LPARAM lparam2, LPARAM lparamSort);

	/**
	 * @brief
	 * Call this member function to override the shortcut link display for each item.
	 * @param bShowLinkIcons TRUE to enable shortcut link display, FALSE to disable.
	 */
	void ShowShellLinkIcons(BOOL bShowLinkIcons = TRUE);

	/**
	 * @brief
	 * Calculates the number of item IDs in the list.
	 * @param pidl Pointer to an item ID list.
	 * @return
	 * The number of item IDs in the list.
	 */
	UINT GetPidlCount(LPCITEMIDLIST pidl);

	/**
	 * @brief
	 * This member function frees memory allocated for a PIDL.
	 * @param pidl Pointer to an item ID list.
	 */
	void FreePidl(LPITEMIDLIST pidl);

	/**
	 * @brief
	 * This member function copies a single PIDL out of a list. Remember
	 * to Free() the old one if it is no longer needed.
	 * @param pidl Pointer to an ITEMIDLIST.
	 * @param nItem PIDL in the list to copy.
	 * @return
	 * A new pointer to a copy of the PIDL with the single item.
	 */
	LPITEMIDLIST CopyPidlItem(LPITEMIDLIST pidl, UINT nItem);

	/**
	 * @brief
	 * This member function compares two PIDLs to determine if they match.
	 * @param pidl1        Pointer to an item ID list.
	 * @param pidl2        Pointer to an item ID list.
	 * @param pShellFolder Pointer to the shell folder to use for the comparison
	 * (default Desktop).
	 * @return
	 * TRUE if successful, otherwise FALSE.
	 */
	BOOL ComparePidls(LPCITEMIDLIST pidl1, LPCITEMIDLIST pidl2, LPSHELLFOLDER pShellFolder = NULL);

protected:
	/**
	 * @brief
	 * This method is called when an item of a context menu is executed.
	 * @param idCmd Identifier of the item that was executed.
	 * @param cmi   A CMINVOKECOMMANDINFO structure reference containing additional
	 * information about the item that was executed.
	 */
	virtual void OnShowContextMenu(int idCmd, CMINVOKECOMMANDINFO& cmi);

	/**
	 * @brief
	 * This function translates shell attributes into a tree item state.
	 * @param pListCtrl    List Control that owns an item.
	 * @param iItem        Index to identify the item, passed verbatim to SetItemState().
	 * @param dwAttributes Shell attributes to translate.
	 */
	virtual void MapShellFlagsToItemAttributes(CListCtrl* pListCtrl, int iItem, DWORD dwAttributes);

	/**
	 * @brief
	 * This function translates shell attributes into a tree item state.
	 * @param pTreeCtrl    Tree Control that owns an item.
	 * @param hItem        Handle to identify the item, passed verbatim to SetItemState().
	 * @param dwAttributes Shell attributes to translate.
	 */
	virtual void MapShellFlagsToItemAttributes(CTreeCtrl* pTreeCtrl, HTREEITEM hItem,
											   DWORD dwAttributes);

protected:
	ULONG m_ulSFGAOFlags;		/**< SFGAO flags used to retrieve shell item attributes. */
	BOOL m_bShowShellLinkIcons; /**< Set to FALSE to override shortcut link display. */

private:
	static WNDPROC m_pOldWndProc;		/**< Regular window proc. */
	static LPCONTEXTMENU2 m_pIContext2; /**< Active shell context menu. */
	static LRESULT CALLBACK HookWndProc(HWND hWnd, UINT msg, WPARAM wp, LPARAM lp);
};

/** @cond */
AFX_INLINE void CXTPShellPidl::ShowShellLinkIcons(BOOL bShowLinkIcons /*= TRUE*/)
{
	m_bShowShellLinkIcons = bShowLinkIcons;
}

#	ifndef CSIDL_MYPICTURES
#		define CSIDL_MYPICTURES 0x0027
#	endif

#	ifndef SFGAO_STREAM
#		define SFGAO_STREAM 0x00400000L
#	endif

#	ifndef SFGAO_ENCRYPTED
#		define SFGAO_ENCRYPTED 0x00002000L
#	endif

#	ifndef SHCIDS_ALLFIELDS
#		define SHCIDS_ALLFIELDS 0x80000000L
#	endif
/** @endcond */
#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // __XTPSHELLPIDL_H__
/** @endcond */