# SFBAlarm Class Reference

Manage "alarm clock"-style settable timers. More...

`#include <SFBAlarm.h>`

## Public Member Functions
u32 | create (SFBAlarmHandler handler)
| Create a new alarm, return its corresponding alarm number.
u32 | create (SFBAlarmArgHandler handler, void *arg)
| Create a new alarm, return its corresponding alarm number.
void | update (u32 alarmNumber, SFBAlarmHandler handler)
void | update (u32 alarmNumber, SFBAlarmArgHandler handler, void *arg)
u32 | get (u32 alarmNumber)
| If alarm alarmNumber is set, access the alarm time.
bool | set (u32 alarmNumber, u32 when)
| Set (or reset) alarm alarmNumber to go off at when.
bool | cancel (u32 alarmNumber)
| Cancel any pending alarm for alarm alarmNumber.
u32 | currentAlarmNumber ()
| What alarm is active? This method should be called only during a callback to an alarm handler; its return value is not defined elsewhere.
int | runDueEvents (int maxEvents, u32 deadline)
int | runPriorityEvents (int maxEvents, u32 priorityAtLeast)
bool | canCreate ()
| Determine if it is possible to create another alarm.
u32 | created ()
bool | canAdd ()
bool | canRemove ()
u32 | count ()
bool | inUse (u32 alarmIndex)
u32 | getTopTime ()
| Get the earliest time in the queue.
int | getUsed ()

## Detailed Description

Manage "alarm clock"-style settable timers.

## Member Function Documentation

bool SFBAlarm::cancel | ( | u32 | alarmNumber | ) |

Cancel any pending alarm for alarm alarmNumber.

Parameters:

  | alarmNumber | The alarm to cancel

Returns:
  `true` if the alarm had been currently set, `false` if not.

Blinks:
  E_API_BAD_ALARM if alarmNumber is not an alarm number previously returned by create(SFBAlarmHandler) or create(SFBAlarmArgHandler,void*)

bool SFBAlarm::canCreate | ( |  | ) |

Determine if it is possible to create another alarm.

The alarm creating functions create(SFBAlarmHandler) and create(SFBAlarmArgHandler,void*) die blinking if they are called when there's no more room to create an additional alarm. To avoid that risk, a sketch may call this function first.

Returns:
  `true` if at least one more alarm can be created, `false` otherwise.

u32 SFBAlarm::create | ( | SFBAlarmArgHandler | handler,
|  | void * | arg |
| ) |  |  |

Create a new alarm, return its corresponding alarm number.

Note this method blinks E_API_NO_MORE_ALARMS if no more alarms are available; if a sketch needs to survive running out of alarms it must call canCreate() to ascertain another alarm is available before calling this method.

Parameters:

  | handler | function to call whenever this alarm goes off
  | arg | an arbitrary pointer value to associate with this alarm, which will be provided to handler whenever the alarm goes off.

Returns:
  a non-zero `alarmNumber` to use to refer to this alarm in the future

Blinks:
  E_API_NO_MORE_ALARMS if the alarm system is full so a new alarm could not be created.

u32 SFBAlarm::create | ( | SFBAlarmHandler | handler | ) |

Create a new alarm, return its corresponding alarm number.

Note this method blinks E_API_NO_MORE_ALARMS if no more alarms are available; if a sketch needs to survive running out of alarms it must call canCreate() to ascertain another alarm is available before calling this method.

Parameters:

  | handler | function to call whenever this alarm goes off

Returns:
  a non-zero `alarmNumber` to use to refer to this alarm in the future

Blinks:
  E_API_NO_MORE_ALARMS if the alarm system is full so a new alarm could not be created.

Examples:
  alarm1.cpp, alarm2.cpp, and alarm3.cpp.

u32 SFBAlarm::currentAlarmNumber | ( |  | ) | `[inline]`

What alarm is active? This method should be called only during a callback to an alarm handler; its return value is not defined elsewhere.

Returns:
  The alarm number that triggered the current alarm handler callback.

Examples:
  alarm2.cpp.

u32 SFBAlarm::get | ( | u32 | alarmNumber | ) |

If alarm alarmNumber is set, access the alarm time.

If alarmNumber is not set, returns the most recent previous alarm time; if alarmNumber has never been set, return 0.

Parameters:

  | alarmNumber | The alarm to access

Returns:
  the current or most-recent alarm setting, or zero

Blinks:
  E_API_BAD_ALARM if alarmNumber is not an alarm number previously returned by create(SFBAlarmHandler) or create(SFBAlarmArgHandler,void*)

Since:
  0.9.5

u32 SFBAlarm::getTopTime | ( |  | ) | `[inline]`

Get the earliest time in the queue.

Only valid when canRemoveEvent() returns true.

bool SFBAlarm::set | ( | u32 | alarmNumber,
|  | u32 | when |
| ) |  |  |

Set (or reset) alarm alarmNumber to go off at when.

If when is in the past relative to millis() (in the sense of IS_EARLIER), the alarm will go off at its soonest possible opportunity.

Parameters:

  | alarmNumber | The alarm to set

Returns:
  `true` if the alarm was currently set, `false` if not.

Blinks:
  E_API_BAD_ALARM if alarmNumber is not an alarm number previously returned by create(SFBAlarmHandler) or create(SFBAlarmArgHandler,void*)

Examples:
  alarm1.cpp, alarm2.cpp, and alarm3.cpp.

The documentation for this class was generated from the following files:

- src/include/SFBAlarm.h
- src/components/library/SFBAlarm.cpp