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.util.datalog;
006
007import edu.wpi.first.util.WPIUtilJNI;
008import java.nio.ByteBuffer;
009
010/**
011 * DataLog wpiutil JNI Functions.
012 *
013 * @see "wpiutil/DataLog.h"
014 */
015public class DataLogJNI extends WPIUtilJNI {
016  /**
017   * Create a new Data Log. The log will be initially created with a temporary filename.
018   *
019   * @param dir directory to store the log
020   * @param filename filename to use; if none provided, a random filename is generated of the form
021   *     "wpilog_{}.wpilog"
022   * @param period time between automatic flushes to disk, in seconds; this is a time/storage
023   *     tradeoff
024   * @param extraHeader extra header data
025   * @return data log implementation handle
026   */
027  static native long create(String dir, String filename, double period, String extraHeader);
028
029  /**
030   * Change log filename.
031   *
032   * @param impl data log implementation handle
033   * @param filename filename
034   */
035  static native void setFilename(long impl, String filename);
036
037  /**
038   * Explicitly flushes the log data to disk.
039   *
040   * @param impl data log implementation handle
041   */
042  static native void flush(long impl);
043
044  /**
045   * Pauses appending of data records to the log. While paused, no data records are saved (e.g.
046   * AppendX is a no-op). Has no effect on entry starts / finishes / metadata changes.
047   *
048   * @param impl data log implementation handle
049   */
050  static native void pause(long impl);
051
052  /**
053   * Resumes appending of data records to the log. If called after Stop(), opens a new file (with
054   * random name if SetFilename was not called after Stop()) and appends Start records and schema
055   * data values for all previously started entries and schemas.
056   *
057   * @param impl data log implementation handle
058   */
059  static native void resume(long impl);
060
061  /**
062   * Stops appending all records to the log, and closes the log file.
063   *
064   * @param impl data log implementation handle
065   */
066  static native void stop(long impl);
067
068  /**
069   * Registers a data schema. Data schemas provide information for how a certain data type string
070   * can be decoded. The type string of a data schema indicates the type of the schema itself (e.g.
071   * "protobuf" for protobuf schemas, "struct" for struct schemas, etc). In the data log, schemas
072   * are saved just like normal records, with the name being generated from the provided name:
073   * "/.schema/<name>". Duplicate calls to this function with the same name are silently
074   * ignored.
075   *
076   * @param impl data log implementation handle
077   * @param name Name (the string passed as the data type for records using this schema)
078   * @param type Type of schema (e.g. "protobuf", "struct", etc)
079   * @param schema Schema data
080   * @param timestamp Time stamp (may be 0 to indicate now)
081   */
082  static native void addSchema(long impl, String name, String type, byte[] schema, long timestamp);
083
084  static native void addSchemaString(
085      long impl, String name, String type, String schema, long timestamp);
086
087  /**
088   * Start an entry. Duplicate names are allowed (with the same type), and result in the same index
089   * being returned (Start/Finish are reference counted). A duplicate name with a different type
090   * will result in an error message being printed to the console and 0 being returned (which will
091   * be ignored by the Append functions).
092   *
093   * @param impl data log implementation handle
094   * @param name Name
095   * @param type Data type
096   * @param metadata Initial metadata (e.g. data properties)
097   * @param timestamp Time stamp (may be 0 to indicate now)
098   * @return Entry index
099   */
100  static native int start(long impl, String name, String type, String metadata, long timestamp);
101
102  /**
103   * Finish an entry.
104   *
105   * @param impl data log implementation handle
106   * @param entry Entry index
107   * @param timestamp Time stamp (may be 0 to indicate now)
108   */
109  static native void finish(long impl, int entry, long timestamp);
110
111  /**
112   * Updates the metadata for an entry.
113   *
114   * @param impl data log implementation handle
115   * @param entry Entry index
116   * @param metadata New metadata for the entry
117   * @param timestamp Time stamp (may be 0 to indicate now)
118   */
119  static native void setMetadata(long impl, int entry, String metadata, long timestamp);
120
121  /**
122   * Closes the data log implementation handle.
123   *
124   * @param impl data log implementation handle
125   */
126  static native void close(long impl);
127
128  /**
129   * Appends a raw record to the log.
130   *
131   * @param impl data log implementation handle
132   * @param entry Entry index, as returned by WPI_DataLog_Start()
133   * @param data Byte array to record
134   * @param len Length of byte array
135   * @param timestamp Time stamp (may be 0 to indicate now)
136   */
137  static native void appendRaw(
138      long impl, int entry, byte[] data, int start, int len, long timestamp);
139
140  /**
141   * Appends a raw record to the log.
142   *
143   * @param impl data log implementation handle
144   * @param entry Entry index, as returned by WPI_DataLog_Start()
145   * @param data ByteBuffer to record
146   * @param len Length of byte array
147   * @param timestamp Time stamp (may be 0 to indicate now)
148   */
149  static void appendRaw(long impl, int entry, ByteBuffer data, int start, int len, long timestamp) {
150    if (data.isDirect()) {
151      if (start < 0) {
152        throw new IndexOutOfBoundsException("start must be >= 0");
153      }
154      if (len < 0) {
155        throw new IndexOutOfBoundsException("len must be >= 0");
156      }
157      if ((start + len) > data.capacity()) {
158        throw new IndexOutOfBoundsException("start + len must be smaller than buffer capacity");
159      }
160      appendRawBuffer(impl, entry, data, start, len, timestamp);
161    } else if (data.hasArray()) {
162      appendRaw(impl, entry, data.array(), data.arrayOffset() + start, len, timestamp);
163    } else {
164      throw new UnsupportedOperationException("ByteBuffer must be direct or have a backing array");
165    }
166  }
167
168  private static native void appendRawBuffer(
169      long impl, int entry, ByteBuffer data, int start, int len, long timestamp);
170
171  /**
172   * Appends a boolean record to the log.
173   *
174   * @param impl data log implementation handle
175   * @param entry Entry index, as returned by Start()
176   * @param value Boolean value to record
177   * @param timestamp Time stamp (may be 0 to indicate now)
178   */
179  static native void appendBoolean(long impl, int entry, boolean value, long timestamp);
180
181  /**
182   * Appends an integer record to the log.
183   *
184   * @param impl data log implementation handle
185   * @param entry Entry index, as returned by Start()
186   * @param value Integer value to record
187   * @param timestamp Time stamp (may be 0 to indicate now)
188   */
189  static native void appendInteger(long impl, int entry, long value, long timestamp);
190
191  /**
192   * Appends a float record to the log.
193   *
194   * @param impl data log implementation handle
195   * @param entry Entry index, as returned by Start()
196   * @param value Float value to record
197   * @param timestamp Time stamp (may be 0 to indicate now)
198   */
199  static native void appendFloat(long impl, int entry, float value, long timestamp);
200
201  /**
202   * Appends a double record to the log.
203   *
204   * @param impl data log implementation handle
205   * @param entry Entry index, as returned by Start()
206   * @param value Double value to record
207   * @param timestamp Time stamp (may be 0 to indicate now)
208   */
209  static native void appendDouble(long impl, int entry, double value, long timestamp);
210
211  /**
212   * Appends a string record to the log.
213   *
214   * @param impl data log implementation handle
215   * @param entry Entry index, as returned by Start()
216   * @param value String value to record
217   * @param timestamp Time stamp (may be 0 to indicate now)
218   */
219  static native void appendString(long impl, int entry, String value, long timestamp);
220
221  /**
222   * Appends a boolean array record to the log.
223   *
224   * @param impl data log implementation handle
225   * @param entry Entry index, as returned by Start()
226   * @param arr Boolean array to record
227   * @param timestamp Time stamp (may be 0 to indicate now)
228   */
229  static native void appendBooleanArray(long impl, int entry, boolean[] value, long timestamp);
230
231  /**
232   * Appends an integer array record to the log.
233   *
234   * @param impl data log implementation handle
235   * @param entry Entry index, as returned by Start()
236   * @param arr Integer array to record
237   * @param timestamp Time stamp (may be 0 to indicate now)
238   */
239  static native void appendIntegerArray(long impl, int entry, long[] value, long timestamp);
240
241  /**
242   * Appends a float array record to the log.
243   *
244   * @param impl data log implementation handle
245   * @param entry Entry index, as returned by Start()
246   * @param arr Float array to record
247   * @param timestamp Time stamp (may be 0 to indicate now)
248   */
249  static native void appendFloatArray(long impl, int entry, float[] value, long timestamp);
250
251  /**
252   * Appends a double array record to the log.
253   *
254   * @param impl data log implementation handle
255   * @param entry Entry index, as returned by Start()
256   * @param arr Double array to record
257   * @param timestamp Time stamp (may be 0 to indicate now)
258   */
259  static native void appendDoubleArray(long impl, int entry, double[] value, long timestamp);
260
261  /**
262   * Appends a string array record to the log.
263   *
264   * @param impl data log implementation handle
265   * @param entry Entry index, as returned by Start()
266   * @param arr String array to record
267   * @param timestamp Time stamp (may be 0 to indicate now)
268   */
269  static native void appendStringArray(long impl, int entry, String[] value, long timestamp);
270
271  /** Utility class. */
272  private DataLogJNI() {}
273}