/**
 * @file  XTPCalendarData.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
 *
 */

#if !defined(_XTPCALENDARDATA_H__)
#	define _XTPCALENDARDATA_H__

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

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

////////////////////////////////////////////////////////////////////////////

class CXTPCalendarRecurrencePattern;
class CXTPCalendarEventLabels;
class CXTPCalendarSchedules;
class CXTPNotifyConnection;
class CXTPCalendarOptions;
class CXTPCalendarEventCategories;
class CXTPCalendarCustomProperties;
class CXTPCalendarEvents;
class CXTPCalendarEvent;
/** @cond */
XTP_DEFINE_SMART_PTR_INTERNAL(CXTPCalendarEvents)
XTP_DEFINE_SMART_PTR_INTERNAL(CXTPCalendarEvent)
XTP_DEFINE_SMART_PTR_INTERNAL(CXTPCalendarRecurrencePattern)
/** @endcond */
/**
 * @brief
 * Cache table size.
 * @details
 * Should be a prime number!
 * like: 503, 1021, 1511, 2003, 3001, 4001, 5003, 6007, 8009, 12007, 16001,
 * 32003, 48017, 64007
 */
#	define XTP_OBJECT_CACHE_HASH_TABLE_SIZE 1021

static const LPCTSTR cszProcess_RecurrenceState =
	_T("process_RecurrenceState"); /**< String name for a corresponding property*/
static const LPCTSTR cszProcess_RecurrencePatternID =
	_T("process_RecurrencePatternID"); /**< String name for a corresponding property*/

/**
 * @brief
 * This class defines an abstract representation of the Calendar
 * control data with all necessary methods and some predefined
 * functionality added.
 *
 * @details
 * This class is the definition of the XTPCalendarData abstract
 * class which represents a data portion of the Calendar control.
 *
 * To implement a custom Data Provider solution you should create a class
 * derived from CXTPCalendarData and implement necessary virtual methods.
 * The first main set of methods to be implemented are Open, Close, Save,
 * Create, IsOpen, etc.
 * The second main set of methods to be implemented is starting from Do verb.
 * Those are: DoRetrieveDayEvents, DoRead_Event, DoUpdate_RPattern, etc.
 *
 * To use a descendant of CXTPCalendarData in a regular way you first
 * construct an instance of CXTPCalendarData object, then use Open()
 * member function to establish connection to the data source and
 * initialize the object. Class provides a number of functions to
 * manipulate events and events related data. After finishing working
 * with data source you should call Close() member function to close
 * connection, de-initialize the object and free unused resources.
 *
 * This class also contains an implementation of the data provider cache,
 * which is used by default and gets a great performance increase in case
 * when any slow connections are used (for example database connection).
 *
 * @see CXTPCalendarData overview
 * @see CXTPCalendarEvents
 * @see CXTPCalendarEvent
 * @see CXTPCalendarCustomDataProvider
 */
class _XTP_EXT_CLASS CXTPCalendarData : public CXTPCmdTarget
{
	friend class CXTPCalendarRecurrencePattern;
	friend class CXTPCalendarEvent;
	friend class CXTPCalendarOptions;
	friend class CXTPCalendarControl;
	/** @cond */
	DECLARE_DYNAMIC(CXTPCalendarData)
	/** @endcond */
public:
	/**
	 * @brief
	 * Default constructor.
	 *
	 * @details
	 * Constructs a Data object. To establish a connection to a
	 * specified data source and initialize the object, you must call
	 * the Open() member function immediately after construction.
	 *
	 * @see Open()
	 */
	CXTPCalendarData();

	/**
	 * @brief
	 * Default Destructor.
	 *
	 * @details
	 * Handles all deallocation.
	 */
	virtual ~CXTPCalendarData();

	/**
	 * @brief
	 * Call this member function to initialize a newly constructed
	 * Data object. Your data object must be created before you
	 * can call Open().
	 *
	 * @return Boolean value representing success/failure result.
	 */
	virtual BOOL Open();

	/**
	 * @brief
	 * Call this member function to create a file for storing custom
	 * data provider data.
	 *
	 * @details
	 * It will be opened by default.
	 *
	 * @return TRUE is successful. FALSE otherwise.
	 */
	virtual BOOL Create();

	/**
	 * @brief
	 * This method saves data to the file.
	 *
	 * @details
	 * The most recent data from the data provider will be saved in
	 * the same external file as before.
	 * Note that all the data inside the data provider is already up to
	 * date, this method just allows it to be saved externally.
	 *
	 * @return TRUE is successful. FALSE otherwise.
	 */
	virtual BOOL Save();

	/**
	 * @brief
	 * Call this member function to close the connection to a data source.
	 */
	virtual void Close();

	/**
	 * @brief
	 * This method determines whether a data source connection is opened.
	 *
	 * @return TRUE when a connection is already opened. FALSE otherwise.
	 */
	virtual BOOL IsOpen() const;

	/**
	 * @brief
	 * This method determines the type of the current Data Provider
	 * implementation.
	 *
	 * @return The current Data Provider implementation type.
	 *
	 * @see XTPCalendarDataProvider enumeration
	 */
	virtual XTPCalendarDataProvider GetType() const;

	/**
	 * @brief
	 * Retrieves day events for a specified day from the data source.
	 *
	 * @param dtDay A specified day.
	 *
	 * @details
	 * This method retrieves all appointments for a specified day from
	 * the data source. It includes recurrence appointments occurrences,
	 * regular appointments for this day, and multi-day appointments which
	 * also have a part of this day.
	 * This method uses the DoRetrieveDayEvents realization and implements
	 * some additional service processing.
	 *
	 * @return A collection of events for a specified day.
	 */
	virtual CXTPCalendarEventsPtr RetrieveDayEvents(COleDateTime dtDay);

	/**
	 * @brief
	 * Creates a new empty CXTPCalendarEvent object.
	 *
	 * @param dwEventID ID for a new event.
	 *
	 * @details
	 * This method creates a new CXTPCalendarEvent class and
	 * initializes its ID.
	 *
	 * It could be reimplemented in a descendant if it has its own
	 * ID's source (for example, database key field).
	 *
	 * @return Created empty event.
	 */
	virtual CXTPCalendarEventPtr CreateNewEvent(DWORD dwEventID = XTP_CALENDAR_UNKNOWN_EVENT_ID);

	/**
	 * @brief
	 * Creates a new empty CXTPCalendarRecurrencePattern object.
	 *
	 * @param dwPatternID ID for a new Recurrence Pattern.
	 *
	 * @details
	 * This method creates a new CXTPCalendarRecurrencePattern class and
	 * initializes its ID.
	 *
	 * It could be reimplemented in a descendant if it has its own
	 * ID's source (for example, database key field).
	 *
	 * @return Created empty Recurrence Pattern.
	 */
	virtual CXTPCalendarRecurrencePatternPtr
		CreateNewRecurrencePattern(DWORD dwPatternID = XTP_CALENDAR_UNKNOWN_RECURRENCE_PATTERN_ID);

	/**
	 * @brief
	 * Reads an event from the data source.
	 *
	 * @param dwEventID Event ID of the read target.
	 *
	 * @details
	 * This method retrieves all data for a specified event.
	 * This method uses DoRead_Event realization and implements
	 * some additional service processing.
	 *
	 * @return A pointer to the new CXTPCalendarEvent object in which fields
	 *		  are filled with data from the data source.
	 */
	virtual CXTPCalendarEventPtr GetEvent(DWORD dwEventID);

	/**
	 * @brief
	 * Reads a recurrence pattern from the data source.
	 *
	 * @param dwPatternID Pattern ID of the read target.
	 *
	 * @details
	 * This method retrieves all data for a specified recurrence pattern.
	 * This method uses DoRead_RPattern realization and implements
	 * some additional service processing.
	 *
	 * @return A pointer to the new CXTPCalendarRecurrencePatternPtr object in which
	 *		  fields are filled with data from the data source.
	 */
	virtual CXTPCalendarRecurrencePatternPtr GetRecurrencePattern(DWORD dwPatternID);

	/**
	 * @brief
	 * Creates a new event in the data source.
	 *
	 * @param pEvent Pointer to the CXTPCalendarEvent object which describes
	 *				all data fields of a newly created record.
	 *
	 * @details
	 * This method creates a data record corresponding with the
	 * specified event.
	 * This method uses DoCreate_Event realization and implements
	 * some additional service processing.
	 *
	 * @return TRUE if event created successfully,
	 *		  FALSE in case of any error during the process.
	 */
	virtual BOOL AddEvent(CXTPCalendarEvent* pEvent);

	/**
	 * @brief
	 * Creates a set of events in the data source.
	 *
	 * @param pEvents Pointer to the CXTPCalendarEvents collection which
	 *				 contains a number of CXTPCalendarEvent objects.
	 *
	 * @details
	 * This method adds a collection of events into the data source.
	 *
	 * @return TRUE if all events were added successfully,
	 *		  FALSE in case of any error during the process.
	 */
	virtual BOOL AddEvents(CXTPCalendarEvents* pEvents);

	/**
	 * @brief
	 * Removes all events from the data source.
	 *
	 * @details
	 * This method removes all appointments from the data source.
	 * This method uses DoRemoveAllEvents realization and implements
	 * some additional service processing.
	 */
	virtual void RemoveAllEvents();

	/**
	 * @brief
	 * Deletes an event from the data source.
	 *
	 * @param pEvent Pointer to the CXTPCalendarEvent object which describes
	 *				all data fields of an event.
	 *
	 * @details
	 * This method deletes a data record corresponding with the
	 * specified event.
	 * This method uses DoDelete_Event realization and implements
	 * some additional service processing.
	 *
	 * @return TRUE if an event deleted successfully,
	 *		  FALSE in case of any errors during the process.
	 */
	virtual BOOL DeleteEvent(CXTPCalendarEvent* pEvent);

	/**
	 * @brief
	 * Updates event properties in the data source.
	 *
	 * @param pNewEvent Pointer to the CXTPCalendarEvent object which describes
	 *				   all data fields of an event.
	 *
	 * @details
	 * This method updates a data record corresponding with the
	 * specified event.
	 * This method uses DoUpdate_Event realization and implements
	 * some additional service processing.
	 *
	 * @return TRUE if an event updated successfully,
	 *		  FALSE in case of any errors during the process.
	 */
	virtual BOOL ChangeEvent(CXTPCalendarEvent* pNewEvent);

	/**
	 * @brief
	 * Returns a connection pointer for the data source.
	 *
	 * @return A connection pointer.
	 *
	 * @see CXTPNotifyConnection overview
	 */
	virtual CXTPNotifyConnection* GetConnection() const;

	/**
	 * @brief
	 * Returns a custom properties collection.
	 *
	 * @return A custom properties collection associated with the data source.
	 *
	 * @see CXTPCalendarCustomProperties overview
	 */
	virtual CXTPCalendarCustomProperties* GetCustomProperties() const;

	/**
	 * @brief
	 * Returns a collection of Labels used in this Data source.
	 *
	 * @return A collection of Labels used in this Data source.
	 *		  By default it has some predefined values.
	 *
	 * @see CXTPCalendarEventLabels overview
	 * @see SetLabelList()
	 * @see CXTPCalendarEventLabels::InitDefaultValues
	 */
	virtual CXTPCalendarEventLabels* GetLabelList() const;

	/**
	 * @brief
	 * Returns a collection of Event categories.
	 *
	 * @return A collection of Event categories.
	 *		  By default it has some predefined values.
	 *
	 * @see CXTPCalendarEventCategories overview
	 * @see CXTPCalendarEventCategories::InitDefaultValues()
	 */
	virtual CXTPCalendarEventCategories* GetEventCategories() const;

	/**
	 * @brief
	 * Set custom collection of Labels to be used in this Data source.
	 *
	 * @param pLabelList A custom collection of Labels to be used there.
	 *
	 * @see CXTPCalendarEventLabels overview
	 * @see GetLabelList()
	 */
	virtual void SetLabelList(CXTPCalendarEventLabels* pLabelList);

	/**
	 * @brief
	 * Call this member function to add a new item to the event label list.
	 *
	 * @param nID Unique identifier for the label.
	 * @param strName Name of the list to add.
	 * @param crLabel Background base color for the list.
	 *
	 * @return TRUE if the item was added to the list, otherwise FALSE.
	 */
	virtual BOOL AddEventLabel(int nID, CString strName, COLORREF crLabel);

	/**
	 * @brief
	 * Call this member function to add a new item to the event
	 * category list.
	 *
	 * @param uID Unique identifier for the category.
	 * @param strName  Name of the category to add.
	 * @param crBorder Border color for the category.
	 * @param crBkBase Background base color for the category.
	 *
	 * @return TRUE if the item was added to the category list, otherwise FALSE.
	 */
	virtual BOOL AddEventCategory(UINT uID, CString strName, COLORREF crBorder, COLORREF crBkBase);

	/**
	 * @brief
	 * Update event labels colors when the theme is changed.
	 *
	 * @param clrEventColors An array of colors.
	 * @param uCount Number of items in the array above.
	 */
	virtual void UpdateEventLabels(COLORREF* clrEventColors, UINT uCount);

	/**
	 * @brief
	 * Call this member function to remove all items from the
	 * event category list.
	 */
	virtual void ClearEventCategoryList();

	/**
	 * @brief
	 * Call this member function to remove all items from the
	 * event label list.
	 */
	virtual void ClearEventLabelList();

	/**
	 * @brief
	 * Call this member function to restore the event category list
	 * to default values.
	 */
	virtual void RestoreEventCategoryList();

	/**
	 * @brief
	 * Call this member function to restore the event label list
	 * to default values.
	 */
	virtual void RestoreEventLabelList();

	/**
	 * @brief
	 * This member function updates the default colors of the category list
	 * when the theme is changed.
	 *
	 * @param pClrBkBase Array of COLORREF values representing the background
	 *					color for each category item.
	 * @param pClrBorder Array of COLORREF values represening the border
	 *			        color for each category item.
	 * @param nCount Size of pClrBack and pClrBorder arrays.
	 */
	void UpdateEventCategories(COLORREF* pClrBkBase, COLORREF* pClrBorder, int nCount);

	/**
	 * @brief
	 * Returns a collection of schedules used in this data source.
	 *
	 * @return A collection of schedules associated with the data source.
	 *
	 * @see CXTPCalendarSchedules overview.
	 */
	virtual CXTPCalendarSchedules* GetSchedules() const;

	/**
	 * @brief
	 * Sets a data provider connection string.
	 *
	 * @param lpszConnectionString A connection string.
	 *
	 * @see GetConnectionString()
	 * @see GetDataSource()
	 */
	virtual void SetConnectionString(LPCTSTR lpszConnectionString);

	/**
	 * @brief
	 * Returns a data provider connection string.
	 *
	 * @return Current connection string.
	 *
	 * @see SetConnectionString()
	 * @see GetDataSource()
	 */
	virtual CString GetConnectionString() const;

	/**
	 * @brief
	 * Returns a data provider data source.
	 *
	 * @return String with current data source settings.
	 *
	 * @details
	 * This method parses a connection string and returns a data source
	 * as a part of it.
	 *
	 * @see GetConnectionString()
	 * @see SetConnectionString()
	 */
	virtual CString GetDataSource();

	/**
	 * @brief
	 * Determines current cache mode.
	 * @return Current cache mode defined by the XTPCalendarDataProviderCacheMode enumeration.
	 * @see XTPCalendarDataProviderCacheMode enumeration
	 * @see SetCacheMode()
	 */
	virtual int GetCacheMode() const;

	/**
	 * @brief
	 * Sets common data provider cache mode.
	 *
	 * @param eCacheMode Cache mode. See XTPCalendarDataProviderCacheMode.
	 * @param pCacheDataProvider Data Provider object which you want to use
	 *							for cache purposes. By default it is
	 *							CXTPCalendarMemoryDataProvider.
	 *
	 * @details
	 * This method updates an internal cache mode.
	 *
	 * @see XTPCalendarDataProviderCacheMode enumeration
	 */
	virtual void SetCacheMode(int eCacheMode, CXTPCalendarData* pCacheDataProvider = NULL);

	/**
	 * @brief
	 * Clears common data provider cache.
	 */
	virtual void ClearCache();

	/**
	 * @brief
	 * Retrieves a collection of events expiring in the period from
	 * dtFrom during next spPeriod.
	 *
	 * @param dtFrom Start date and time of a specified period.
	 * @param spPeriod A duration of a specified period.
	 *
	 * @details
	 * This method is used by a reminders manager.
	 * This method uses DoGetUpcomingEvents realization and implements
	 * some additional service processing.
	 *
	 * @return A CXTPCalendarEvents pointer containing a collection of
	 *		  upcoming events.
	 *
	 * @see CXTPCalendarRemindersManager overview
	 */
	virtual CXTPCalendarEventsPtr GetUpcomingEvents(COleDateTime dtFrom		  = (DATE)0,
													COleDateTimeSpan spPeriod = (DATE)0);

	/**
	 * @brief
	 * This method Gets all events without generating recurrence
	 * occurrences.
	 *
	 * @details
	 * Simple events are included as is.
	 * For the recurrence events only master events are included,
	 * recurrence occurrences are not generated.
	 * This method uses DoGetAllEvents_raw realization and implements
	 * some additional service processing.
	 *
	 * @return A CXTPCalendarEvents pointer containing a collection of
	 *		  all events.
	 *
	 * @see _Save()
	 * @see Serialize()
	 * @see DoGetAllEvents_raw()
	 */
	virtual CXTPCalendarEventsPtr GetAllEvents_raw();

	BOOL m_bOwnershipMode;
	// flag to set protected mode of using Calendar when some schedules can be protected and other -
	// public
protected:
	/**
	 * @brief
	 * Retrieves day events for a specified day from the data source.
	 *
	 * @param dtDay A specified day.
	 *
	 * @details
	 * This method retrieves all appointments for a specified day from
	 * the data source. It includes recurrence appointments occurrences,
	 * regular appointments for this day, and multi-day appointments which
	 * also have a part of this day.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return A collection of events for a specified day.
	 */
	virtual CXTPCalendarEventsPtr DoRetrieveDayEvents(COleDateTime dtDay);

	/**
	 * @brief
	 * Removes all events from the data source.
	 *
	 * @details
	 * This method removes all appointments from the data source.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 */
	virtual void DoRemoveAllEvents();

	/**
	 * @brief
	 * Read event from the data source.
	 *
	 * @param dwEventID Event ID of the read target.
	 *
	 * @details
	 * This method retrieves all data for a specified event.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return A pointer to the new CXTPCalendarEvent object in which fields
	 *		  are filled with data from the data source.
	 */
	virtual CXTPCalendarEventPtr DoRead_Event(DWORD dwEventID);

	/**
	 * @brief
	 * Read recurrence pattern from the data source.
	 *
	 * @param dwPatternID Pattern ID of the read target.
	 *
	 * @details
	 * This method retrieves all data for a specified recurrence pattern.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return A pointer to the new CXTPCalendarRecurrencePatternPtr object in which
	 *		  fields are filled with data from the data source.
	 */
	virtual CXTPCalendarRecurrencePatternPtr DoRead_RPattern(DWORD dwPatternID);

	/**
	 * @brief
	 * Creates a new event in the data source.
	 *
	 * @param pEvent Pointer to the CXTPCalendarEvent object which describes
	 *				all data fields of a newly created record.
	 * @param rdwNewEventID [out] EventID of a newly created record.
	 *
	 * @details
	 * This method creates a data record corresponding with the
	 * specified event.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return TRUE if event created successfully,
	 *		  FALSE in case of any error during the process.
	 */
	virtual BOOL DoCreate_Event(CXTPCalendarEvent* pEvent, DWORD& rdwNewEventID);

	/**
	 * @brief
	 * Updates event properties in the data source.
	 *
	 * @param pEvent Pointer to the CXTPCalendarEvent object which describes
	 *				all data fields of an event.
	 *
	 * @details
	 * This method updates a data record corresponding with the
	 * specified event.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return TRUE if an event updated successfully,
	 *		  FALSE in case of any errors during the process.
	 */
	virtual BOOL DoUpdate_Event(CXTPCalendarEvent* pEvent);

	/**
	 * @brief
	 * Deletes an event from the data source.
	 *
	 * @param pEvent Pointer to the CXTPCalendarEvent object which describes
	 *          all data fields of an event.
	 *
	 * @details
	 * This method deletes a data record corresponding with the
	 * specified event.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return TRUE if an event deleted successfully,
	 *		  FALSE in case of any errors during the process.
	 */
	virtual BOOL DoDelete_Event(CXTPCalendarEvent* pEvent);

	/**
	 * @brief
	 * Creates a new recurrence pattern in the data source.
	 *
	 * @param pPattern Pointer to the CXTPCalendarRecurrencePattern object which
	 *				  describes all data fields of a newly created record.
	 * @param rdwNewPatternID [out] ID of a newly created record.
	 *
	 * @details
	 * This method creates a data record corresponding with the
	 * specified recurrence pattern.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return TRUE if recurrence pattern created successfully,
	 *		  FALSE in case of any error during the process.
	 */
	virtual BOOL DoCreate_RPattern(CXTPCalendarRecurrencePattern* pPattern, DWORD& rdwNewPatternID);

	/**
	 * @brief
	 * Updates a recurrence pattern in the database.
	 *
	 * @param pPattern Pointer to the CXTPCalendarRecurrencePattern object.
	 *
	 * @details
	 * This method updates a data record corresponding with the
	 * specified recurrence pattern.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return TRUE if recurrence pattern updated successfully,
	 *		  FALSE in case of any error during the process.
	 */
	virtual BOOL DoUpdate_RPattern(CXTPCalendarRecurrencePattern* pPattern);

	/**
	 * @brief
	 * Deletes a recurrence pattern from the database.
	 *
	 * @param pPattern Pointer to the CXTPCalendarRecurrencePattern object
	 *				  which should be deleted.
	 *
	 * @details
	 * This method deletes a data record corresponding with the
	 * specified recurrence pattern.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return TRUE if recurrence pattern deleted successfully,
	 *		  FALSE in case of any error during the process.
	 */
	virtual BOOL DoDelete_RPattern(CXTPCalendarRecurrencePattern* pPattern);

	/**
	 * @brief
	 * Retrieves a collection of events expiring in the period from
	 * dtFrom during next spPeriod.
	 *
	 * @param dtFrom Start date and time of a specified period.
	 * @param spPeriod A duration of a specified period.
	 *
	 * @details
	 * This method is used by a reminders manager.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return A CXTPCalendarEvents pointer containing a collection of
	 *		  upcoming events.
	 *
	 * @see CXTPCalendarRemindersManager overview
	 */
	virtual CXTPCalendarEventsPtr DoGetUpcomingEvents(COleDateTime dtFrom,
													  COleDateTimeSpan spPeriod);

	/**
	 * @brief
	 * Retrieves all events without generating
	 * recurrence occurrences.
	 *
	 * @details
	 * Simple events are included as is.
	 * For the recurrence events only master events are included,
	 * recurrence occurrences are not generated.
	 * It has empty implementation in this class and should be
	 * implemented by any custom realization of CXTPCalendarData.
	 *
	 * @return A CXTPCalendarEvents pointer containing a collection of
	 *		  all events.
	 *
	 * @see GetAllEvents_raw()
	 */
	virtual CXTPCalendarEventsPtr DoGetAllEvents_raw();

protected:
	/**
	 * @brief
	 * Sends a notification to all listeners.
	 *
	 * @param EventCode Notification event code.
	 * @param wParam First notification parameter.
	 * @param lParam Second notification parameter.
	 *
	 * @see CXTPNotifyConnection overview
	 */
	virtual void SendNotification(XTP_NOTIFY_CODE EventCode, WPARAM wParam, LPARAM lParam);

	/**
	 * @brief
	 *  This method is called by the calendar control framework when Time Zone is Changed.
	 *
	 * @details
	 *  The data provider implementation may use this method to adjust its data for
	 *  a new timezone.
	 *
	 * @return TRUE if internal data changed and calendar must be re-populated, FALSE if this
	 *		  event is ignored (no data changed).
	 *		  Base implementation does nothing and returns FALSE.
	 *
	 * @see CXTPTopLevelWndMsgNotifier, XTP_WM_TIME_ZONE_CHANGED
	 */
	virtual BOOL OnTimeZoneChanged()
	{
		return FALSE;
	};

	virtual BOOL _AddRPatternWithExceptions(CXTPCalendarRecurrencePattern* pPattern);
	virtual BOOL _RemoveRPatternWithExceptions(CXTPCalendarRecurrencePattern* pPattern);
	virtual BOOL _ChangeRPatternWithExceptions(CXTPCalendarRecurrencePattern* pRecurrencePattern);

	virtual BOOL _ChangeRExceptionOccurrence_nf(CXTPCalendarEvent* pExcOcc,
												BOOL bSend_EventDeleted);

	virtual void _PostProcessOccurrencesFromMaster(COleDateTime dtDay, CXTPCalendarEvents* pEvents);
	virtual void _PostProcessOccurrencesFromMaster2(COleDateTime dtDayFrom, COleDateTime dtDayTo,
													CXTPCalendarEvents* pEvents);

	virtual BOOL _PostProcessRecurrenceIfNeed(CXTPCalendarEvent* pEvent);
	virtual void _PostProcessRecurrenceIfNeed(CXTPCalendarEvents* pEvents);

	virtual void _FilterDayEventsInstancesByEndTime(COleDateTime dtDay,
													CXTPCalendarEvents* pEvents);

	virtual CXTPCalendarRecurrencePatternPtr _GetRecurrencePattern_raw(DWORD dwPatternID);
	virtual CXTPCalendarEventPtr _GetEvent_raw(DWORD dwEventID);

protected:
	BOOL m_bOpened; /**< Stores a flag whether a data source connection is open*/

	CXTPNotifyConnection* m_pConnection; /**< Connection object to send notifications.*/
	BOOL m_bDisableNotificationsSending; /**< Stores a flag whether notifications sending is
											disabled.*/

	CXTPCalendarEventLabels* m_pLabelList;			 /**< Event labels list.*/
	CXTPCalendarSchedules* m_pSchedules;			 /**< Data source Schedules list*/
	CXTPCalendarEventCategories* m_pEventCategories; /**< Store a collection of Event categories.*/

	CXTPCalendarCustomProperties* m_pCustomProperties; /**< Custom properties collection object.*/
protected:
	CString m_strConnectionString; /**< default connection string;*/

	XTPCalendarDataProvider m_typeProvider; /**< Data provider type.*/

	/**
	 * @details
	 * Implementation of the data provider cache.
	 */
	class _XTP_EXT_CLASS CXTPDPCache
	{
	public:
		/**
		 * @brief
		 * Default class constructor.
		 */
		CXTPDPCache();

		/**
		 * @brief
		 * Default class destructor.
		 */
		virtual ~CXTPDPCache();

		/**
		 * @brief
		 * Closes a cache.
		 */
		void SafeClose();

		/**
		 * @brief
		 * Safely removes all elements from the cache.
		 */
		void SafeRemoveAll();

		/**
		 * @brief
		 * Checks whether events for this day are already stored in the cache.
		 *
		 * @param dtDay A day to check.
		 *
		 * @return TRUE if day is already stored in cache,
		 *		  FALSE otherwise.
		 */
		virtual BOOL IsDayInCache(COleDateTime dtDay);

		/**
		 * @brief
		 * Sets a flag that this day is in the cache.
		 *
		 * @param dtDay A day to set.
		 * @param bSet Whether to set or clear flag.
		 */
		virtual void SetDayInCache(COleDateTime dtDay, BOOL bSet = TRUE);

		/**
		 * @brief
		 * Checks whether a specified event is already stored in the cache.
		 *
		 * @param pEvent An event to check.
		 *
		 * @return TRUE if an event is already stored in cache,
		 *		  FALSE otherwise.
		 */
		virtual BOOL IsEventInCache(CXTPCalendarEvent* pEvent);

		/**
		 * @brief
		 * Adds a collection of events to the cache for a specified day.
		 *
		 * @param pEvents An events collection.
		 * @param dtDay A specified day.
		 */
		virtual void AddToCache(CXTPCalendarEvents* pEvents, COleDateTime dtDay);

		/**
		 * @brief
		 * Checks whether a specified event is already stored in the cache
		 * and adds it there if not.
		 *
		 * @param pEvent An event to check / add.
		 */
		virtual void AddToCacheIfNeed(CXTPCalendarEvent* pEvent);

		/**
		 * @brief
		 * Checks whether a specified recurrence pattern is already
		 * stored in the cache and adds it there if not.
		 *
		 * @param pPattern An pattern to check / add.
		 */
		virtual void _AddToCacheIfNeed(CXTPCalendarRecurrencePattern* pPattern);

		CXTPCalendarData* m_pCacheDP; // Cache Data Provider.
		int m_eCacheMode;			  // see XTPCalendarDataProviderCacheMode

	protected:
		CMap<DWORD, DWORD, BOOL, BOOL> m_mapIsDayInCache; // whether events for this day are already
														  // stored in cache
	};

protected:
	CXTPDPCache m_cache; // Common data provider cache.

	/**
	 * @details
	 * This template class is used as a map (see CMap) to store
	 * ID and object pairs. Using the map allows for Quick Access
	 * using the ID.
	 *
	 * @see CMap
	 */
	template<class _TObject>
	class EventsMapByID_T
	{
	public:
		/**
		 * @brief
		 * Default class constructor.
		 *
		 * @param uHashTableSize Size of the map hash table.
		 *
		 * @see CMap
		 * @see CMap::InitHashTable
		 */
		EventsMapByID_T(UINT uHashTableSize = XTP_OBJECT_CACHE_HASH_TABLE_SIZE)
		{
			m_mapID2Object.InitHashTable(uHashTableSize, FALSE);
		};

		/**
		 * @brief
		 * Default class destructor.
		 *
		 * @details
		 * Handles member items deallocation. Decreases references of
		 * stored objects.
		 *
		 * @see CMap
		 */
		virtual ~EventsMapByID_T(){};

		/**
		 * @brief
		 * This member function is used to add new or to replace existing
		 * pairs of IDs and Objects.
		 *
		 * @param dwID Object ID.
		 * @param pObj Object Pointer.
		 *
		 * @details
		 * Call this method to add new or to replace existing
		 * elements in the map. InternalAddRef is called for the
		 * stored object.
		 *
		 * @see Get
		 * @see Remove
		 * @see CMap::SetAt
		 */
		void Add(DWORD dwID, _TObject* pObj)
		{
			if (!pObj)
			{
				_ASSERTE(FALSE);
				return;
			}
			TObjPtr ptrObj(pObj, TRUE);
			m_mapID2Object.SetAt(dwID, ptrObj);
		};

		/**
		 * @brief
		 * This member function is used to obtain a pointer to an object
		 * using the specified ID.
		 *
		 * @param dwID Object ID.
		 *
		 * @details
		 * Call this method to search for the object using the ID.
		 * InternalAddRef is called for the non-NULL returned object.
		 *
		 * @return Object pointer or NULL.
		 *
		 * @see Add
		 * @see CMap::Lookup
		 */
		_TObject* Get(DWORD dwID)
		{
			TObjPtr ptrObj;
			if (m_mapID2Object.Lookup(dwID, ptrObj) && !!ptrObj)
			{
				return (_TObject*)(CCmdTarget*)ptrObj;
			}
			return NULL;
		};

		/**
		 * @brief
		 * This member function is used to determine if an object with the
		 * specified ID exists.
		 *
		 * @param dwID Object ID.
		 *
		 * @details
		 * Similar to Get method, but calls InternalAddRef for
		 * the returned object.
		 *
		 * @return TRUE if object with ID exists. Otherwise FALSE.
		 *
		 * @see Get
		 * @see CMap::Lookup
		 */
		BOOL IsExist(DWORD dwID)
		{
			TObjPtr ptrObj;
			return m_mapID2Object.Lookup(dwID, ptrObj) && !!ptrObj;
		};

		/**
		 * @brief
		 * This member function is used to remove an object with the
		 * specified ID.
		 *
		 * @param dwID Object ID.
		 *
		 * @details
		 * Call this method to remove an element with the supplied ID
		 * from the map.
		 * InternalAddRef is called for the removed object.
		 *
		 * @return Nonzero if the entry was found and successfully removed; otherwise 0.
		 *
		 * @see Add
		 * @see RemoveAll
		 * @see CMap::RemoveKey
		 */
		BOOL Remove(DWORD dwID)
		{
			BOOL bRes = m_mapID2Object.RemoveKey(dwID);
			return bRes;
		};

		/**
		 * @brief
		 * This member function is used to remove all stored objects
		 * from the map.
		 *
		 * @details
		 * Call this method to cleanup the map.
		 * InternalAddRef is called for all objects.
		 *
		 * @see Remove
		 * @see CMap::RemoveAll
		 */
		void RemoveAll()
		{
			m_mapID2Object.RemoveAll();
		}

		/**
		 * @brief
		 * This member function is used to get the start iteration position.
		 *
		 * @return A POSITION value that indicates a starting position for
		 *		  iterating the map; or NULL if the map is empty.
		 *
		 * @see GetNextElement
		 * @see CMap::GetStartPosition
		 */
		POSITION GetStartPosition()
		{
			return m_mapID2Object.GetStartPosition();
		}

		/**
		 * @brief
		 *  This member function is used to get the next object pointer.
		 *
		 * @param rPos [in/out]  Iteration position of the element.
		 * @param rID [out]     Element ID.
		 *
		 * @details
		 *  Call this method to iterate on elements stored in the map.
		 *  InternalAddRef is not called for the returned object.
		 *  rPos parameter value is set to the element next position
		 *  or NULL if iterating is finished.
		 *
		 * @return A pointer to the object which corresponds to the specified
		 *		  position (rPos parameter value).
		 *
		 * @see GetStartPosition
		 * @see CMap::GetNextAssoc
		 */
		_TObject* GetNextElement(POSITION& rPos, DWORD& rID)
		{
			TObjPtr ptrElement;
			m_mapID2Object.GetNextAssoc(rPos, rID, ptrElement);
			return (_TObject*)(CCmdTarget*)ptrElement;
		}

		/**
		 * @brief
		 *  This member function is used to get object count.
		 *
		 * @return Count of the objects in the map.
		 *
		 * @see CMap::GetCount
		 */
		int GetCount()
		{
			return (int)m_mapID2Object.GetCount();
		}

	protected:
		/**
		 *   typedef CXTPSmartPtrInternalT<_TObject> TObjPtr;
		 *   Smart pointer object type.
		 *   to avoid warning C4786 CXTPCmdTarget used.
		 */
		typedef CXTPSmartPtrInternalT<CCmdTarget> TObjPtr;	/**< Smart pointer object type.*/
		CMap<DWORD, DWORD, TObjPtr, TObjPtr&> m_mapID2Object; /**< The map of ID to object.*/
	};

	/**
	 * @brief
	 * Call this member function to get a unique temporary event ID.
	 *
	 * @return New value for event ID.
	 */
	static DWORD AFX_CDECL GetNextFreeTempID();

	static DWORD ms_dwNextFreeTempID; /**< Next unique event ID.*/

	CXTPCalendarOptions* m_pCalendarOptions; /**< This member stores user's calendar view options.*/

public:
	/**
	 * @brief
	 * Call this method to create a data provider from
	 * a specified Calendar connection string.
	 *
	 * @param lpszConnectionString A text Calendar connection string.
	 *
	 * @details
	 * This is a helper method which creates calendar's data provider of
	 * the specified type with settings taken from the connection string.
	 *
	 * @return Pointer to the created Calendar Data Provider object.
	 */
	static CXTPCalendarData* AFX_CDECL CreateDataProvider(LPCTSTR lpszConnectionString);

	/**
	 * @brief
	 * Call this method to create a data provider of the
	 * specified type.
	 *
	 * @param eDataProvider A member of XTPCalendarDataProvider enumeration,
	 *					   which specifies a type of the Data Provider to create.
	 *
	 * @details
	 * This is a helper method which creates calendar's data provider of
	 * the specified type.
	 *
	 * @return Pointer to the created Calendar Data Provider object.
	 */
	static CXTPCalendarData* AFX_CDECL CreateDataProvider(XTPCalendarDataProvider eDataProvider);

	/**
	 * @brief
	 * Call this method to retrieve a type of the data provider from
	 * its connection string.
	 *
	 * @param lpszConnectionString A text Calendar connection string.
	 * @param eDPDefault Default data provider type to be returned if
	 *                   it can't be determined from the string.
	 *
	 * @details
	 * This is a helper method which parses a connection string and
	 * identifies a type of the data provider which is specified there.
	 *
	 * @return One of the values from XTPCalendarDataProvider enumeration.
	 *
	 * @see DataSourceFromConStr()
	 * @see CreateDataProvider()
	 */
	static XTPCalendarDataProvider AFX_CDECL DataProviderTypeFromConStr(
		LPCTSTR lpszConnectionString,
		XTPCalendarDataProvider eDPDefault = xtpCalendarDataProviderUnknown);

	/**
	 * @brief
	 * Call this method to retrieve a data source connection string from
	 * a regular Calendar connection string.
	 *
	 * @param lpszConnectionString A text Calendar connection string.
	 *
	 * @details
	 * This is a helper method which parses a connection string and
	 * identifies a data source connection string there.
	 *
	 * @return Identified data source connection string.
	 *
	 * @see DataProviderTypeFromConStr()
	 * @see CreateDataProvider()
	 */
	static CString AFX_CDECL DataSourceFromConStr(LPCTSTR lpszConnectionString);

private:
	void SetOptionsToUpdate(CXTPCalendarOptions* pOptions);

protected:
#	ifdef _XTP_ACTIVEX

	virtual BOOL OpenEx(LPDISPATCH pdispADOConnection);

	DECLARE_DISPATCH_MAP()
	DECLARE_INTERFACE_MAP()

	DECLARE_OLETYPELIB_EX(CXTPCalendarData);

	afx_msg LPDISPATCH OleCreateEvent();
	afx_msg LPDISPATCH OleCreateEventEx(long EventID);
	afx_msg LPDISPATCH OleCreateRecurrencePattern(long PatternID);

	afx_msg void OleAddEvent(LPDISPATCH Event);
	afx_msg void OleChangeEvent(LPDISPATCH Event);

	afx_msg BOOL OleOpen();
	afx_msg BOOL OleOpenEx(LPDISPATCH pdispADOConnection);

	afx_msg BOOL OleCreate();
	afx_msg void OleDeleteEvent(LPDISPATCH Event);
	afx_msg BSTR OleGetDataSource();
	afx_msg void OleClose();
	afx_msg void OleSave();
	afx_msg void OleRemoveAllEvents();
	afx_msg LPDISPATCH OleRetrieveDayEvents(DATE dt);
	afx_msg LPDISPATCH OleGetEvent(long EventID);
	afx_msg LPDISPATCH OleGetRecurrencePattern(long PatternID);

	afx_msg LPDISPATCH OleGetLabelList();

	afx_msg long OleGetCacheMode();
	afx_msg void OleSetCacheMode(long eCacheMode);

	afx_msg BOOL OleGetOwnershipMode();
	afx_msg void OleSetOwnershipMode(BOOL bMode);

	afx_msg void OleClearCache();

	afx_msg LPDISPATCH OleGetAllEventsRaw();
	afx_msg LPDISPATCH OleGetSchedules();
	afx_msg LPDISPATCH OleGetEventCategories();

#	endif
};

/////////////////////////////////////////////////////////////////////////////
AFX_INLINE BOOL CXTPCalendarData::Open()
{
	// _ASSERTE(!m_bOpened);
	return m_bOpened = TRUE;
}
AFX_INLINE BOOL CXTPCalendarData::Create()
{
	// _ASSERTE(!m_bOpened);
	return m_bOpened = TRUE;
}
AFX_INLINE BOOL CXTPCalendarData::IsOpen() const
{
	return m_bOpened;
}
AFX_INLINE BOOL CXTPCalendarData::Save()
{
	// _ASSERTE(m_bOpened);
	return TRUE;
}
AFX_INLINE void CXTPCalendarData::Close()
{
	// _ASSERTE(m_bOpened);

	m_cache.SafeClose();
	m_bOpened = FALSE;
}
AFX_INLINE CXTPNotifyConnection* CXTPCalendarData::GetConnection() const
{
	return m_pConnection;
}
AFX_INLINE DWORD AFX_CDECL CXTPCalendarData::GetNextFreeTempID()
{
	return ms_dwNextFreeTempID--;
}
AFX_INLINE CXTPCalendarEventLabels* CXTPCalendarData::GetLabelList() const
{
	return m_pLabelList;
}
AFX_INLINE CXTPCalendarEventCategories* CXTPCalendarData::GetEventCategories() const
{
	return m_pEventCategories;
}
AFX_INLINE CXTPCalendarSchedules* CXTPCalendarData::GetSchedules() const
{
	return m_pSchedules;
}

AFX_INLINE void CXTPCalendarData::SetConnectionString(LPCTSTR lpszConnectionString)
{
	_ASSERTE(lpszConnectionString);
	if (lpszConnectionString)
	{
		m_strConnectionString = lpszConnectionString;
	}
}
AFX_INLINE CString CXTPCalendarData::GetConnectionString() const
{
	return m_strConnectionString;
}
AFX_INLINE XTPCalendarDataProvider CXTPCalendarData::GetType() const
{
	return m_typeProvider;
}
AFX_INLINE int CXTPCalendarData::GetCacheMode() const
{
	return m_cache.m_eCacheMode;
}
AFX_INLINE CXTPCalendarCustomProperties* CXTPCalendarData::GetCustomProperties() const
{
	return m_pCustomProperties;
}

#	include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
#endif // !defined(_XTPCALENDARDATA_H__)