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