1.\" Copyright (c) 2020 Yubico AB. All rights reserved.
2.\" Use of this source code is governed by a BSD-style
3.\" license that can be found in the LICENSE file.
4.\"
5.Dd $Mdocdate: August 5 2020 $
6.Dt FIDO_DEV_GET_TOUCH_BEGIN 3
7.Os
8.Sh NAME
9.Nm fido_dev_get_touch_begin ,
10.Nm fido_dev_get_touch_status
11.Nd asynchronously wait for touch on a FIDO 2 authenticator
12.Sh SYNOPSIS
13.In fido.h
14.Ft int
15.Fn fido_dev_get_touch_begin "fido_dev_t *dev"
16.Ft int
17.Fn fido_dev_get_touch_status "fido_dev_t *dev" "int *touched" "int ms"
18.Sh DESCRIPTION
19The functions described in this page allow an application to
20asynchronously wait for touch on a FIDO authenticator.
21This is useful when multiple authenticators are present and
22the application needs to know which one to use.
23.Pp
24The
25.Fn fido_dev_get_touch_begin
26function initiates a touch request on
27.Fa dev .
28.Pp
29The
30.Fn fido_dev_get_touch_status
31function continues an ongoing touch request on
32.Fa dev ,
33blocking up to
34.Fa ms
35milliseconds.
36On success,
37.Fa touched
38will be updated to reflect the touch request status.
39If
40.Fa touched
41is 1, the device was touched, and the touch request is
42terminated.
43If
44.Fa touched
45is 0, the application may call
46.Fn fido_dev_get_touch_status
47to continue the touch request, or
48.Fn fido_dev_cancel
49to terminate it.
50.Sh RETURN VALUES
51The error codes returned by
52.Fn fido_dev_get_touch_begin
53and
54.Fn fido_dev_get_touch_status
55are defined in
56.In fido/err.h .
57On success,
58.Dv FIDO_OK
59is returned.
60.Sh EXAMPLES
61Please refer to
62.Em examples/select.c
63in
64.Em libfido2's
65source tree.
66.Sh SEE ALSO
67.Xr fido_dev_cancel 3
68.Sh CAVEATS
69The
70.Fn fido_dev_get_touch_status
71function will cause a command to be transmitted to U2F
72authenticators.
73These transmissions should not exceed a frequency of 5Hz.
74