/**
 * @file  XTPCalendarCustomDataProvider.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(_XTP_CALENDAR_CUSTOM_DATA_PROVIDER_H__)
#	define _XTP_CALENDAR_CUSTOM_DATA_PROVIDER_H__

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

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

/**
 * @brief
 * Custom implementation of XTPCalendarData based on notifications.
 *
 * @details
 * This class is the implementation of the XTPCalendarData abstract
 * class which represents a data portion of the Calendar control.
 *
 * This implementation is based on a notifications mechanism.
 * Each significant method sends a custom notification, which could be
 * handled by a user and where a custom data access code should be
 * implemented.
 *
 * @see CXTPCalendarData overview
 */
class _XTP_EXT_CLASS CXTPCalendarCustomDataProvider : public CXTPCalendarData
{
	/** @cond */
	DECLARE_DYNAMIC(CXTPCalendarCustomDataProvider)
	/** @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 Open() member function immediately after construction.
	 *
	 * @see Open()
	 */
	CXTPCalendarCustomDataProvider();

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

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

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.
	 *
	 * This implementation of the method sends a notification to
	 * XTP_NC_CALENDAR_DoRetrieveDayEvents which a user can handle and
	 * implement a custom method.
	 *
	 * @return A collection of events for a specified day.
	 *
	 * @see XTP_NC_CALENDAR_DoRetrieveDayEvents notification
	 */
	virtual CXTPCalendarEventsPtr DoRetrieveDayEvents(COleDateTime dtDay);

	/**
	 * @brief
	 * Removes all events from the data source.
	 *
	 * @details
	 * This method removes all appointments from the data source.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoRemoveAllEvents which a user can handle and
	 * implement a custom method.
	 *
	 * @see XTP_NC_CALENDAR_DoRemoveAllEvents notification
	 */
	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.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoRead_Event which a user can handle and
	 * implement a custom method.
	 *
	 * @return A pointer to the new CXTPCalendarEvent object in which fields
	 *		  are filled with data from the data source.
	 *
	 * @see XTP_NC_CALENDAR_DoRead_Event notification
	 */
	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.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoRead_RPattern which a user can handle and
	 * implement a custom method.
	 *
	 * @return A pointer to the new CXTPCalendarRecurrencePatternPtr object in which
	 *		  fields are filled with data from the data source.
	 *
	 * @see XTP_NC_CALENDAR_DoRead_RPattern notification
	 */
	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.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoCreate_Event which a user can handle and
	 * implement a custom method.
	 *
	 * @return TRUE if event created successfully,
	 *		  FALSE in case of any error during the process.
	 *
	 * @see XTP_NC_CALENDAR_DoCreate_Event notification
	 */
	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.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoUpdate_Event which a user can handle and
	 * implement a custom method.
	 *
	 * @return TRUE if an event updated successfully,
	 *		  FALSE in case of any errors during the process.
	 *
	 * @see XTP_NC_CALENDAR_DoUpdate_Event notification
	 */
	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.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoDelete_Event which a user can handle and
	 * implement a custom method.
	 *
	 * @return TRUE if an event deleted successfully,
	 *		  FALSE in case of any errors during the process.
	 *
	 * @see XTP_NC_CALENDAR_DoDelete_Event notification
	 */
	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.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoCreate_RPattern which a user can handle and
	 * implement a custom method.
	 *
	 * @return TRUE if recurrence pattern created successfully,
	 *		  FALSE in case of any error during the process.
	 *
	 * @see XTP_NC_CALENDAR_DoCreate_RPattern notification
	 */
	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.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoUpdate_RPattern which a user can handle and
	 * implement a custom method.
	 *
	 * @return TRUE if recurrence pattern updated successfully,
	 *		  FALSE in case of any error during the process.
	 *
	 * @see XTP_NC_CALENDAR_DoUpdate_RPattern notification
	 */
	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.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoDelete_RPattern which a user can handle and
	 * implement a custom method.
	 *
	 * @return TRUE if recurrence pattern deleted successfully,
	 *		  FALSE in case of any error during the process.
	 *
	 * @see XTP_NC_CALENDAR_DoDelete_RPattern notification
	 */
	virtual BOOL DoDelete_RPattern(CXTPCalendarRecurrencePattern* pPattern);

	/**
	 * @brief
	 * This method implements Getting all events without generating
	 * recurrence occurrences.
	 *
	 * @details
	 * This method actually implements working with the data source.
	 * Simple events are included as is.
	 *
	 * This implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoGetAllEvents_raw which a user can handle and
	 * implement a custom method.
	 *
	 * @return A CXTPCalendarEvents pointer containing a collection of
	 *		  all events.
	 *
	 * @see XTP_NC_CALENDAR_DoGetAllEvents_raw notification
	 * @see GetAllEvents_raw()
	 */
	virtual CXTPCalendarEventsPtr DoGetAllEvents_raw();

	/**
	 * @brief
	 * This method implements getting 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 implementation of the method sends a notification
	 * XTP_NC_CALENDAR_DoGetUpcomingEvents which a user can handle and
	 * implement a custom method.
	 *
	 * @return A CXTPCalendarEvents pointer containing a collection of
	 *		  upcoming events.
	 *
	 * @see CXTPCalendarRemindersManager overview
	 * @see XTP_NC_CALENDAR_DoGetUpcomingEvents notification
	 */
	virtual CXTPCalendarEventsPtr DoGetUpcomingEvents(COleDateTime dtFrom,
													  COleDateTimeSpan spPeriod);
};

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

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