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.
This commit is contained in:
Marco Trevisan (Treviño) 2020-01-16 16:43:56 +01:00
parent 30c783cbeb
commit 0889ec20a8
3 changed files with 40 additions and 29 deletions

View file

@ -128,23 +128,36 @@ typedef void (*FpEnrollProgress) (FpDevice *device,
/** /**
* FpMatchCb: * FpMatchCb:
* @device: a #FpDevice * @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 * @print: (nullable) (transfer none): The newly scanned print
* @user_data: (nullable) (transfer none): User provided data * @user_data: (nullable) (transfer none): User provided data
* @error: (nullable) (transfer none): #GError or %NULL * @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, typedef void (*FpMatchCb) (FpDevice *device,
gboolean success,
FpPrint *match, FpPrint *match,
FpPrint *print, FpPrint *print,
gpointer user_data, gpointer user_data,

View file

@ -1281,7 +1281,7 @@ fpi_device_verify_report (FpDevice *device,
} }
if (call_cb && data->match_cb) 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) 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);
} }

View file

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