1.\" Copyright (c) 2018 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: May 25 2018 $ 6.Dt FIDO_DEV_INFO_MANIFEST 3 7.Os 8.Sh NAME 9.Nm fido_dev_info_manifest , 10.Nm fido_dev_info_new , 11.Nm fido_dev_info_free , 12.Nm fido_dev_info_ptr , 13.Nm fido_dev_info_path , 14.Nm fido_dev_info_product , 15.Nm fido_dev_info_vendor , 16.Nm fido_dev_info_manufacturer_string , 17.Nm fido_dev_info_product_string 18.Nd FIDO 2 device discovery functions 19.Sh SYNOPSIS 20.In fido.h 21.Ft int 22.Fn fido_dev_info_manifest "fido_dev_info_t *devlist" "size_t ilen" "size_t *olen" 23.Ft fido_dev_info_t * 24.Fn fido_dev_info_new "size_t n" 25.Ft void 26.Fn fido_dev_info_free "fido_dev_info_t **devlist_p" "size_t n" 27.Ft const fido_dev_info_t * 28.Fn fido_dev_info_ptr "const fido_dev_info_t *devlist" "size_t i" 29.Ft const char * 30.Fn fido_dev_info_path "const fido_dev_info_t *di" 31.Ft int16_t 32.Fn fido_dev_info_product "const fido_dev_info_t *di" 33.Ft int16_t 34.Fn fido_dev_info_vendor "const fido_dev_info_t *di" 35.Ft const char * 36.Fn fido_dev_info_manufacturer_string "const fido_dev_info_t *di" 37.Ft const char * 38.Fn fido_dev_info_product_string "const fido_dev_info_t *di" 39.Sh DESCRIPTION 40The 41.Fn fido_dev_info_manifest 42function fills 43.Fa devlist 44with up to 45.Fa ilen 46FIDO devices found by the underlying operating system. 47Currently only USB HID devices are supported. 48The number of discovered devices is returned in 49.Fa olen , 50where 51.Fa olen 52is an addressable pointer. 53.Pp 54The 55.Fn fido_dev_info_new 56function returns a pointer to a newly allocated, empty device list 57with 58.Fa n 59available slots. 60If memory is not available, NULL is returned. 61.Pp 62The 63.Fn fido_dev_info_free 64function releases the memory backing 65.Fa *devlist_p , 66where 67.Fa *devlist_p 68must have been previously allocated by 69.Fn fido_dev_info_new . 70The number 71.Fa n 72of allocated slots must also be provided. 73On return, 74.Fa *devlist_p 75is set to NULL. 76Either 77.Fa devlist_p 78or 79.Fa *devlist_p 80may be NULL, in which case 81.Fn fido_dev_info_free 82is a NOP. 83.Pp 84The 85.Fn fido_dev_info_ptr 86function returns a pointer to slot number 87.Fa i 88of 89.Fa devlist . 90It is the caller's responsibility to ensure that 91.Fa i 92is bounded. 93Please note that the first slot has index 0. 94.Pp 95The 96.Fn fido_dev_info_path 97returns the filesystem path or subsystem-specific identification 98string of 99.Fa di . 100.Pp 101The 102.Fn fido_dev_info_product 103function returns the product ID of 104.Fa di . 105.Pp 106The 107.Fn fido_dev_info_vendor 108function returns the vendor ID of 109.Fa di . 110.Pp 111The 112.Fn fido_dev_info_manufacturer_string 113function returns the manufacturer string of 114.Fa di . 115.Pp 116The 117.Fn fido_dev_info_product_string 118function returns the product string of 119.Fa di . 120.Pp 121An example of how to use the functions described in this document 122can be found in the 123.Pa examples/manifest.c 124file shipped with 125.Em libfido2 . 126.Sh RETURN VALUES 127The 128.Fn fido_dev_info_manifest 129function always returns 130.Dv FIDO_OK . 131If a discovery error occurs, the 132.Fa olen 133pointer is set to 0. 134.Pp 135The pointers returned by 136.Fn fido_dev_info_ptr , 137.Fn fido_dev_info_path , 138.Fn fido_dev_info_manufacturer_string , 139and 140.Fn fido_dev_info_product_string 141are guaranteed to exist until 142.Fn fido_dev_info_free 143is called on the corresponding device list. 144