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}