Update and document org.freedesktop.gstreamer.device package.

Author: neilcsmith-net

src/org/freedesktop/gstreamer/device/Device.java

@@ -1,6 +1,6 @@
 /*
  * 
- * Copyright (c) 2017 Neil C Smith
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2015 Andres Colubri <[email protected]>
  * Copyright (C) 2013 Olivier Crete <[email protected]>
  *
@@ -30,51 +30,114 @@
 import static org.freedesktop.gstreamer.lowlevel.GstDeviceAPI.GSTDEVICE_API;
 
 /**
- *
- * @author andres
+ * Devices are objects representing a device, they contain relevant metadata
+ * about the device, such as its class and the GstCaps representing the media
+ * types it can produce or handle.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/gstreamer-GstDevice.html"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/gstreamer-GstDevice.html</a>
+ * <p>
+ * Device objects are created by {@link DeviceProvider} objects, which can be
+ * aggregated by {@link DeviceMonitor} objects.
  */
 public class Device extends GstObject {
 
     public static final String GTYPE_NAME = "GstDevice";
 
-    public Device(Initializer init) {
+    Device(Initializer init) {
         super(init);
     }
 
+    /**
+     * Creates the element with all of the required parameters set to use this
+     * device.
+     *
+     * @param name name of new element, or NULL to automatically create a unique
+     * name
+     * @return a new {@link Element} configured to use this device.
+     */
     public Element createElement(String name) {
         return GSTDEVICE_API.gst_device_create_element(this, name);
     }
 
+    /**
+     * Get the {@link Caps} that this device supports.
+     *
+     * @return The Caps supported by this device.
+     */
     public Caps getCaps() {
         return GSTDEVICE_API.gst_device_get_caps(this);
     }
 
+    /**
+     * Gets the "class" of a device. This is a "/" separated list of classes
+     * that represent this device. They are a subset of the classes of the
+     * {@link DeviceProvider} that produced this device.
+     *
+     * @return class the device class
+     */
     public String getDeviceClass() {
         Pointer ptr = GSTDEVICE_API.gst_device_get_device_class(this);
         String ret = ptr.getString(0);
         GLIB_API.g_free(ptr);
         return ret;
     }
 
+    /**
+     * Gets the user-friendly name of the device.
+     *
+     * @return name of the device
+     */
     public String getDisplayName() {
         Pointer ptr = GSTDEVICE_API.gst_device_get_display_name(this);
         String ret = ptr.getString(0);
         GLIB_API.g_free(ptr);
         return ret;
     }
 
+    /**
+     * Check if device matches all of the given classes.
+     *
+     * @param classes a "/"-separated list of device classes to match, only
+     * match if all classes are matched
+     * @return true if device matches
+     */
     public boolean hasClasses(String classes) {
         return GSTDEVICE_API.gst_device_has_classes(this, classes);
     }
 
+    /**
+     * Check if device matches all of the given classes.
+     *
+     * @param classes an array of classes to match, only match if all classes
+     * are matched.
+     * @return true if device matches
+     */
     public boolean hasClasses(String[] classes) {
         return GSTDEVICE_API.gst_device_has_classesv(this, classes);
     }
 
+    /**
+     * Tries to reconfigure an existing element to use the device. If this
+     * function fails, then one must destroy the element and create a new one
+     * using {@link #createElement(java.lang.String) }
+     * <p>
+     * Note: This should only be implemented for elements can change their
+     * device in the PLAYING state.
+     * 
+     * @param element the element to be configured
+     * @return true if the element could be reconfigured to use this device
+     */
     public boolean reconfigureElement(Element element) {
         return GSTDEVICE_API.gst_device_reconfigure_element(this, element);
     }
 
+    /**
+     * Gets the extra properties of a device.
+     * 
+     * @return The extra properties or NULL when there are none.
+     */
     public Structure getProperties() {
         return GSTDEVICE_API.gst_device_get_properties(this);
     }

src/org/freedesktop/gstreamer/device/DeviceMonitor.java

@@ -1,6 +1,6 @@
 /*
  * 
- * Copyright (c) 2017 Neil C Smith
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2015 Andres Colubri <[email protected]>
  * Copyright (C) 2013 Olivier Crete <[email protected]>
  *
@@ -30,44 +30,102 @@
 import static org.freedesktop.gstreamer.lowlevel.GstDeviceMonitorAPI.GSTDEVICEMONITOR_API;
 
 /**
- *
- * @author andres
+ * A device monitor and prober
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/gstreamer-GstDeviceMonitor.html"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/gstreamer-GstDeviceMonitor.html</a>
+ * <p>
+ * Applications should create a DeviceMonitor when they want to probe, list and
+ * monitor devices of a specific type. The DeviceMonitor will create the
+ * appropriate {@link DeviceProvider} objects and manage them. It will then post
+ * messages on its {@link Bus} for devices that have been added and removed.
+ * <p>
+ * The device monitor will monitor all devices matching the filters that the
+ * application has set.
  */
 public class DeviceMonitor extends GstObject {
 
     public static final String GTYPE_NAME = "GstDeviceMonitor";
 
-    public DeviceMonitor(Initializer init) {
-        super(init);
+    public DeviceMonitor() {
+        super(initializer(GSTDEVICEMONITOR_API.ptr_gst_device_monitor_new(), false, true));
     }
 
-    static public DeviceMonitor createNew() {
-        return GSTDEVICEMONITOR_API.gst_device_monitor_new();
+    DeviceMonitor(Initializer init) {
+        super(init);
     }
 
+    /**
+     * Get the {@link Bus} for this DeviceMonitor
+     *
+     * @return bus
+     */
     public Bus getBus() {
         return GSTDEVICEMONITOR_API.gst_device_monitor_get_bus(this);
     }
 
+    /**
+     * Adds a filter for which devices will be monitored, any device that
+     * matches all these classes and the {@link Caps} will be returned.
+     * <p>
+     * If this function is called multiple times to add more filters, each will
+     * be matched independently. That is, adding more filters will not further
+     * restrict what devices are matched.
+     * <p>
+     * The GstCaps supported by the device as returned by gst_device_get_caps()
+     * are not intersected with caps filters added using this function.
+     * <p>
+     * Filters must be added before the GstDeviceMonitor is started.
+     *
+     * @param classes device classes to use as filter or NULL for any class.
+     * @param caps the GstCaps to filter or NULL for ANY.
+     * @return id the id of the new filter or 0 if no provider matched the
+     * filter's classes.
+     */
     public int addFilter(String classes, Caps caps) {
         return GSTDEVICEMONITOR_API.gst_device_monitor_add_filter(this, classes, caps);
     }
 
+    /**
+     * Remove a filter from the DeviceMonitor using the id that was returned
+     * from {@link #addFilter(java.lang.String, org.freedesktop.gstreamer.Caps)
+     * }
+     *
+     * @param filterId of filter to remove
+     * @return true if the filter id was valid and the filter was removed
+     */
     public boolean removeFilter(int filterId) {
         return GSTDEVICEMONITOR_API.gst_device_monitor_remove_filter(this, filterId);
     }
 
+    /**
+     * Starts monitoring the devices, once this has succeeded, the
+     * GST_MESSAGE_DEVICE_ADDED and GST_MESSAGE_DEVICE_REMOVED messages will be
+     * emitted on the bus when the list of devices changes.
+     *
+     * @return true if the device monitoring could be started
+     */
     public boolean start() {
         return GSTDEVICEMONITOR_API.gst_device_monitor_start(this);
     }
 
+    /**
+     * Stop monitoring devices.
+     */
     public void stop() {
         GSTDEVICEMONITOR_API.gst_device_monitor_stop(this);
     }
 
+    /**
+     * Gets a list of devices from all of the relevant monitors. This may
+     * actually probe the hardware if the monitor is not currently started.
+     * 
+     * @return list of {@link Device}
+     */
     public List<Device> getDevices() {
         GList glist = GSTDEVICEMONITOR_API.gst_device_monitor_get_devices(this);
-        List<Device> list = new ArrayList<Device>();
+        List<Device> list = new ArrayList<>();
 
         GList next = glist;
         while (next != null) {