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