API Proposal - Connect to the Clarius probe without user interaction

mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java

@@ -192,6 +192,37 @@ public class MobileApi
 
     public static final int MSG_COPY_RAW_DATA = 17;
 
+    //! Query the service with all available ultrasound probes and their connection status.
+    //!
+    //! The reply will be delived with the MSG_RETURN_PROBES.
+    //!
+    //! Parameters(s):
+    //! - Message.replyTo: client's Messenger where the reply should be sent. This field is mandatory; if missing, the query will be ignored.
+    //! - Message.arg1 (optional): callback parameter for MSG_RETURN_PROBES.
+    //!
+    //! MSG_RETURN_STATUS Message.arg2 will be 0 if the request failed, i.e. the Clarius user is not logged in and the available probes cannot be retrieved.
+    //! \version Added in version x.x.x
+
+    public static final int MSG_LIST_PROBES = 18;
+
+    //! Select a scanner and try to connect to it. Follows the same behaviour as the "Select Scanner" UI element in the Clarius app. Tries to connect to the probes wifi automatically. Follows the connection setup as configured in the Clarius app, i.e. direct Wifi or pre-configured custom SSID.
+    //!
+    //! The MSG_RETURN_STATUS will be
+    //! - 0 if the scanner or scan application does not exist, if the license for the mobile API cannot be used or for any other reason the request for connection cannot be executed.
+    //! - 1 if the request was successful. This does not mean that the probe has been successfully connected. For this, listen to the MSG_PROBE_STATUS_CHANGED
+    //!
+    //! The event MSG_PROBE_STATUS_CHANGED will inform you whether the connection has succeeded.
+    //!
+    //! Parameter(s):
+    //! - Bundle[KEY_SELECT_PROBE]: String, the serial number of the probe to connect to
+    //! - Bundle[KEY_SELECT_APPLICATION]: String, the name of the application to use for the scanner, i.e. vascular. A list of available applications is defined here: TODO
+    //! - Message.replyTo (optional): if set, Messenger to send the MSG_RETURN_STATUS message to.
+    //! - Message.arg1 (optional): callback parameter for MSG_RETURN_STATUS.
+    //!
+    //! \version Added in version x.x.x
+
+    public static final int MSG_SELECT_PROBE = 19;
+
     // Messages from server to client.
 
     //! Return the outcome of a command sent by the client.
@@ -376,6 +407,28 @@ public class MobileApi
 
     public static final int MSG_RAW_DATA_COPIED = 123;
 
+    //! Reply to query MSG_LIST_PROBES
+    //!
+    //! Parameters:
+    //! - Bundle[KEY_PROBES]: me.clarius.mobileapi.Probes, a list of probes that are available to the current Clarius user
+    //! - Message.arg1: callback parameter copied from the Message.arg1 sent by the client.
+    //!
+    //! \version Added in version x.x.x
+
+    public static final int MSG_RETURN_PROBES = 124;
+
+    //! Server event for the current probe connection status
+    //!
+    //! Parameters:
+    //! - Message.arg1: int
+    //!    0 - a previously successfully connected probe disconnected or a connection attempt failed
+    //!    1 - probe connected successfully and is ready for imaging (bluetooth + wifi available)
+    //!
+    //! If a connection attempt failed (i.e status 0) the MSG_SELECT_PROBE needs to be initiated again. The MobileAPI does not retry a failed attempt for you.
+    //!
+    //! \version Added in version x.x.x
+    public static final int MSG_PROBE_STATUS_CHANGED = 125;
+
     // Bundle keys
 
     public static final String KEY_IMAGE_SIZE = "size";
@@ -405,6 +458,9 @@ public class MobileApi
     public static final String KEY_CAPTURE_ID = "captureID";
     public static final String KEY_FILE_NAME = "fileName";
     public static final String KEY_SIZE_BYTES = "sizeBytes";
+    public static final String KEY_SELECT_PROBE = "selectProbe";
+    public static final String KEY_SELECT_APPLICATION = "selectApplication";
+    public static final String KEY_PROBES = "listProbes";
 
     // Predefined bundle values
 

mobileapi/src/main/java/me/clarius/mobileapi/ProbeInfo.java

@@ -9,6 +9,7 @@ public class ProbeInfo implements Parcelable
 {
     public String model;        //!< model type
     public String serial;       //!< serial #
+    public String name;         //!< nick name of the scanner, added in version x.x.x
     public int battery;         //!< battery percentage
     public int temperature;     //!< temperature percentage (of max)
     public int version;         //!< version (1 = Clarius 1st Generation, 2 = Clarius HD)
@@ -22,7 +23,8 @@ public ProbeInfo()
     {
         model = "";
         serial = "";
-        battery = 0;
+        name = "";
+	battery = 0;
         temperature = 0;
         version = 0;
         elements = 0;
@@ -55,6 +57,8 @@ private ProbeInfo(Parcel in)
         battery = in.readInt();
         serial = in.readString();
         model = in.readString();
+	// Added in version x.x.x:
+	name = in.readString();
     }
 
     @Override
@@ -69,6 +73,8 @@ public void writeToParcel(Parcel out, int flags)
         out.writeInt(battery);
         out.writeString(serial);
         out.writeString(model);
+	// Added in version x.x.x:
+        out.writeString(name);
     }
 
     @Override

mobileapi/src/main/java/me/clarius/mobileapi/Probes.java

@@ -0,0 +1,105 @@
+package me.clarius.mobileapi;
+
+import android.os.Parcel;
+import android.os.Parcelable;
+
+//! A list of available ultrasound scanners for the current Clarius user
+
+// NOTE(sven): This could also be done by reusing the ProbeInfo Parcelable and
+// we would just add some fields.
+public class Probe implements Parcelable
+{
+    public String model;        //!< model type
+    public String serial;       //!< serial
+    public String name;         //!< nick name of the scanner
+    public int version;         //!< version (1 = Clarius 1st Generation, 2 = Clarius HD)
+    public int battery;         //!< battery percentage, 0 if scanner is not available
+    public boolean isVirtual;    //!< true, if the scanner is a virtual demo scanner
+    public boolean isAvailable; //!< true, if the scanner is ready to connect
+    public boolean isConnected; //!< true, if the scanner is connected and ready for imaging
+
+    // Parcelable interface
+
+    public static final Parcelable.Creator<Probe> CREATOR = new Parcelable.Creator<Probe>()
+    {
+        public Prob createFromParcel(Parcel in)
+        {
+            return new Probe(in);
+        }
+        public Probe[] newArray(int size)
+        {
+            return new Probe[size];
+        }
+    };
+
+    private Probe(Parcel in)
+    {
+        version = in.readInt();
+        temperature = in.readInt();
+        battery = in.readInt();
+        serial = in.readString();
+        model = in.readString();
+	name = in.readString();
+    }
+
+    @Override
+    public void writeToParcel(Parcel out, int flags)
+    {
+        out.writeInt(version);
+        out.writeInt(temperature);
+        out.writeInt(battery);
+        out.writeString(serial);
+        out.writeString(model);
+	out.writeString(name);
+    }
+
+    @Override
+    public int describeContents()
+    {
+        return 0;
+    }
+}
+
+public class Probes implements Parcelable
+{
+    public Probe[] probes;
+
+    //! Default constructor sets everything to zero.
+    //! Note: required for JNI for Android 8 API 26.
+    public Probes()
+    {
+        probes = null
+    }
+
+    // Parcelable interface
+
+    public static final Parcelable.Creator<Probes> CREATOR = new Parcelable.Creator<Probes>()
+    {
+        public Probes createFromParcel(Parcel in)
+        {
+            return new Probes(in);
+        }
+
+        public Probes[] newArray(int size)
+        {
+            return new Probes[size];
+        }
+    };
+
+    private Probes(Parcel in)
+    {
+        probes = in.createTypedArray(Probe.CREATOR);
+    }
+
+    @Override
+    public void writeToParcel(Parcel out, int flags)
+    {
+        out.writeTypedArray(probes, 0);
+    }
+
+    @Override
+    public int describeContents()
+    {
+        return 0;
+    }
+}