fp-device: Remove confusing success parameter on FpMatchCb

This was added as alias to the error check, but given we're passing to the
callback both the error and the match itself, we can just avoid adding an
extra parameter that could be confusing (as may imply that the matching
happened).

Also clarify the documentation and ensure that the match value is properly
set in tests.

libfprint/fp-device.h

@@ -128,23 +128,36 @@ typedef void (*FpEnrollProgress) (FpDevice *device,
 /**
  * FpMatchCb:
  * @device: a #FpDevice
- * @success: Whether a print was retrieved, %FALSE means @error is set
+ * @match: (nullable) (transfer none): The matching print if any matched @print
- * @match: (nullable) (transfer none): The matching print
  * @print: (nullable) (transfer none): The newly scanned print
  * @user_data: (nullable) (transfer none): User provided data
  * @error: (nullable) (transfer none): #GError or %NULL
  *
- * Report the result of a match (identify or verify) operation. This callback
+ * Report the result of a match (identify or verify) operation.
- * because it makes sense for drivers to wait e.g. on finger removal before
- * finishing the operation. However, the success/failure can often be reported
- * at an earlier time, and there is no need to make the user wait.
  *
- * The passed error is guaranteed to be of type %FP_DEVICE_RETRY if set. Actual
+ * If @match is non-%NULL, then it is set to the matching #FpPrint as passed
- * error conditions will not be reported using this function. Such an error may
+ * to the match operation. In this case @error will always be %NULL.
- * still happen even if this callback has been called.
+ *
+ * If @error is not %NULL then its domain is guaranteed to be
+ * %FP_DEVICE_RETRY. All other error conditions will not be reported using
+ * this callback. If such an error occurs before a match/no-match decision
+ * can be made, then this callback will not be called. Should an error
+ * happen afterwards, then you will get a match report through this callback
+ * and an error when the operation finishes.
+ *
+ * If @match and @error are %NULL, then a finger was presented but it did not
+ * match any known print.
+ *
+ * @print represents the newly scanned print. The driver may or may not
+ * provide this information. Image based devices will provide it and it
+ * allows access to the raw data.
+ *
+ * This callback exists because it makes sense for drivers to wait e.g. on
+ * finger removal before completing the match operation. However, the
+ * success/failure can often be reported at an earlier time, and there is
+ * no need to make the user wait.
  */
 typedef void (*FpMatchCb) (FpDevice *device,
-                           gboolean  success,
                            FpPrint  *match,
                            FpPrint  *print,
                            gpointer  user_data,

libfprint/fpi-device.c

@@ -1281,7 +1281,7 @@ fpi_device_verify_report (FpDevice      *device,
     }
 
   if (call_cb && data->match_cb)
-    data->match_cb (device, data->error == NULL, data->match, data->print, data->match_data, data->error);
+    data->match_cb (device, data->match, data->print, data->match_data, data->error);
 }
 
 /**
@@ -1357,5 +1357,5 @@ fpi_device_identify_report (FpDevice *device,
     }
 
   if (call_cb && data->match_cb)
-    data->match_cb (device, data->error == NULL, data->match, data->print, data->match_data, data->error);
+    data->match_cb (device, data->match, data->print, data->match_data, data->error);
 }

tests/test-fpi-device.c

@@ -546,7 +546,6 @@ test_driver_enroll_progress (void)
 typedef struct
 {
   gboolean called;
-  gboolean success;
   FpPrint *match;
   FpPrint *print;
   GError  *error;
@@ -556,7 +555,6 @@ static void
 test_driver_match_data_clear (MatchCbData *data)
 {
   data->called = FALSE;
-  data->success = FALSE;
   g_clear_object (&data->match);
   g_clear_object (&data->print);
   g_clear_error (&data->error);
@@ -564,7 +562,6 @@ test_driver_match_data_clear (MatchCbData *data)
 
 static void
 test_driver_match_cb (FpDevice *device,
-                      gboolean  success,
                       FpPrint  *match,
                       FpPrint  *print,
                       gpointer  user_data,
@@ -574,24 +571,18 @@ test_driver_match_cb (FpDevice *device,
 
   g_assert (data->called == FALSE);
   data->called = TRUE;
-  data->success = TRUE;
   if (match)
     data->match = g_object_ref (match);
   if (print)
     data->print = g_object_ref (print);
   if (error)
+    {
       data->error = g_error_copy (error);
-
-  if (success)
-    {
-      g_assert_null (error);
-    }
-  else
-    {
-      g_assert_nonnull (error);
       g_assert_null (match);
-      g_assert_null (print);
     }
+
+  if (match)
+    g_assert_no_error (error);
 }
 
 static void
@@ -616,7 +607,7 @@ test_driver_verify (void)
   g_assert_no_error (error);
 
   g_assert_true (match_data.called);
-  g_assert_true (match_data.success);
+  g_assert_nonnull (match_data.match);
   g_assert_true (match_data.print == out_print);
   g_assert_true (match_data.match == enrolled_print);
 
@@ -647,7 +638,7 @@ test_driver_verify_fail (void)
   g_assert_no_error (error);
 
   g_assert_true (match_data.called);
-  g_assert_true (match_data.success);
+  g_assert_no_error (match_data.error);
   g_assert_true (match_data.print == out_print);
   g_assert_null (match_data.match);
 
@@ -676,6 +667,7 @@ test_driver_verify_retry (void)
                          &match, &out_print, &error);
 
   g_assert_true (match_data.called);
+  g_assert_null (match_data.match);
   g_assert_error (match_data.error, FP_DEVICE_RETRY, FP_DEVICE_RETRY_GENERAL);
 
   g_assert (fake_dev->last_called_function == dev_class->verify);
@@ -705,6 +697,8 @@ test_driver_verify_error (void)
                          &match, &out_print, &error);
 
   g_assert_false (match_data.called);
+  g_assert_null (match_data.match);
+  g_assert_no_error (match_data.error);
 
   g_assert (fake_dev->last_called_function == dev_class->verify);
   g_assert_error (error, FP_DEVICE_ERROR, FP_DEVICE_ERROR_GENERAL);
@@ -803,7 +797,7 @@ test_driver_identify (void)
                            &matched_print, &print, &error);
 
   g_assert_true (match_data.called);
-  g_assert_true (match_data.success);
+  g_assert_nonnull (match_data.match);
   g_assert_true (match_data.match == matched_print);
   g_assert_true (match_data.print == print);
 
@@ -841,7 +835,8 @@ test_driver_identify_fail (void)
                            &matched_print, &print, &error);
 
   g_assert_true (match_data.called);
-  g_assert_true (match_data.success);
+  g_assert_null (match_data.match);
+  g_assert_no_error (match_data.error);
   g_assert_true (match_data.match == matched_print);
   g_assert_true (match_data.print == print);
 
@@ -882,6 +877,7 @@ test_driver_identify_retry (void)
                            &matched_print, &print, &error);
 
   g_assert_true (match_data.called);
+  g_assert_null (match_data.match);
   g_assert_error (match_data.error, FP_DEVICE_RETRY, FP_DEVICE_RETRY_GENERAL);
 
   g_assert (fake_dev->last_called_function == dev_class->identify);
@@ -921,6 +917,8 @@ test_driver_identify_error (void)
                            &matched_print, &print, &error);
 
   g_assert_false (match_data.called);
+  g_assert_null (match_data.match);
+  g_assert_no_error (match_data.error);
 
   g_assert (fake_dev->last_called_function == dev_class->identify);
   g_assert_error (error, FP_DEVICE_ERROR, FP_DEVICE_ERROR_GENERAL);