|
LocalTimeRK
|
A complete time schedule. More...
#include <LocalTimeRK.h>
Public Member Functions | |
| LocalTimeSchedule () | |
| Construct a new, empty schedule. | |
| LocalTimeSchedule & | withMinuteOfHour (int increment, LocalTimeRange timeRange=LocalTimeRange()) |
| Adds a minute multiple schedule in a time range. More... | |
| LocalTimeSchedule & | withHourOfDay (int hourMultiple, LocalTimeRange timeRange=LocalTimeRange()) |
| Adds multiple times periodically in a time range with an hour increment. More... | |
| LocalTimeSchedule & | withDayOfWeekOfMonth (int dayOfWeek, int instance, LocalTimeRange timeRange=LocalTimeRange()) |
| Schedule an item on a specific instance of a day of week of the month. More... | |
| LocalTimeSchedule & | withDayOfMonth (int dayOfMonth, LocalTimeRange timeRange=LocalTimeRange()) |
| Schedule an item on a specific day of the month. More... | |
| LocalTimeSchedule & | withTime (LocalTimeHMSRestricted hms) |
| Add a scheduled item at a time in local time during the day. More... | |
| LocalTimeSchedule & | withTimes (std::initializer_list< LocalTimeHMSRestricted > timesParam) |
| Add multiple scheduled items at a time in local time during the day. More... | |
| LocalTimeSchedule & | withName (const char *name) |
| Sets the name of this schedule (optional) More... | |
| LocalTimeSchedule & | withFlags (uint32_t flags) |
| Sets the flags for this schedule (optional) More... | |
| bool | isEmpty () const |
| Returns true if the schedule does not have any items in it. More... | |
| void | clear () |
| Clear the existing settings. | |
| void | fromJson (const char *jsonStr) |
| Set the schedule from a JSON string containing an array of objects. More... | |
| void | fromJson (JSONValue jsonArray) |
| Set the schedule of this object from a JSONValue, typically the outer object. More... | |
| bool | getNextScheduledTime (LocalTimeConvert &conv) const |
| Update the conv object to point at the next schedule item. More... | |
| bool | getNextScheduledTime (LocalTimeConvert &conv, std::function< bool(LocalTimeScheduleItem &item)> filter) const |
| Update the conv object to point at the next schedule item. More... | |
| bool | isScheduledTime () |
| Determine if it's time to run the scheduled task based on the current time and internal nextTime member variable. More... | |
| bool | isScheduledTime (LocalTimeConvert &conv, time_t timeNow) |
| Low-level function used for unit testing. More... | |
Data Fields | |
| String | name |
| Name of this schedule (optional, typically used with LocalTimeScheduleManager) | |
| uint32_t | flags = 0 |
| Flags (optional, typically used with LocalTimeScheduleManager) | |
| time_t | nextTime = 0 |
| Optional, used with isScheduleTime() | |
| std::vector< LocalTimeScheduleItem > | scheduleItems |
| LocalTimeSchedule items. | |
A complete time schedule.
A time schedule consists of minute multiples ("every 15 minutes"), optionally within a time range (all day, or from 09:00:00 to 17:00:00 local time, for example.
It can also have hour multiples, optionally in a time range, at a defined minute ("every 4 hours at :15 past the hour").
Schedules can be at a specifc day week, with an ordinal (first Monday, last Friday) at a specific time, optionally with exceptions.
Schedules can be a specific day of the month (the 1st, the 5th of the month, the last day of the month, the second to last day of month).
It can also have any number of specific times in the day ("at 08:17:30 local time, 18:15:20 local time") every day, specific days of the week, on specific dates, or with date exceptions.
| void LocalTimeSchedule::fromJson | ( | const char * | jsonStr | ) |
Set the schedule from a JSON string containing an array of objects.
| jsonStr |
See the overload that takes a JSONValue if the JSON string has already been parsed.
| void LocalTimeSchedule::fromJson | ( | JSONValue | jsonArray | ) |
Set the schedule of this object from a JSONValue, typically the outer object.
| jsonArray | A JSONValue containing an array of objects |
Array of LocalTimeScheduleItem objects:
| bool LocalTimeSchedule::getNextScheduledTime | ( | LocalTimeConvert & | conv | ) | const |
Update the conv object to point at the next schedule item.
| conv | LocalTimeConvert object, may be modified |
This method finds closest scheduled time for this object, if it's in the relatively near future. The LocalTime::instance().getScheduleLookaheadDays() setting determines how far in the future to check; the default is 100 days. The way schedules work each day needs to be checked to make sure all of the constraints are met, so long look-aheads are computationally intensive.
| bool LocalTimeSchedule::getNextScheduledTime | ( | LocalTimeConvert & | conv, |
| std::function< bool(LocalTimeScheduleItem &item)> | filter | ||
| ) | const |
Update the conv object to point at the next schedule item.
| conv | LocalTimeConvert object, may be modified |
| filter | A function to determine, for each schedule item, if it should be tested |
This method finds closest scheduled time for this object, if it's in the relatively near future. The LocalTime::instance().getScheduleLookaheadDays() setting determines how far in the future to check; the default is 100 days. The way schedules work each day needs to be checked to make sure all of the constraints are met, so long look-aheads are computationally intensive.
The filter function or lambda has this prototype:
bool filterCallback(LocalTimeScheduleItem &item)
If should return true to check this item, or false to skip this item for schedule checking.
|
inline |
Returns true if the schedule does not have any items in it.
| bool LocalTimeSchedule::isScheduledTime | ( | ) |
Determine if it's time to run the scheduled task based on the current time and internal nextTime member variable.
| bool LocalTimeSchedule::isScheduledTime | ( | LocalTimeConvert & | conv, |
| time_t | timeNow | ||
| ) |
Low-level function used for unit testing.
| conv | |
| timeNow |
| LocalTimeSchedule & LocalTimeSchedule::withDayOfMonth | ( | int | dayOfMonth, |
| LocalTimeRange | timeRange = LocalTimeRange() |
||
| ) |
Schedule an item on a specific day of the month.
| dayOfMonth | 1 = 1st, 2 = 2nd of the month, ..., -1 = last day of the month, -2 = second to last day of the month, ... |
| timeRange | Optional to restrict dates or to set a time for the item |
| LocalTimeSchedule & LocalTimeSchedule::withDayOfWeekOfMonth | ( | int | dayOfWeek, |
| int | instance, | ||
| LocalTimeRange | timeRange = LocalTimeRange() |
||
| ) |
Schedule an item on a specific instance of a day of week of the month.
| dayOfWeek | Day of week 0 = Sunday, 1 = Monday, ..., 6 = Saturday |
| instance | 1 = first week, 2 = second week, ..., -1 = last week, -2 = 2nd to last week |
| timeRange | Optional to restrict dates or to set a time for the item |
|
inline |
| LocalTimeSchedule & LocalTimeSchedule::withHourOfDay | ( | int | hourMultiple, |
| LocalTimeRange | timeRange = LocalTimeRange() |
||
| ) |
Adds multiple times periodically in a time range with an hour increment.
| hourMultiple | Hours between items must be >= 1. For example: 2 = every other hour. |
| timeRange | Time range to add items to. This is optional; if not specified then the entire day. Also is used to specify a minute offset. |
Hours are per day, local time. For whole-day schedules, you will typically use a value that 24 is evenly divisible by (2, 3, 4, 6, 8, 12), because otherwise the time periods will brief unequal at midnight.
Also note that times are local, and take into account daylight saving. Thus during a time switch, the interval may end up being a different number of hours than specified. For example, if the times would have been 00:00 and 04:00, a hourMultiple of 4, and you do this over a spring forward, the actual number hours between 00:00 and 04:00 is 5 (at least in the US where DST starts at 2:00).
| LocalTimeSchedule & LocalTimeSchedule::withMinuteOfHour | ( | int | increment, |
| LocalTimeRange | timeRange = LocalTimeRange() |
||
| ) |
Adds a minute multiple schedule in a time range.
| increment | Number of minutes (must be 1 <= minutes <= 59). A value that is is divisible by is recommended. |
| timeRange | When to apply this minute multiple and/or minute offset (optional) |
This schedule publishes every n minutes within the hour. This really is every hour, not rolling, so you should use a value that 60 is divisible by (2, 3, 4, 5, 6, 10, 12, 15, 20, 30) otherwise there will be an inconsistent period at the top of the hour.
If you specify a time range that does not start at 00:00:00 you can customize which minute the schedule starts at. For example: 15, LocalTimeRange(LocalTimeHMS("00:05:00"), LocalTimeHMS("23:59:59") will schedule every 15 minutes, but starting at 5 minutes past the hour, so 05:00, 20:00, 35:00, 50:00.
The largest value for hmsEnd of the time range is 23:59:59.
|
inline |
| LocalTimeSchedule & LocalTimeSchedule::withTime | ( | LocalTimeHMSRestricted | hms | ) |
Add a scheduled item at a time in local time during the day.
| hms | The time in local time 00:00:00 to 23:59:59, optionally with date restrictions |
You can call this multiple times, and also combine it with minute multiple schedules.
| LocalTimeSchedule & LocalTimeSchedule::withTimes | ( | std::initializer_list< LocalTimeHMSRestricted > | timesParam | ) |
Add multiple scheduled items at a time in local time during the day.
| timesParam | an auto-initialized list of LocalTimeHMS objects |
You can call this multiple times, and also combine it with minute multiple schedules.
schedule.withTimes({LocalTimeHMS("06:00"), LocalTimeHMS("18:30")});
1.9.2