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 edu.wpi.first.networktables;
006
007/** NetworkTables publish/subscribe option. */
008public class PubSubOption {
009  enum Kind {
010    periodic,
011    sendAll,
012    topicsOnly,
013    pollStorage,
014    keepDuplicates,
015    disableRemote,
016    disableLocal,
017    excludePublisher,
018    excludeSelf;
019  }
020
021  PubSubOption(Kind kind, boolean value) {
022    m_kind = kind;
023    m_bValue = value;
024    m_iValue = 0;
025    m_dValue = 0;
026  }
027
028  PubSubOption(Kind kind, int value) {
029    m_kind = kind;
030    m_bValue = false;
031    m_iValue = value;
032    m_dValue = 0;
033  }
034
035  PubSubOption(Kind kind, double value) {
036    m_kind = kind;
037    m_bValue = false;
038    m_iValue = 0;
039    m_dValue = value;
040  }
041
042  /**
043   * How frequently changes will be sent over the network. NetworkTables may send more frequently
044   * than this (e.g. use a combined minimum period for all values) or apply a restricted range to
045   * this value. The default if unspecified is 100 ms.
046   *
047   * @param period time between updates, in seconds
048   * @return option
049   */
050  public static PubSubOption periodic(double period) {
051    return new PubSubOption(Kind.periodic, period);
052  }
053
054  /**
055   * If enabled, sends all value changes over the network. This option defaults to disabled.
056   *
057   * @param enabled True to enable, false to disable
058   * @return option
059   */
060  public static PubSubOption sendAll(boolean enabled) {
061    return new PubSubOption(Kind.sendAll, enabled);
062  }
063
064  /**
065   * If enabled on a subscription, does not request value changes. This option defaults to disabled.
066   *
067   * @param enabled True to enable, false to disable
068   * @return option
069   */
070  public static PubSubOption topicsOnly(boolean enabled) {
071    return new PubSubOption(Kind.topicsOnly, enabled);
072  }
073
074  /**
075   * If enabled, preserves duplicate value changes (rather than ignoring them). This option defaults
076   * to disabled.
077   *
078   * @param enabled True to enable, false to disable
079   * @return option
080   */
081  public static PubSubOption keepDuplicates(boolean enabled) {
082    return new PubSubOption(Kind.keepDuplicates, enabled);
083  }
084
085  /**
086   * Polling storage for subscription. Specifies the maximum number of updates NetworkTables should
087   * store between calls to the subscriber's readQueue() function. Defaults to 1 if sendAll is
088   * false, 20 if sendAll is true.
089   *
090   * @param depth number of entries to save for polling.
091   * @return option
092   */
093  public static PubSubOption pollStorage(int depth) {
094    return new PubSubOption(Kind.pollStorage, depth);
095  }
096
097  /**
098   * For subscriptions, specify whether remote value updates should not be queued for readQueue().
099   * See also disableLocal(). Defaults to false (remote value updates are queued).
100   *
101   * @param disabled True to disable, false to enable
102   * @return option
103   */
104  public static PubSubOption disableRemote(boolean disabled) {
105    return new PubSubOption(Kind.disableRemote, disabled);
106  }
107
108  /**
109   * For subscriptions, specify whether local value updates should not be queued for readQueue().
110   * See alse disableRemote(). Defaults to false (local value updates are queued).
111   *
112   * @param disabled True to disable, false to enable
113   * @return option
114   */
115  public static PubSubOption disableLocal(boolean disabled) {
116    return new PubSubOption(Kind.disableLocal, disabled);
117  }
118
119  /**
120   * Don't queue value updates for the given publisher. Only has an effect on subscriptions. Only
121   * one exclusion may be set.
122   *
123   * @param publisher publisher handle to exclude
124   * @return option
125   */
126  public static PubSubOption excludePublisher(int publisher) {
127    return new PubSubOption(Kind.excludePublisher, publisher);
128  }
129
130  /**
131   * Don't queue value updates for the given publisher. Only has an effect on subscriptions. Only
132   * one exclusion may be set.
133   *
134   * @param publisher publisher to exclude
135   * @return option
136   */
137  public static PubSubOption excludePublisher(Publisher publisher) {
138    return excludePublisher(publisher != null ? publisher.getHandle() : 0);
139  }
140
141  /**
142   * Don't queue value updates for the internal publisher for an entry. Only has an effect on
143   * entries.
144   *
145   * @param enabled True to enable, false to disable
146   * @return option
147   */
148  public static PubSubOption excludeSelf(boolean enabled) {
149    return new PubSubOption(Kind.excludeSelf, enabled);
150  }
151
152  final Kind m_kind;
153  final boolean m_bValue;
154  final int m_iValue;
155  final double m_dValue;
156}