initial design for extended reads

see #5

core/src/main/java/tel/schich/javacan/AbstractCanChannel.java

@@ -218,6 +218,19 @@ protected long readSocket(ByteBuffer buffer) throws IOException {
         }
     }
 
+    /**
+     * Reads a message from this socket using the provided {@link java.nio.ByteBuffer} for the CAN frame.
+     *
+     * @see <a href="https://man7.org/linux/man-pages/man3/recvmsg.3p.html">read man page</a>
+     * @param buffer the buffer used to store the CAN frame
+     * @return An {@link ExtendedResult} instance that carries a CAN frame and additional message headers
+     * @throws IOException if the native call fails
+     */
+    protected ExtendedResult receiveMessage(ByteBuffer buffer) throws IOException {
+        // TODO flip buffer here
+        throw new UnsupportedOperationException("Implement me!");
+    }
+
     /**
      * Writes data to this socket from the given {@link java.nio.ByteBuffer}.
      * The {@link java.nio.ByteBuffer} must be a direct buffer as it is passed into native code.

core/src/main/java/tel/schich/javacan/ExtendedResult.java

@@ -0,0 +1,29 @@
+package tel.schich.javacan;
+
+import java.time.Instant;
+
+public class ExtendedResult {
+    private final CanFrame frame;
+
+    private final Instant timestamp;
+
+    private final int dropCount;
+
+    public ExtendedResult(CanFrame frame, Instant timestamp, int dropCount) {
+        this.frame = frame;
+        this.timestamp = timestamp;
+        this.dropCount = dropCount;
+    }
+
+    public CanFrame getFrame() {
+        return frame;
+    }
+
+    public Instant getTimestamp() {
+        return timestamp;
+    }
+
+    public int getDropCount() {
+        return dropCount;
+    }
+}

core/src/main/java/tel/schich/javacan/RawCanChannel.java

@@ -68,13 +68,33 @@ public RawCanChannel(int sock) {
      * Reads a CAM frame from the channel using the supplied buffer.
      *
      * @see <a href="https://man7.org/linux/man-pages/man2/read.2.html">read man page</a>
-     * @param buffer the buffer to read into.The buffer's {@link ByteOrder} will be set to native and it will be
+     * @param buffer the buffer to read into. The buffer's {@link ByteOrder} will be set to native, and it will be
      *               flipped after the read has been completed.
      * @return the CAN frame
      * @throws IOException if the IO operations failed, the supplied buffer was insufficient or invalid data was read.
      */
     public abstract CanFrame read(ByteBuffer buffer) throws IOException;
 
+    /**
+     * Reads a CAM frame and additional message headers from the channel by internally allocating a new direct {@link ByteBuffer}.
+     *
+     * @see <a href="https://man7.org/linux/man-pages/man3/recvmsg.3p.html">read man page</a>
+     * @return An {@link ExtendedResult} instance that carries a CAN frame and additional message headers
+     * @throws IOException if the IO operations failed or invalid data was read.
+     */
+    public abstract ExtendedResult extendedRead() throws IOException;
+
+    /**
+     * Reads a CAM frame  and additional message headers from the channel using the supplied buffer.
+     *
+     * @see <a href="https://man7.org/linux/man-pages/man3/recvmsg.3p.html">read man page</a>
+     * @param buffer the buffer to read into. The buffer's {@link ByteOrder} will be set to native, and it will be
+     *               flipped after the read has been completed.
+     * @return An {@link ExtendedResult} instance that carries a CAN frame and additional message headers
+     * @throws IOException if the IO operations failed, the supplied buffer was insufficient or invalid data was read.
+     */
+    public abstract ExtendedResult extendedRead(ByteBuffer buffer) throws IOException;
+
     /**
      * Reads raw bytes from the channel.
      *
@@ -89,6 +109,20 @@ public RawCanChannel(int sock) {
      */
     public abstract long readUnsafe(ByteBuffer buffer) throws IOException;
 
+    /**
+     * Reads raw bytes from the channel.
+     *
+     * This method does not apply any checks on the data that has been read or on the supplied buffer. This method
+     * is primarily intended for downstream libraries that implement their own parsing on the data from the socket.
+     *
+     * @see <a href="https://man7.org/linux/man-pages/man2/read.2.html">read man page</a>
+     * @param buffer the buffer to read into.The buffer's {@link ByteOrder} will be set to native and it will be
+     *               flipped after the read has been completed.
+     * @return the number of bytes
+     * @throws IOException if the IO operations failed.
+     */
+    public abstract ExtendedResult extendedReadUnsafe(ByteBuffer buffer) throws IOException;
+
     /**
      * Writes the given CAN frame.
      *

core/src/main/java/tel/schich/javacan/RawCanChannelImpl.java

@@ -87,6 +87,23 @@ public long readUnsafe(ByteBuffer buffer) throws IOException {
         return bytesRead;
     }
 
+    @Override
+    public ExtendedResult extendedRead() throws IOException {
+        int length = getOption(CanSocketOptions.FD_FRAMES) ? FD_MTU : MTU;
+        ByteBuffer frameBuf = JavaCAN.allocateOrdered(length);
+        return extendedRead(frameBuf);
+    }
+
+    @Override
+    public ExtendedResult extendedRead(ByteBuffer buffer) throws IOException {
+        return extendedReadUnsafe(buffer);
+    }
+
+    @Override
+    public ExtendedResult extendedReadUnsafe(ByteBuffer buffer) throws IOException {
+        return receiveMessage(buffer);
+    }
+
     @Override
     public RawCanChannel write(CanFrame frame) throws IOException {
         long written = writeUnsafe(frame.getBuffer());