ref: a2b7e1e05e07302b156ef7515cde17fcd93c443c nitrokey-rs/src/device d---------
Add get_struct utility function

This patch adds the internal get_struct utility function that can be
used for querying a struct with a libnitrokey function that uses an
output parameter.  Instead of this:

    let mut out = R::default();
    get_command_result(op(&mut out))?;

We can now write this:

    get_struct(|out| op(out))
Use Default::default for nitrokey-sys structs

Since version 3.6.0, nitrokey-sys derives the Default trait for all
structs.  This allows us to simplify code snippets where we have to
construct an empty struct that is then filled by nitrokey-sys.
Use NK_config struct for configuration handling

Previously, the Nitrokey configuration was represented as an array in
libnitrokey.  libnitrokey 3.6 added the NK_config struct and the
NK_{read,write}_config_struct for type-safe configuration handling.
This patch replaces the old functions with the new versions using the
NK_config struct.  This makes the RawConfig struct obsolete as it is
identical to NK_config.
Use NK_device_serial_number_as_u32

Previously, we called the NK_device_serial_number function in
Device::get_serial which returned a string that we had to parse into an
unsigned integer to use with the SerialNumber struct.  libnitrokey 3.6
introduced the NK_device_serial_number_as_u32 function that returns the
serial number as an unsigned integer.  This patch replaces the call to
NK_device_serial_number with this new function.
Rename *lock fields of the Config struct

libnitrokey calls the configuration fields that set bindings for the Num
Lock, Caps Lock and Scroll Lock keys numlock, capslock, scrolllock.  Due
to a typo, scrolllock with three l was renamed to scrollock with two l
in nitrokey-rs.

To make the field names easier to read (and type) and consistent with
the typical names for these keys, this patch changes them to num_lock,
caps_lock and scroll_lock.  In the doc comments, we now use the spelling
“Num Lock”, “Caps Lock” and “Scroll Lock”.
Fix dead links in Device documentation
Make *Error, Model, DeviceWrapper non-exhaustive

Previously, all enums defined by the nitrokey crate were exhaustive.
This means that adding new variants to these enums is a breaking change.
To make it possible to add new features to nitrokey-rs without breaking
compatibility, this patch marks the Error, CommandError,
CommunicationError, LibraryError, Model and DeviceWrapper enums as
Use find(…) instead of skip_while(…).next()

This patch replaces calls to skip_while(…).next() for an iter::Iterator
with a call to find(…), as suggested by clippy.
Remove unused imports
Refactor string handling in util

The util module provides helper methods to deal with the C strings
returned by libnitrokey.  The current implementation has to problems:
- It causes unnecessary allocations if we only want to look at the
  string, for example in get_serial_number.
- If the conversion from a CStr to a String fails, the string pointer
  is not freed.

Therefore this patch introduces the run_with_str function that executes
a function with the string returned by libnitrokey and then makes sure
that the pointer is freed correctly.
Represent serial numbers using SerialNumber struct

In a previous commit, we changed the serial number representation from a
string to an integer.  This made it easier to compare serial numbers,
but also introduced new problems:
- Serial numbers should be formatted consistently, for example as
  "{:#010x}".  It is hard to ensure this for an integer value.
- The format of the serial number may be subject to change.  Users
  should not rely too much on the u32 representation.

Therefore we introduce a new SerialNumber struct that represents a
serial number.  Currently it only stores a u32 value.  The following
traits and functions can be used to access its value:
- FromStr for string parsing
- ToString/Display for string formatting
- as_u32 to access the underlying integer value
Merge branch 'get_config' into next

This patch series changes the Device::get_config implementation to use
libnitrokey’s NK_get_status instead of NK_read_config.  This does
results in the same command being sent to the Nitrokey device, but
avoids a new[]/free mismatch and makes the parsing more robust.
Use NK_get_status to implement Device::get_config

libnitrokey’s NK_read_config function returns a pointer to an array that
has been allocated using new[].  We would have to delete this pointer
using delete[], but we only have access to free.  Therefore this patch
modifies the Device::get_config function to call NK_get_status instead
of NK_read_config.

This also makes the code more safe as we get the data as a struct
instead of an array.  It does not add much overhead as NK_read_config
also executes the GET_STATUS command on the Nitrokey device.
Implement From<&NK_status> for RawConfig

This makes it easier to parse only the config part of the NK_status
struct and avoids code duplication in the upcoming get_config
Always store serial numbers as integers

This patch consistently uses u32 integers to store and return the serial
number of a Nitrokey device.  This makes it easier to convert and
compare the serial number, as it is a unique representation and as
formatting an integer cannot fail.  For more details, see this RFC:
Add String value to the Error::UnexpectedError variant

To make debugging of unexpected errors easier, this patch adds an
associated String value with a description of the unexpected behavior to
the UnexpectedError variant of the Error enum.
Merge branch 'release-0.5.1'
Fix serial number for older Nitrokey Pro in list_devices

Previously, we assumed that the serial number returned by hidapi
contains the Nitrokey serial number as the least significant bytes.  As
disussed here [0], this is not true for Nitrokey Pro devices with
firmware version 0.8 or older:  They write the serial number to the most
significant bytes instead.

This patch update the get_hidapi_serial_number function so that
list_devices now returns the correctly formatted and truncated serial
number for all Nitrokey Pro devices.  It also makes sure that the serial
number is lowercase to be consistent with libnitrokey’s formatting.
Merge branch 'release-0.5.0'
Add the fill_sd_card function to Storage

This patch adds support for libnitrokey’s
NK_fill_SD_card_with_random_data function.  It is executed by the
fill_sd_card function of the Storage struct.  We also add a new test
case that is set to ignore because it takes between 30 and 60 minutes to