Add support for generic probes on Pad, better matching upstream API.

Author: neilcsmith-net

src/org/freedesktop/gstreamer/Pad.java

@@ -1,5 +1,5 @@
 /* 
- * Copyright (C) 2019 Neil C Smith
+ * Copyright (C) 2020 Neil C Smith
  * Copyright (C) 2018 Antonio Morales
  * Copyright (C) 2014 Tom Greenwood <[email protected]>
  * Copyright (C) 2009 Tamas Korodi <[email protected]>
@@ -28,6 +28,7 @@
 import com.sun.jna.Pointer;
 import java.util.HashSet;
 import java.util.Set;
+import org.freedesktop.gstreamer.glib.NativeFlags;
 import org.freedesktop.gstreamer.glib.Natives;
 
 import org.freedesktop.gstreamer.lowlevel.GstAPI.GstCallback;
@@ -80,7 +81,7 @@
 public class Pad extends GstObject {
 
     public static final String GTYPE_NAME = "GstPad";
-    
+
     private static final int EVENT_HAS_INFO_MASK = GstPadAPI.GST_PAD_PROBE_TYPE_EVENT_DOWNSTREAM | GstPadAPI.GST_PAD_PROBE_TYPE_EVENT_UPSTREAM;
     private final Handle handle;
 
@@ -95,7 +96,7 @@ private Pad(Handle handle, boolean needRef) {
         super(handle, needRef);
         this.handle = handle;
     }
-    
+
     /**
      * Creates a new pad with the given name in the given direction. If name is
      * null, a guaranteed unique name (across all pads) will be assigned.
@@ -190,7 +191,7 @@ public Pad getPeer() {
      * filter contains the caps accepted by downstream in the preferred order.
      * filter might be NULL but if it is not NULL the returned caps will be a
      * subset of filter .
-     * 
+     *
      * @param filter Caps to filter by, or null
      * @return the {@link Caps} of the peer pad, or null if there is no peer
      * pad.
@@ -386,6 +387,79 @@ public void disconnect(UNLINKED listener) {
         disconnect(UNLINKED.class, listener);
     }
 
+    /**
+     * Be notified of different states of pads. The provided callback is called
+     * for every state that matches mask.
+     * <p>
+     * Probes are called in groups: First {@link PadProbeType#BLOCK} probes are
+     * called, then others, then finally {@link PadProbeType#IDLE}. The only
+     * exception here are IDLE probes that are called immediately if the pad is
+     * already idle while calling addProbe(). In each of the groups, probes are
+     * called in the order in which they were added.
+     *
+     * @param mask set of mask flags for probe - common options are fields of
+     * {@link PadProbeType}
+     * @param callback callback that will be called with notifications of the
+     * pad state
+     */
+    public void addProbe(final Set<PadProbeType> mask, PROBE callback) {
+        addProbe(NativeFlags.toInt(mask), callback);
+    }
+    
+    /**
+     * Be notified of different states of pads. The provided callback is called
+     * for every state that matches mask.
+     * <p>
+     * Probes are called in groups: First {@link PadProbeType#BLOCK} probes are
+     * called, then others, then finally {@link PadProbeType#IDLE}. The only
+     * exception here are IDLE probes that are called immediately if the pad is
+     * already idle while calling addProbe(). In each of the groups, probes are
+     * called in the order in which they were added.
+     *
+     * @param mask mask flag for probe
+     * @param callback callback that will be called with notifications of the
+     * pad state
+     */
+    public void addProbe(PadProbeType mask, PROBE callback) {
+        addProbe(mask.intValue(), callback);
+    }
+    
+    synchronized void addProbe(int mask, PROBE callback) {
+        final GstPadAPI.PadProbeCallback probe = new GstPadAPI.PadProbeCallback() {
+            @Override
+            public PadProbeReturn callback(Pad pad, GstPadProbeInfo probeInfo, Pointer user_data) {
+                PadProbeInfo info = new PadProbeInfo(probeInfo);
+                PadProbeReturn ret = callback.probeCallback(pad, info);
+                info.invalidate();
+                return ret;
+            }
+        };
+
+        NativeLong id = handle.addProbe(mask, probe);
+        if (id.longValue() == 0) {
+            // the Probe was an IDLE-Probe and it was already handled synchronously in handle.addProbe,
+            // so no Callback needs to be registered
+            return;
+        }
+
+        GCallback cb = new GCallback(id, probe) {
+            @Override
+            protected void disconnect() {
+                handle.removeProbe(id);
+            }
+        };
+        addCallback(PROBE.class, callback, cb);
+    }
+    
+    /**
+     * Remove the provided probe callback from the Pad.
+     * 
+     * @param callback callback to remove
+     */
+    public synchronized void removeProbe(PROBE callback) {
+        removeCallback(PROBE.class, callback);
+    }
+
     public void addEventProbe(final EVENT_PROBE listener) {
         final int mask = GstPadAPI.GST_PAD_PROBE_TYPE_EVENT_BOTH | GstPadAPI.GST_PAD_PROBE_TYPE_EVENT_FLUSH;
         addEventProbe(listener, mask);
@@ -609,7 +683,6 @@ public PadTemplate getTemplate() {
     public boolean hasCurrentCaps() {
         return GSTPAD_API.gst_pad_has_current_caps(this);
     }
-    
 
     /**
      * Signal emitted when new this {@link Pad} is linked to another {@link Pad}
@@ -646,6 +719,28 @@ public static interface UNLINKED {
         public void unlinked(Pad pad, Pad peer);
     }
 
+    /**
+     * Callback used by
+     * {@link #addProbe(java.util.EnumSet, org.freedesktop.gstreamer.Pad.PROBE)}
+     */
+    public static interface PROBE {
+
+        /**
+         * Callback used by
+         * {@link #addProbe(java.util.EnumSet, org.freedesktop.gstreamer.Pad.PROBE)}.
+         * Gets called to notify about the current blocking type.
+         * <p>
+         * <b>The PadProbeInfo and any Buffer, Event or Query referenced from
+         * it, is only valid for the duration of the callback.</b>
+         *
+         * @param pad Pad that is blocked
+         * @param info PadProbeInfo with access to underlying data
+         * @return PadProbeReturn value
+         */
+        public PadProbeReturn probeCallback(Pad pad, PadProbeInfo info);
+
+    }
+
     /**
      * Signal emitted when an event passes through this <tt>Pad</tt>.
      *
@@ -667,11 +762,11 @@ public static interface DATA_PROBE {
 
         public PadProbeReturn dataReceived(Pad pad, Buffer buffer);
     }
-    
+
     private static class Handle extends GstObject.Handle {
-        
+
         private final Set<NativeLong> probes;
-        
+
         private Handle(GstPadPtr ptr, boolean ownsHandle) {
             super(ptr, ownsHandle);
             probes = new HashSet<>();
@@ -681,21 +776,21 @@ private Handle(GstPadPtr ptr, boolean ownsHandle) {
         protected GstPadPtr getPointer() {
             return (GstPadPtr) super.getPointer();
         }
-        
+
         private synchronized NativeLong addProbe(int mask, GstPadAPI.PadProbeCallback probe) {
             NativeLong id = GSTPAD_API.gst_pad_add_probe(getPointer(), mask, probe, null, null);
             if (id.longValue() != 0) {
                 probes.add(id);
             }
             return id;
         }
-        
+
         private synchronized void removeProbe(NativeLong id) {
             if (probes.remove(id)) {
                 GSTPAD_API.gst_pad_remove_probe(getPointer(), id);
             }
         }
-        
+
         private synchronized void clearProbes() {
             probes.forEach(id -> GSTPAD_API.gst_pad_remove_probe(getPointer(), id));
             probes.clear();
@@ -712,7 +807,6 @@ public void dispose() {
             clearProbes();
             super.dispose();
         }
-        
-        
+
     }
 }

src/org/freedesktop/gstreamer/PadProbeInfo.java

@@ -0,0 +1,79 @@
+/* 
+ * Copyright (C) 2020 Neil C Smith
+ *
+ * This file is part of gstreamer-java.
+ *
+ * This code is free software: you can redistribute it and/or modify it under 
+ * the terms of the GNU Lesser General Public License version 3 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT 
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License 
+ * version 3 for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.freedesktop.gstreamer;
+
+import java.util.Set;
+import org.freedesktop.gstreamer.event.Event;
+import org.freedesktop.gstreamer.glib.NativeFlags;
+import org.freedesktop.gstreamer.lowlevel.GstPadProbeInfo;
+import org.freedesktop.gstreamer.query.Query;
+
+import static org.freedesktop.gstreamer.lowlevel.GstPadAPI.GSTPAD_API;
+
+/**
+ * Probe info passed in to Pad.PROBE callback.
+ */
+public final class PadProbeInfo {
+    
+    private GstPadProbeInfo info;
+    
+    PadProbeInfo(GstPadProbeInfo info) {
+        this.info = info;
+    }
+    
+    /**
+     * Get the set of flags for the current probe type.
+     * 
+     * @return probe type
+     */
+    public Set<PadProbeType> getType() {
+        return NativeFlags.fromInt(PadProbeType.class, info.padProbeType);
+    }
+    
+    /**
+     * Get the Buffer from the probe, or null.
+     * 
+     * @return buffer or null
+     */
+    public Buffer getBuffer() {
+        return GSTPAD_API.gst_pad_probe_info_get_buffer(info);
+    }
+
+    /**
+     * Get the Event from the probe, or null.
+     * 
+     * @return event or null
+     */
+    public Event getEvent() {
+        return GSTPAD_API.gst_pad_probe_info_get_event(info);
+    }
+
+    /**
+     * Get the query from the probe, or null.
+     * 
+     * @return query or null
+     */
+    public Query getQuery() {
+        return GSTPAD_API.gst_pad_probe_info_get_query(info);
+    }
+    
+    void invalidate() {
+        info = null;
+    }
+
+}