001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package org.wpilib.hardware.hal;
006
007/**
008 * The NotifierJNI class directly wraps the C++ HAL Notifier.
009 *
010 * <p>This class is not meant for direct use by teams. Instead, the org.wpilib.system.Notifier
011 * class, which corresponds to the C++ Notifier class, should be used.
012 *
013 * @see "wpi/hal/Notifier.h"
014 */
015public class NotifierJNI extends JNIWrapper {
016  /**
017   * Creates a notifier.
018   *
019   * <p>A notifier is an timer that alarms at an initial and (optionally) repeated intervals. This
020   * can be used to make precise control loops.
021   *
022   * @return the created notifier
023   * @see "HAL_CreateNotifier"
024   */
025  public static native int createNotifier();
026
027  /**
028   * Sets the name of the notifier.
029   *
030   * @param notifierHandle Notifier handle.
031   * @param name Notifier name.
032   * @see "HAL_SetNotifierName"
033   */
034  public static native void setNotifierName(int notifierHandle, String name);
035
036  /**
037   * Destroys a notifier.
038   *
039   * <p>Destruction wakes up any waiters.
040   *
041   * @param notifierHandle the notifier handle
042   * @see "HAL_DestroyNotifier"
043   */
044  public static native void destroyNotifier(int notifierHandle);
045
046  /**
047   * Updates the initial and interval alarm times for a notifier.
048   *
049   * <p>The alarmTime is an absolute time (using the WPI now() time base) if absolute is true, or
050   * relative to the current time if absolute is false.
051   *
052   * <p>If intervalTime is non-zero, the notifier will alarm periodically following alarmTime at the
053   * given interval.
054   *
055   * <p>If an absolute alarmTime is in the past, the notifier will alarm immediately.
056   *
057   * @param notifierHandle the notifier handle
058   * @param alarmTime the first alarm time (in microseconds)
059   * @param intervalTime the periodic interval time (in microseconds)
060   * @param absolute true if the alarm time is absolute
061   * @param ack true to acknowledge any prior alarm
062   * @see "HAL_SetNotifierAlarm"
063   */
064  public static native void setNotifierAlarm(
065      int notifierHandle, long alarmTime, long intervalTime, boolean absolute, boolean ack);
066
067  /**
068   * Cancels all future notifier alarms for a notifier.
069   *
070   * @param notifierHandle the notifier handle
071   * @param ack true to acknowledge any prior alarm
072   * @see "HAL_CancelNotifierAlarm"
073   */
074  public static native void cancelNotifierAlarm(int notifierHandle, boolean ack);
075
076  /**
077   * Indicates the notifier alarm has been serviced. Makes no change to future alarms.
078   *
079   * <p>One of setNotifierAlarm (with ack=true), cancelNotifierAlarm (with ack=true), or this
080   * function must be called before waiting for the next alarm.
081   *
082   * @param notifierHandle the notifier handle
083   * @see "HAL_AcknowledgeNotifierAlarm"
084   */
085  public static native void acknowledgeNotifierAlarm(int notifierHandle);
086
087  /**
088   * Gets the overrun count for a notifier.
089   *
090   * <p>An overrun occurs when a notifier's alarm is not serviced before the next scheduled alarm
091   * time.
092   *
093   * @param notifierHandle the notifier handle
094   * @return overrun count
095   */
096  public static native int getNotifierOverrun(int notifierHandle);
097
098  /** Utility class. */
099  private NotifierJNI() {}
100}