/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2012 Raritan Inc. All rights reserved.
 */

#ifndef __EVENT_TIMEREVENTMANAGER_IDL__
#define __EVENT_TIMEREVENTMANAGER_IDL__

/** Event interface */
module event {

    /** TimerEventManager interface */
    interface TimerEventManager_2_0_0 {

	/** Error codes */
	constant int NO_ERROR			= 0;	///< operation successful, no error
	constant int ERR_INVALID_SCHEDULE	= 1;	///< failure in schedule
	constant int ERR_UNKNOWN_EVENT_ID	= 2;	///< unknown eventId
	constant int ERR_CREATE_EVENT_ID_FAILED	= 3;	///< creating eventId failed
	constant int ERR_MAX_TIMERS_CREATED	= 4;	///< max number of timers have been created

	/**
	 * Schedule defines and structures
	 *
	 * The goal of the  following declarations is 
	 * to express crontab entries in a structured way. 
	 */
	/** Months */
	constant int JAN	= 1;	///< January
	constant int FEB	= 2;	///< February
	constant int MAR	= 3;	///< March
	constant int APR	= 4;	///< April
	constant int MAY	= 5;	///< May
	constant int JUN	= 6;	///< June
	constant int JUL	= 7;	///< July
	constant int AUG	= 8;	///< August
	constant int SEP	= 9;	///< September
	constant int OCT	= 10;	///< October
	constant int NOV	= 11;	///< November
	constant int DEC	= 12;	///< December
	/** Days of week */
	constant int SUN	= 0;	///< Sunday
	constant int MON	= 1;	///< Monday
	constant int TUE	= 2;	///< Tuesday
	constant int WED	= 3;	///< Wednesday
	constant int THU	= 4;	///< Thursday
	constant int FRI	= 5;	///< Friday
	constant int SAT	= 6;	///< Saturday
	/**
	 * Range structure
	 *
	 * A range defines a time between start and end point in time.
	 * If start and end point are the same it is a specific point in time 
	 * and no range. Step defines the repeating interval in time.
	 * Step of 1 is default and matches all values in range.
	 */
	structure Range {
	    int start;			///< Start time
	    int end;			///< End time
	    int step;			///< Step
	};
	/**
	 * Schedule structure
	 *
	 * An empty vector means a match for all values.
	 * The values range of every field depends on the meaning of the field.
	 * For minutes 0-59 is possible, for hour 0-24 and for day of month 0-31.
	 * For month and day of weeks the definitions above should be used.
	 */
	structure Schedule {
	    boolean enabled;		///< Whether the timer event is enabled
	    vector<Range> minute;	///< Ranges for minute
	    vector<Range> hour;		///< Ranges for hour
	    vector<Range> dayOfMonth;	///< Ranges for day of month
	    vector<Range> month;	///< Ranges for month
	    vector<Range> dayOfWeek;	///< Ranges for day of week
	};

	/**
	 * TimerEvent structure
	 *
	 * A TimerEvent can be used in the event engine to run actions
	 * at a specified time.
	 * The 'eventId' is an unique identification of every timer event.
	 * The 'executionTime' contains the schedule for the execution time. 
	 */
	structure TimerEvent {
	    vector<string> eventId;	///< Event ID
	    Schedule executionTime;	///< Schedule for execution time
	};

	/**
	 * Add a new timer event.
	 *
	 * The timer event id field is allocated automatically 
	 * and returned in the timerEventId parameter.
	 *
	 * @param  schedule			schedule for timer
	 * @param  eventId			created event id
	 * @return NO_ERROR			if OK
	 * @return ERR_INVALID_SCHEDULE		if schedule is invalid
	 * @return ERR_CREATE_EVENT_ID_FAILED	if generating the eventId failed
	 * @return ERR_MAX_TIMERS_CREATED	if max timer count already created
	 */
	int addTimerEvent(in Schedule schedule, out vector<string> eventId);

	/**
	 * Modify a timer event.
	 *
	 * @param  eventId			event id
	 * @param  schedule			new schedule for timer
	 * @return NO_ERROR			if OK
	 * @return ERR_INVALID_SCHEDULE		if schedule is invalid
	 * @return ERR_UNKNOWN_EVENT_ID		if eventId is unknown
	 */
	int modifyTimerEvent(in vector<string> eventId, in Schedule schedule);

	/**
	 * Delete a timer event.
	 *
	 * @param  eventId			event id
	 * @return NO_ERROR			if OK
	 * @return ERR_UNKNOWN_EVENT_ID		if eventId is unknown
	 */
	int deleteTimerEvent(in vector<string> eventId);

	/**
	 * List all timer events.
	 */
	vector<TimerEvent> listTimerEvents();

    };

}

#endif /* __EVENT_TIMEREVENTMANAGER_IDL__ */
