Fix signature of VCustomSource#SeekCallback (fixes #171) (#172)

* Fix signature of VCustomSource#SeekCallback (fixes #171)

Previously the offset was mistyped as a `*void`/`MemorySegment`. It was now
changed to be a `gint64`/`long`. Additionally, the `int whence`
parameter was replaced with a new `SeekWhence` enum that provides more
type safety and discoverability for implementers.

To test, a sample was added to provide a `VCustomSource` based on a
`FileHandle` that implements seeking, testing it against a TIF image.

* Regenerate docs to reflect changed API

Author: jbaiter

core/src/main/java/app/photofox/vipsffm/VCustomSource.java

@@ -16,13 +16,55 @@ public final class VCustomSource extends VSource {
     @FunctionalInterface
     public interface ReadCallback {
 
+        /**
+         * Read data from the input and write it to the provided memory segment
+         *
+         * @param dataPointer Pointer to the memory segment where the data should be written
+         * @param length      The maximum number of bytes to read
+         * @return The number of bytes actually read, or -1 on error
+         */
         long read(MemorySegment dataPointer, long length);
     }
 
     @FunctionalInterface
     public interface SeekCallback {
 
-        long seek(int whence);
+        /**
+         * Seek to a specific position in the input
+         *
+         * @param offset Relative offset in bytes from the position specified by {@code whence}
+         * @param whence Where to seek from, one of {@link SeekWhence}
+         * @return the new position in the input, or -1 on error
+         */
+        long seek(long offset, SeekWhence whence);
+    }
+
+    public enum SeekWhence {
+        /** Seek from the beginning of the input */
+        SEEK_SET(0),
+        /** Seek from the current position in the input */
+        SEEK_CUR(1),
+        /** Seek from the end of the input */
+        SEEK_END(2);
+
+        private final int value;
+
+        public static SeekWhence fromValue(int value) {
+            return switch (value) {
+                case 0 -> SEEK_SET;
+                case 1 -> SEEK_CUR;
+                case 2 -> SEEK_END;
+                default -> throw new IllegalArgumentException("Unknown seek whence value: " + value);
+            };
+        }
+
+        SeekWhence(int value) {
+            this.value = value;
+        }
+
+        public int getValue() {
+            return value;
+        }
     }
 
     private final VCustomSource.ReadCallback readCallback;
@@ -39,7 +81,7 @@ public VCustomSource(
 
         attachReadSignal(arena, this);
         if (seekCallback != null) {
-            attachSeekSignal(arena, this, seekCallback);
+            attachSeekSignal(arena, this);
         }
     }
 
@@ -78,17 +120,17 @@ public long apply(
         }
     }
 
-    private void attachSeekSignal(Arena arena, VSource source, SeekCallback seekCallback) {
+    private void attachSeekSignal(Arena arena, VSource source) {
         var callback = new CustomStreamSeekCallback.Function() {
 
             @Override
             public long apply(
                 MemorySegment source,
-                MemorySegment data,
+                long offset,
                 int whence,
                 MemorySegment handle
             ) {
-                return seekCallback.seek(whence);
+                return seekCallback.seek(offset, SeekWhence.fromValue(whence));
             }
         };
         var callbackPointer = CustomStreamSeekCallback.allocate(callback, arena);

core/src/main/java/app/photofox/vipsffm/jextract/CustomStreamSeekCallback.java

@@ -14,7 +14,7 @@
 
 /**
  * {@snippet lang=c :
- * typedef gint64 (*CustomStreamSeekCallback)(VipsSourceCustom *, void *, int, void *)
+ * typedef gint64 (*CustomStreamSeekCallback)(VipsSourceCustom *, gint64, int, void *)
  * }
  */
 public class CustomStreamSeekCallback {
@@ -27,13 +27,13 @@ public class CustomStreamSeekCallback {
      * The function pointer signature, expressed as a functional interface
      */
     public interface Function {
-        long apply(MemorySegment source, MemorySegment data, int whence, MemorySegment handle);
+        long apply(MemorySegment source, long offset, int whence, MemorySegment handle);
     }
 
     private static final FunctionDescriptor $DESC = FunctionDescriptor.of(
-        VipsRaw.C_LONG_LONG,
-        VipsRaw.C_POINTER,
+        VipsRaw.C_LONG,
         VipsRaw.C_POINTER,
+        VipsRaw.C_LONG,
         VipsRaw.C_INT,
         VipsRaw.C_POINTER
     );
@@ -60,9 +60,9 @@ public static MemorySegment allocate(CustomStreamSeekCallback.Function fi, Arena
     /**
      * Invoke the upcall stub {@code funcPtr}, with given parameters
      */
-    public static long invoke(MemorySegment funcPtr,MemorySegment source, MemorySegment data, int whence, MemorySegment handle) {
+    public static long invoke(MemorySegment funcPtr,MemorySegment source, long offset, int whence, MemorySegment handle) {
         try {
-            return (long) DOWN$MH.invokeExact(funcPtr, source, data, whence, handle);
+            return (long) DOWN$MH.invokeExact(funcPtr, source, offset, whence, handle);
         } catch (Throwable ex$) {
             throw new AssertionError("should not reach here", ex$);
         }