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

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

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

/** @cond */
// IXTPCmdTargetProvider interface identifier.
EXTERN_C const IID IID_IXTPCmdTargetProvider;

#	pragma warning(push)
// C4616: #pragma warning : warning number '...' out of range, must be between '4001' and '4999'
// C4619: #pragma warning : there is no warning number 'number'
// C5204: '...': class has virtual functions, but its trivial destructor is not virtual; instances
// of objects derived from this class may not be destructed correctly
#	pragma warning(disable : 4616 4619 5204)

/**
 * @brief
 * A class that implements IXTPCmdTargetProvider interface can be
 * used when guaranteed casting from IDispatch to CCmdTarget is
 * required using CXTPCmdTarget::FromIDispatchSafe.
 */
struct __declspec(uuid("1965CF4C-7BE1-4E09-94B4-DCEF78B16D04")) IXTPCmdTargetProvider
	: public IUnknown
{
	/**
	 * @brief
	 * The implementation must always return a valid CCmdTarget pointer
	 * of the current implementation object.
	 * @return
	 * Obtained CCmdTarget pointer value.
	 */
	virtual CCmdTarget* GetCmdTarget() = 0;
};

#	pragma warning(pop)

// clang-format off
#	if defined(_MSC_VER) && (1900 <= _MSC_VER)
#		define XTP_DECLARE_CMDTARGETPROVIDER_INTERFACE_()                                              \
			__pragma(warning(push))                                                                    \
			__pragma(warning(disable : 4616 4619 5204))                                                \
			BEGIN_INTERFACE_PART(CmdTargetProvider, IXTPCmdTargetProvider)                             \
			virtual CCmdTarget* GetCmdTarget();                                                        \
			END_INTERFACE_PART(CmdTargetProvider);                                                     \
			__pragma(warning(pop))
#	else
#		define XTP_DECLARE_CMDTARGETPROVIDER_INTERFACE_()                                              \
			BEGIN_INTERFACE_PART(CmdTargetProvider, IXTPCmdTargetProvider)                             \
			virtual CCmdTarget* GetCmdTarget();                                                        \
			END_INTERFACE_PART(CmdTargetProvider);
#	endif
// clang-format on
/** @endcond */

/**
 * @brief
 * When deriving from CXTPCmdTarget is not possible this macro can
 * be used in addition to standard DECLARE_INTERFACE_MAP for
 * declaring IXTPCmdTargetProvider interface.
 */
#	define XTP_DECLARE_CMDTARGETPROVIDER_INTERFACE() XTP_DECLARE_CMDTARGETPROVIDER_INTERFACE_()

/**
 * @brief
 * When deriving from CXTPCmdTarget is not possible this macro can
 * be used in addition to standard DECLARE_INTERFACE_MAP for
 * declaring IXTPCmdTargetProvider interface part.
 * @param className Class name that implements IXTPCmdTargetProvider interface.
 */
#	define XTP_DECLARE_CMDTARGETPROVIDER_INTERFACE_PART(className)                                \
		INTERFACE_PART(className, IID_IXTPCmdTargetProvider, CmdTargetProvider)

/**
 * @brief
 * When deriving from CXTPCmdTarget is not possible this macro can
 * be used in addition to standard DECLARE_INTERFACE_MAP for
 * implementing IXTPCmdTargetProvider interface.
 * @param className Class name that implements IXTPCmdTargetProvider interface.
 */
#	define XTP_IMPLEMENT_CMDTARGETPROVIDER_INTERFACE(className)                                   \
		XTP_IMPLEMENT_IUNKNOWN(className, CmdTargetProvider)                                       \
		CCmdTarget* className::XCmdTargetProvider::GetCmdTarget()                                  \
		{                                                                                          \
			METHOD_PROLOGUE(className, CmdTargetProvider);                                         \
			return pThis;                                                                          \
		}

/**
 * @brief
 * The CXTPCmdTarget class extends functionality of CCmdTarget
 * and introduces workarounds for known issues and limitations of CCmdTarget.
 */
class _XTP_EXT_CLASS CXTPCmdTarget : public CCmdTarget
{
	DECLARE_DYNAMIC(CXTPCmdTarget);

public:
	/**
	 * @brief
	 * Constructs command target instance.
	 */
	CXTPCmdTarget();

	/**
	 * @brief
	 * Tries to cast IDispatch pointer to its CCmdTarget object pointer
	 * if it is provided by CCmdTarget.
	 * Unlike CCmdTarget::FromIDispatch
	 * that has side-effects in certain configurations FromIDispatchSafe
	 * guaranties correct CCmdTarget pointer as a result value if an
	 * object that provides IDispatch interface is either derived from
	 * CXTPCmdTarget or only exposes IXTPCmdTargetProvider interface.
	 * If the object does not expose IXTPCmdTargetProvider interface
	 * the implementation fall back to CCmdTarget::FromIDispatch.
	 * @param pDisp IDispatch pointer for which CCmdTarget pointer is to be obtained.
	 * @return
	 * Obtained CCmdTarget pointer value or NULL when it cannot be obtained.
	 */
	static CCmdTarget* AFX_CDECL FromIDispatchSafe(IDispatch* pDisp);

	/** @cond */
protected:
	DECLARE_INTERFACE_MAP()
	XTP_DECLARE_CMDTARGETPROVIDER_INTERFACE()
	/** @endcond */
};

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