Source code

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   * Create a new Data Log foreground writer to a memory buffer.
051   *
052   * @param extraHeader extra header data
053   * @return data log writer implementation handle
054   */
055  static native long fgCreateMemory(String extraHeader);
056
057  /**
058   * Explicitly flushes the log data to disk.
059   *
060   * @param impl data log background writer implementation handle
061   */
062  static native void flush(long impl);
063
064  /**
065   * Flushes the log data to a memory buffer (only valid with fgCreateMemory data logs).
066   *
067   * @param impl data log background writer implementation handle
068   * @param buf output data buffer
069   * @param pos position in write buffer to start copying from
070   * @return Number of bytes written to buffer; 0 if no more to copy
071   */
072  static native int copyWriteBuffer(long impl, byte[] buf, int pos);
073
074  /**
075   * Pauses appending of data records to the log. While paused, no data records are saved (e.g.
076   * AppendX is a no-op). Has no effect on entry starts / finishes / metadata changes.
077   *
078   * @param impl data log background writer implementation handle
079   */
080  static native void pause(long impl);
081
082  /**
083   * Resumes appending of data records to the log. If called after Stop(), opens a new file (with
084   * random name if SetFilename was not called after Stop()) and appends Start records and schema
085   * data values for all previously started entries and schemas.
086   *
087   * @param impl data log background writer implementation handle
088   */
089  static native void resume(long impl);
090
091  /**
092   * Stops appending all records to the log, and closes the log file.
093   *
094   * @param impl data log background writer implementation handle
095   */
096  static native void stop(long impl);
097
098  /**
099   * Registers a data schema. Data schemas provide information for how a certain data type string
100   * can be decoded. The type string of a data schema indicates the type of the schema itself (e.g.
101   * "protobuf" for protobuf schemas, "struct" for struct schemas, etc). In the data log, schemas
102   * are saved just like normal records, with the name being generated from the provided name:
103   * "/.schema/&lt;name&gt;". Duplicate calls to this function with the same name are silently
104   * ignored.
105   *
106   * @param impl data log implementation handle
107   * @param name Name (the string passed as the data type for records using this schema)
108   * @param type Type of schema (e.g. "protobuf", "struct", etc)
109   * @param schema Schema data
110   * @param timestamp Time stamp (may be 0 to indicate now)
111   */
112  static native void addSchema(long impl, String name, String type, byte[] schema, long timestamp);
113
114  static native void addSchemaString(
115      long impl, String name, String type, String schema, long timestamp);
116
117  /**
118   * Start an entry. Duplicate names are allowed (with the same type), and result in the same index
119   * being returned (Start/Finish are reference counted). A duplicate name with a different type
120   * will result in an error message being printed to the console and 0 being returned (which will
121   * be ignored by the Append functions).
122   *
123   * @param impl data log implementation handle
124   * @param name Name
125   * @param type Data type
126   * @param metadata Initial metadata (e.g. data properties)
127   * @param timestamp Time stamp (may be 0 to indicate now)
128   * @return Entry index
129   */
130  static native int start(long impl, String name, String type, String metadata, long timestamp);
131
132  /**
133   * Finish an entry.
134   *
135   * @param impl data log implementation handle
136   * @param entry Entry index
137   * @param timestamp Time stamp (may be 0 to indicate now)
138   */
139  static native void finish(long impl, int entry, long timestamp);
140
141  /**
142   * Updates the metadata for an entry.
143   *
144   * @param impl data log implementation handle
145   * @param entry Entry index
146   * @param metadata New metadata for the entry
147   * @param timestamp Time stamp (may be 0 to indicate now)
148   */
149  static native void setMetadata(long impl, int entry, String metadata, long timestamp);
150
151  /**
152   * Closes the data log implementation handle.
153   *
154   * @param impl data log implementation handle
155   */
156  static native void close(long impl);
157
158  /**
159   * Appends a raw record to the log.
160   *
161   * @param impl data log implementation handle
162   * @param entry Entry index, as returned by WPI_DataLog_Start()
163   * @param data Byte array to record
164   * @param len Length of byte array
165   * @param timestamp Time stamp (may be 0 to indicate now)
166   */
167  static native void appendRaw(
168      long impl, int entry, byte[] data, int start, int len, long timestamp);
169
170  /**
171   * Appends a raw record to the log.
172   *
173   * @param impl data log implementation handle
174   * @param entry Entry index, as returned by WPI_DataLog_Start()
175   * @param data ByteBuffer to record
176   * @param len Length of byte array
177   * @param timestamp Time stamp (may be 0 to indicate now)
178   */
179  static void appendRaw(long impl, int entry, ByteBuffer data, int start, int len, long timestamp) {
180    if (data.isDirect()) {
181      if (start < 0) {
182        throw new IndexOutOfBoundsException("start must be >= 0");
183      }
184      if (len < 0) {
185        throw new IndexOutOfBoundsException("len must be >= 0");
186      }
187      if ((start + len) > data.capacity()) {
188        throw new IndexOutOfBoundsException("start + len must be smaller than buffer capacity");
189      }
190      appendRawBuffer(impl, entry, data, start, len, timestamp);
191    } else if (data.hasArray()) {
192      appendRaw(impl, entry, data.array(), data.arrayOffset() + start, len, timestamp);
193    } else {
194      throw new UnsupportedOperationException("ByteBuffer must be direct or have a backing array");
195    }
196  }
197
198  private static native void appendRawBuffer(
199      long impl, int entry, ByteBuffer data, int start, int len, long timestamp);
200
201  /**
202   * Appends a boolean record to the log.
203   *
204   * @param impl data log implementation handle
205   * @param entry Entry index, as returned by Start()
206   * @param value Boolean value to record
207   * @param timestamp Time stamp (may be 0 to indicate now)
208   */
209  static native void appendBoolean(long impl, int entry, boolean value, long timestamp);
210
211  /**
212   * Appends an integer record to the log.
213   *
214   * @param impl data log implementation handle
215   * @param entry Entry index, as returned by Start()
216   * @param value Integer value to record
217   * @param timestamp Time stamp (may be 0 to indicate now)
218   */
219  static native void appendInteger(long impl, int entry, long value, long timestamp);
220
221  /**
222   * Appends a float record to the log.
223   *
224   * @param impl data log implementation handle
225   * @param entry Entry index, as returned by Start()
226   * @param value Float value to record
227   * @param timestamp Time stamp (may be 0 to indicate now)
228   */
229  static native void appendFloat(long impl, int entry, float value, long timestamp);
230
231  /**
232   * Appends a double record to the log.
233   *
234   * @param impl data log implementation handle
235   * @param entry Entry index, as returned by Start()
236   * @param value Double value to record
237   * @param timestamp Time stamp (may be 0 to indicate now)
238   */
239  static native void appendDouble(long impl, int entry, double value, long timestamp);
240
241  /**
242   * Appends a string record to the log.
243   *
244   * @param impl data log implementation handle
245   * @param entry Entry index, as returned by Start()
246   * @param value String value to record
247   * @param timestamp Time stamp (may be 0 to indicate now)
248   */
249  static native void appendString(long impl, int entry, String value, long timestamp);
250
251  /**
252   * Appends a boolean array record to the log.
253   *
254   * @param impl data log implementation handle
255   * @param entry Entry index, as returned by Start()
256   * @param value Boolean array to record
257   * @param timestamp Time stamp (may be 0 to indicate now)
258   */
259  static native void appendBooleanArray(long impl, int entry, boolean[] value, long timestamp);
260
261  /**
262   * Appends an integer array record to the log.
263   *
264   * @param impl data log implementation handle
265   * @param entry Entry index, as returned by Start()
266   * @param value Integer array to record
267   * @param timestamp Time stamp (may be 0 to indicate now)
268   */
269  static native void appendIntegerArray(long impl, int entry, long[] value, long timestamp);
270
271  /**
272   * Appends a float array record to the log.
273   *
274   * @param impl data log implementation handle
275   * @param entry Entry index, as returned by Start()
276   * @param value Float array to record
277   * @param timestamp Time stamp (may be 0 to indicate now)
278   */
279  static native void appendFloatArray(long impl, int entry, float[] value, long timestamp);
280
281  /**
282   * Appends a double array record to the log.
283   *
284   * @param impl data log implementation handle
285   * @param entry Entry index, as returned by Start()
286   * @param value Double array to record
287   * @param timestamp Time stamp (may be 0 to indicate now)
288   */
289  static native void appendDoubleArray(long impl, int entry, double[] value, long timestamp);
290
291  /**
292   * Appends a string array record to the log.
293   *
294   * @param impl data log implementation handle
295   * @param entry Entry index, as returned by Start()
296   * @param value String array to record
297   * @param timestamp Time stamp (may be 0 to indicate now)
298   */
299  static native void appendStringArray(long impl, int entry, String[] value, long timestamp);
300
301  /** Utility class. */
302  private DataLogJNI() {}
303}