Require mutable reference if method changes device state

Previously, all methods that access a Nitrokey device took a reference
to the device as input.  This method changes methods that change the
device state to require a mutable reference instead.  In most case,
this is straightforward as the method writes data to the device (for
example write_config or change_user_pin).  But there are two edge cases:
- Authenticating with a PIN changes the device state as it may decrease
  the PIN retry counter if the authentication fails.
- Generating an HOTP code changes the device state as it increases the
  HOTP counter.

5 files changed, 75 insertions, 74 deletions

diff --git a/src/auth.rs b/src/auth.rs
index 8cec49c..f9f50fa 100644
--- a/src/auth.rs
+++ b/src/auth.rs
@@ -226,7 +226,7 @@ impl<T: Device> ops::DerefMut for User<T> {
 }
 
 impl<T: Device> GenerateOtp for User<T> {
-    fn get_hotp_code(&self, slot: u8) -> Result<String, Error> {
+    fn get_hotp_code(&mut self, slot: u8) -> Result<String, Error> {
         result_from_string(unsafe {
             nitrokey_sys::NK_get_hotp_code_PIN(slot, self.temp_password_ptr())
         })
@@ -290,7 +290,7 @@ impl<T: Device> Admin<T> {
     /// let device = nitrokey::connect()?;
     /// let config = Config::new(None, None, None, false);
     /// match device.authenticate_admin("12345678") {
-    ///     Ok(admin) => {
+    ///     Ok(mut admin) => {
     ///         admin.write_config(config);
     ///         ()
     ///     },
@@ -301,7 +301,7 @@ impl<T: Device> Admin<T> {
     /// ```
     ///
     /// [`InvalidSlot`]: enum.LibraryError.html#variant.InvalidSlot
-    pub fn write_config(&self, config: Config) -> Result<(), Error> {
+    pub fn write_config(&mut self, config: Config) -> Result<(), Error> {
         let raw_config = RawConfig::try_from(config)?;
         get_command_result(unsafe {
             nitrokey_sys::NK_write_config(
@@ -317,7 +317,7 @@ impl<T: Device> Admin<T> {
 }
 
 impl<T: Device> ConfigureOtp for Admin<T> {
-    fn write_hotp_slot(&self, data: OtpSlotData, counter: u64) -> Result<(), Error> {
+    fn write_hotp_slot(&mut self, data: OtpSlotData, counter: u64) -> Result<(), Error> {
         let raw_data = RawOtpSlotData::new(data)?;
         get_command_result(unsafe {
             nitrokey_sys::NK_write_hotp_slot(
@@ -334,7 +334,7 @@ impl<T: Device> ConfigureOtp for Admin<T> {
         })
     }
 
-    fn write_totp_slot(&self, data: OtpSlotData, time_window: u16) -> Result<(), Error> {
+    fn write_totp_slot(&mut self, data: OtpSlotData, time_window: u16) -> Result<(), Error> {
         let raw_data = RawOtpSlotData::new(data)?;
         get_command_result(unsafe {
             nitrokey_sys::NK_write_totp_slot(
@@ -351,13 +351,13 @@ impl<T: Device> ConfigureOtp for Admin<T> {
         })
     }
 
-    fn erase_hotp_slot(&self, slot: u8) -> Result<(), Error> {
+    fn erase_hotp_slot(&mut self, slot: u8) -> Result<(), Error> {
         get_command_result(unsafe {
             nitrokey_sys::NK_erase_hotp_slot(slot, self.temp_password_ptr())
         })
     }
 
-    fn erase_totp_slot(&self, slot: u8) -> Result<(), Error> {
+    fn erase_totp_slot(&mut self, slot: u8) -> Result<(), Error> {
         get_command_result(unsafe {
             nitrokey_sys::NK_erase_totp_slot(slot, self.temp_password_ptr())
         })
diff --git a/src/device.rs b/src/device.rs
index 462e9dc..f6492cd 100644
--- a/src/device.rs
+++ b/src/device.rs
@@ -452,7 +452,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// match device.change_admin_pin("12345678", "12345679") {
     ///     Ok(()) => println!("Updated admin PIN."),
     ///     Err(err) => eprintln!("Failed to update admin PIN: {}", err),
@@ -463,7 +463,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     ///
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
-    fn change_admin_pin(&self, current: &str, new: &str) -> Result<(), Error> {
+    fn change_admin_pin(&mut self, current: &str, new: &str) -> Result<(), Error> {
         let current_string = get_cstring(current)?;
         let new_string = get_cstring(new)?;
         get_command_result(unsafe {
@@ -485,7 +485,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// match device.change_user_pin("123456", "123457") {
     ///     Ok(()) => println!("Updated admin PIN."),
     ///     Err(err) => eprintln!("Failed to update admin PIN: {}", err),
@@ -496,7 +496,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     ///
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
-    fn change_user_pin(&self, current: &str, new: &str) -> Result<(), Error> {
+    fn change_user_pin(&mut self, current: &str, new: &str) -> Result<(), Error> {
         let current_string = get_cstring(current)?;
         let new_string = get_cstring(new)?;
         get_command_result(unsafe {
@@ -518,7 +518,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// match device.unlock_user_pin("12345678", "123456") {
     ///     Ok(()) => println!("Unlocked user PIN."),
     ///     Err(err) => eprintln!("Failed to unlock user PIN: {}", err),
@@ -529,7 +529,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     ///
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
-    fn unlock_user_pin(&self, admin_pin: &str, user_pin: &str) -> Result<(), Error> {
+    fn unlock_user_pin(&mut self, admin_pin: &str, user_pin: &str) -> Result<(), Error> {
         let admin_pin_string = get_cstring(admin_pin)?;
         let user_pin_string = get_cstring(user_pin)?;
         get_command_result(unsafe {
@@ -552,7 +552,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// match device.lock() {
     ///     Ok(()) => println!("Locked the Nitrokey device."),
     ///     Err(err) => eprintln!("Could not lock the Nitrokey device: {}", err),
@@ -560,7 +560,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     /// #     Ok(())
     /// # }
     /// ```
-    fn lock(&self) -> Result<(), Error> {
+    fn lock(&mut self) -> Result<(), Error> {
         get_command_result(unsafe { nitrokey_sys::NK_lock_device() })
     }
 
@@ -583,7 +583,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// match device.factory_reset("12345678") {
     ///     Ok(()) => println!("Performed a factory reset."),
     ///     Err(err) => eprintln!("Could not perform a factory reset: {}", err),
@@ -593,7 +593,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     /// ```
     ///
     /// [`build_aes_key`]: #method.build_aes_key
-    fn factory_reset(&self, admin_pin: &str) -> Result<(), Error> {
+    fn factory_reset(&mut self, admin_pin: &str) -> Result<(), Error> {
         let admin_pin_string = get_cstring(admin_pin)?;
         get_command_result(unsafe { nitrokey_sys::NK_factory_reset(admin_pin_string.as_ptr()) })
     }
@@ -617,7 +617,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// match device.build_aes_key("12345678") {
     ///     Ok(()) => println!("New AES keys have been built."),
     ///     Err(err) => eprintln!("Could not build new AES keys: {}", err),
@@ -627,7 +627,7 @@ pub trait Device: Authenticate + GetPasswordSafe + GenerateOtp + fmt::Debug {
     /// ```
     ///
     /// [`factory_reset`]: #method.factory_reset
-    fn build_aes_key(&self, admin_pin: &str) -> Result<(), Error> {
+    fn build_aes_key(&mut self, admin_pin: &str) -> Result<(), Error> {
         let admin_pin_string = get_cstring(admin_pin)?;
         get_command_result(unsafe { nitrokey_sys::NK_build_aes_key(admin_pin_string.as_ptr()) })
     }
@@ -758,8 +758,8 @@ impl GenerateOtp for DeviceWrapper {
         self.device().get_totp_slot_name(slot)
     }
 
-    fn get_hotp_code(&self, slot: u8) -> Result<String, Error> {
-        self.device().get_hotp_code(slot)
+    fn get_hotp_code(&mut self, slot: u8) -> Result<String, Error> {
+        self.device_mut().get_hotp_code(slot)
     }
 
     fn get_totp_code(&self, slot: u8) -> Result<String, Error> {
@@ -882,7 +882,7 @@ impl Storage {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// match device.change_update_pin("12345678", "87654321") {
     ///     Ok(()) => println!("Updated update PIN."),
     ///     Err(err) => eprintln!("Failed to update update PIN: {}", err),
@@ -893,7 +893,7 @@ impl Storage {
     ///
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
-    pub fn change_update_pin(&self, current: &str, new: &str) -> Result<(), Error> {
+    pub fn change_update_pin(&mut self, current: &str, new: &str) -> Result<(), Error> {
         let current_string = get_cstring(current)?;
         let new_string = get_cstring(new)?;
         get_command_result(unsafe {
@@ -919,7 +919,7 @@ impl Storage {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// match device.enable_firmware_update("12345678") {
     ///     Ok(()) => println!("Nitrokey entered update mode."),
     ///     Err(err) => eprintln!("Could not enter update mode: {}", err),
@@ -930,7 +930,7 @@ impl Storage {
     ///
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
-    pub fn enable_firmware_update(&self, update_pin: &str) -> Result<(), Error> {
+    pub fn enable_firmware_update(&mut self, update_pin: &str) -> Result<(), Error> {
         let update_pin_string = get_cstring(update_pin)?;
         get_command_result(unsafe {
             nitrokey_sys::NK_enable_firmware_update(update_pin_string.as_ptr())
@@ -953,7 +953,7 @@ impl Storage {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// match device.enable_encrypted_volume("123456") {
     ///     Ok(()) => println!("Enabled the encrypted volume."),
     ///     Err(err) => eprintln!("Could not enable the encrypted volume: {}", err),
@@ -964,7 +964,7 @@ impl Storage {
     ///
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
-    pub fn enable_encrypted_volume(&self, user_pin: &str) -> Result<(), Error> {
+    pub fn enable_encrypted_volume(&mut self, user_pin: &str) -> Result<(), Error> {
         let user_pin = get_cstring(user_pin)?;
         get_command_result(unsafe { nitrokey_sys::NK_unlock_encrypted_volume(user_pin.as_ptr()) })
     }
@@ -982,7 +982,7 @@ impl Storage {
     /// fn use_volume() {}
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// match device.enable_encrypted_volume("123456") {
     ///     Ok(()) => {
     ///         println!("Enabled the encrypted volume.");
@@ -999,7 +999,7 @@ impl Storage {
     /// #     Ok(())
     /// # }
     /// ```
-    pub fn disable_encrypted_volume(&self) -> Result<(), Error> {
+    pub fn disable_encrypted_volume(&mut self) -> Result<(), Error> {
         get_command_result(unsafe { nitrokey_sys::NK_lock_encrypted_volume() })
     }
 
@@ -1028,7 +1028,7 @@ impl Storage {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// device.enable_encrypted_volume("123445")?;
     /// match device.enable_hidden_volume("hidden-pw") {
     ///     Ok(()) => println!("Enabled a hidden volume."),
@@ -1041,7 +1041,7 @@ impl Storage {
     /// [`enable_encrypted_volume`]: #method.enable_encrypted_volume
     /// [`AesDecryptionFailed`]: enum.CommandError.html#variant.AesDecryptionFailed
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
-    pub fn enable_hidden_volume(&self, volume_password: &str) -> Result<(), Error> {
+    pub fn enable_hidden_volume(&mut self, volume_password: &str) -> Result<(), Error> {
         let volume_password = get_cstring(volume_password)?;
         get_command_result(unsafe {
             nitrokey_sys::NK_unlock_hidden_volume(volume_password.as_ptr())
@@ -1061,7 +1061,7 @@ impl Storage {
     /// fn use_volume() {}
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// device.enable_encrypted_volume("123445")?;
     /// match device.enable_hidden_volume("hidden-pw") {
     ///     Ok(()) => {
@@ -1079,7 +1079,7 @@ impl Storage {
     /// #     Ok(())
     /// # }
     /// ```
-    pub fn disable_hidden_volume(&self) -> Result<(), Error> {
+    pub fn disable_hidden_volume(&mut self) -> Result<(), Error> {
         get_command_result(unsafe { nitrokey_sys::NK_lock_hidden_volume() })
     }
 
@@ -1108,7 +1108,7 @@ impl Storage {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// device.enable_encrypted_volume("123445")?;
     /// device.create_hidden_volume(0, 0, 100, "hidden-pw")?;
     /// #     Ok(())
@@ -1118,7 +1118,7 @@ impl Storage {
     /// [`AesDecryptionFailed`]: enum.CommandError.html#variant.AesDecryptionFailed
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     pub fn create_hidden_volume(
-        &self,
+        &mut self,
         slot: u8,
         start: u8,
         end: u8,
@@ -1148,7 +1148,7 @@ impl Storage {
     /// use nitrokey::VolumeMode;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// match device.set_unencrypted_volume_mode("12345678", VolumeMode::ReadWrite) {
     ///     Ok(()) => println!("Set the unencrypted volume to read-write mode."),
     ///     Err(err) => eprintln!("Could not set the unencrypted volume to read-write mode: {}", err),
@@ -1160,7 +1160,7 @@ impl Storage {
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
     pub fn set_unencrypted_volume_mode(
-        &self,
+        &mut self,
         admin_pin: &str,
         mode: VolumeMode,
     ) -> Result<(), Error> {
@@ -1193,7 +1193,7 @@ impl Storage {
     /// use nitrokey::VolumeMode;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// match device.set_encrypted_volume_mode("12345678", VolumeMode::ReadWrite) {
     ///     Ok(()) => println!("Set the encrypted volume to read-write mode."),
     ///     Err(err) => eprintln!("Could not set the encrypted volume to read-write mode: {}", err),
@@ -1205,7 +1205,7 @@ impl Storage {
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
     pub fn set_encrypted_volume_mode(
-        &self,
+        &mut self,
         admin_pin: &str,
         mode: VolumeMode,
     ) -> Result<(), Error> {
@@ -1322,7 +1322,7 @@ impl Storage {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::Storage::connect()?;
+    /// let mut device = nitrokey::Storage::connect()?;
     /// match device.clear_new_sd_card_warning("12345678") {
     ///     Ok(()) => println!("Cleared the new SD card warning."),
     ///     Err(err) => eprintln!("Could not set the clear the new SD card warning: {}", err),
@@ -1333,7 +1333,7 @@ impl Storage {
     ///
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
-    pub fn clear_new_sd_card_warning(&self, admin_pin: &str) -> Result<(), Error> {
+    pub fn clear_new_sd_card_warning(&mut self, admin_pin: &str) -> Result<(), Error> {
         let admin_pin = get_cstring(admin_pin)?;
         get_command_result(unsafe {
             nitrokey_sys::NK_clear_new_sd_card_warning(admin_pin.as_ptr())
@@ -1341,7 +1341,7 @@ impl Storage {
     }
 
     /// Blinks the red and green LED alternatively and infinitely until the device is reconnected.
-    pub fn wink(&self) -> Result<(), Error> {
+    pub fn wink(&mut self) -> Result<(), Error> {
         get_command_result(unsafe { nitrokey_sys::NK_wink() })
     }
 
@@ -1361,7 +1361,7 @@ impl Storage {
     ///
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
-    pub fn export_firmware(&self, admin_pin: &str) -> Result<(), Error> {
+    pub fn export_firmware(&mut self, admin_pin: &str) -> Result<(), Error> {
         let admin_pin_string = get_cstring(admin_pin)?;
         get_command_result(unsafe { nitrokey_sys::NK_export_firmware(admin_pin_string.as_ptr()) })
     }
diff --git a/src/lib.rs b/src/lib.rs
index f7da8e1..c35829c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -47,7 +47,7 @@
 //! let device = nitrokey::connect()?;
 //! let slot_data = OtpSlotData::new(1, "test", "01234567890123456689", OtpMode::SixDigits);
 //! match device.authenticate_admin("12345678") {
-//!     Ok(admin) => {
+//!     Ok(mut admin) => {
 //!         match admin.write_hotp_slot(slot_data, 0) {
 //!             Ok(()) => println!("Successfully wrote slot."),
 //!             Err(err) => eprintln!("Could not write slot: {}", err),
@@ -66,7 +66,7 @@
 //! # use nitrokey::Error;
 //!
 //! # fn try_main() -> Result<(), Error> {
-//! let device = nitrokey::connect()?;
+//! let mut device = nitrokey::connect()?;
 //! match device.get_hotp_code(1) {
 //!     Ok(code) => println!("Generated HOTP code: {}", code),
 //!     Err(err) => eprintln!("Could not generate HOTP code: {}", err),
diff --git a/src/otp.rs b/src/otp.rs
index abaff66..ee142c7 100644
--- a/src/otp.rs
+++ b/src/otp.rs
@@ -38,7 +38,7 @@ pub trait ConfigureOtp {
     /// let device = nitrokey::connect()?;
     /// let slot_data = OtpSlotData::new(1, "test", "01234567890123456689", OtpMode::SixDigits);
     /// match device.authenticate_admin("12345678") {
-    ///     Ok(admin) => {
+    ///     Ok(mut admin) => {
     ///         match admin.write_hotp_slot(slot_data, 0) {
     ///             Ok(()) => println!("Successfully wrote slot."),
     ///             Err(err) => eprintln!("Could not write slot: {}", err),
@@ -53,7 +53,7 @@ pub trait ConfigureOtp {
     /// [`InvalidSlot`]: enum.LibraryError.html#variant.InvalidSlot
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`NoName`]: enum.CommandError.html#variant.NoName
-    fn write_hotp_slot(&self, data: OtpSlotData, counter: u64) -> Result<(), Error>;
+    fn write_hotp_slot(&mut self, data: OtpSlotData, counter: u64) -> Result<(), Error>;
 
     /// Configure a TOTP slot with the given data and set the TOTP time window to the given value
     /// (default 30).
@@ -74,7 +74,7 @@ pub trait ConfigureOtp {
     /// let device = nitrokey::connect()?;
     /// let slot_data = OtpSlotData::new(1, "test", "01234567890123456689", OtpMode::EightDigits);
     /// match device.authenticate_admin("12345678") {
-    ///     Ok(admin) => {
+    ///     Ok(mut admin) => {
     ///         match admin.write_totp_slot(slot_data, 30) {
     ///             Ok(()) => println!("Successfully wrote slot."),
     ///             Err(err) => eprintln!("Could not write slot: {}", err),
@@ -89,7 +89,7 @@ pub trait ConfigureOtp {
     /// [`InvalidSlot`]: enum.LibraryError.html#variant.InvalidSlot
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`NoName`]: enum.CommandError.html#variant.NoName
-    fn write_totp_slot(&self, data: OtpSlotData, time_window: u16) -> Result<(), Error>;
+    fn write_totp_slot(&mut self, data: OtpSlotData, time_window: u16) -> Result<(), Error>;
 
     /// Erases an HOTP slot.
     ///
@@ -106,7 +106,7 @@ pub trait ConfigureOtp {
     /// # fn try_main() -> Result<(), Error> {
     /// let device = nitrokey::connect()?;
     /// match device.authenticate_admin("12345678") {
-    ///     Ok(admin) => {
+    ///     Ok(mut admin) => {
     ///         match admin.erase_hotp_slot(1) {
     ///             Ok(()) => println!("Successfully erased slot."),
     ///             Err(err) => eprintln!("Could not erase slot: {}", err),
@@ -119,7 +119,7 @@ pub trait ConfigureOtp {
     /// ```
     ///
     /// [`InvalidSlot`]: enum.LibraryError.html#variant.InvalidSlot
-    fn erase_hotp_slot(&self, slot: u8) -> Result<(), Error>;
+    fn erase_hotp_slot(&mut self, slot: u8) -> Result<(), Error>;
 
     /// Erases a TOTP slot.
     ///
@@ -136,7 +136,7 @@ pub trait ConfigureOtp {
     /// # fn try_main() -> Result<(), Error> {
     /// let device = nitrokey::connect()?;
     /// match device.authenticate_admin("12345678") {
-    ///     Ok(admin) => {
+    ///     Ok(mut admin) => {
     ///         match admin.erase_totp_slot(1) {
     ///             Ok(()) => println!("Successfully erased slot."),
     ///             Err(err) => eprintln!("Could not erase slot: {}", err),
@@ -149,7 +149,7 @@ pub trait ConfigureOtp {
     /// ```
     ///
     /// [`InvalidSlot`]: enum.LibraryError.html#variant.InvalidSlot
-    fn erase_totp_slot(&self, slot: u8) -> Result<(), Error>;
+    fn erase_totp_slot(&mut self, slot: u8) -> Result<(), Error>;
 }
 
 /// Provides methods to generate OTP codes and to query OTP slots on a Nitrokey
@@ -171,7 +171,7 @@ pub trait GenerateOtp {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// let time = time::SystemTime::now().duration_since(time::UNIX_EPOCH);
     /// match time {
     ///     Ok(time) => device.set_time(time.as_secs(), false)?,
@@ -187,7 +187,7 @@ pub trait GenerateOtp {
     ///
     /// [`get_totp_code`]: #method.get_totp_code
     /// [`Timestamp`]: enum.CommandError.html#variant.Timestamp
-    fn set_time(&self, time: u64, force: bool) -> Result<(), Error> {
+    fn set_time(&mut self, time: u64, force: bool) -> Result<(), Error> {
         let result = if force {
             unsafe { nitrokey_sys::NK_totp_set_time(time) }
         } else {
@@ -270,7 +270,7 @@ pub trait GenerateOtp {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// let code = device.get_hotp_code(1)?;
     /// println!("Generated HOTP code on slot 1: {}", code);
     /// #     Ok(())
@@ -281,7 +281,7 @@ pub trait GenerateOtp {
     /// [`InvalidSlot`]: enum.LibraryError.html#variant.InvalidSlot
     /// [`NotAuthorized`]: enum.CommandError.html#variant.NotAuthorized
     /// [`SlotNotProgrammed`]: enum.CommandError.html#variant.SlotNotProgrammed
-    fn get_hotp_code(&self, slot: u8) -> Result<String, Error> {
+    fn get_hotp_code(&mut self, slot: u8) -> Result<String, Error> {
         result_from_string(unsafe { nitrokey_sys::NK_get_hotp_code(slot) })
     }
 
@@ -305,7 +305,7 @@ pub trait GenerateOtp {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// let time = time::SystemTime::now().duration_since(time::UNIX_EPOCH);
     /// match time {
     ///     Ok(time) => {
diff --git a/src/pws.rs b/src/pws.rs
index 1e27935..371de6e 100644
--- a/src/pws.rs
+++ b/src/pws.rs
@@ -43,9 +43,10 @@ pub const SLOT_COUNT: u8 = 16;
 /// }
 ///
 /// # fn try_main() -> Result<(), Error> {
-/// let device = nitrokey::connect()?;
+/// let mut device = nitrokey::connect()?;
 /// let pws = device.get_password_safe("123456")?;
 /// use_password_safe(&pws);
+/// drop(pws);
 /// device.lock()?;
 /// #     Ok(())
 /// # }
@@ -97,14 +98,14 @@ pub trait GetPasswordSafe {
     /// fn use_password_safe(pws: &PasswordSafe) {}
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// match device.get_password_safe("123456") {
     ///     Ok(pws) => {
     ///         use_password_safe(&pws);
-    ///         device.lock()?;
     ///     },
     ///     Err(err) => eprintln!("Could not open the password safe: {}", err),
     /// };
+    /// device.lock()?;
     /// #     Ok(())
     /// # }
     /// ```
@@ -116,7 +117,7 @@ pub trait GetPasswordSafe {
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     /// [`Unknown`]: enum.CommandError.html#variant.Unknown
     /// [`WrongPassword`]: enum.CommandError.html#variant.WrongPassword
-    fn get_password_safe(&self, user_pin: &str) -> Result<PasswordSafe<'_>, Error>;
+    fn get_password_safe(&mut self, user_pin: &str) -> Result<PasswordSafe<'_>, Error>;
 }
 
 fn get_password_safe<'a>(
@@ -148,7 +149,7 @@ impl<'a> PasswordSafe<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// let pws = device.get_password_safe("123456")?;
     /// pws.get_slot_status()?.iter().enumerate().for_each(|(slot, programmed)| {
     ///     let status = match *programmed {
@@ -193,7 +194,7 @@ impl<'a> PasswordSafe<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// match device.get_password_safe("123456") {
     ///     Ok(pws) => {
     ///         let name = pws.get_slot_name(0)?;
@@ -230,7 +231,7 @@ impl<'a> PasswordSafe<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// let pws = device.get_password_safe("123456")?;
     /// let name = pws.get_slot_name(0)?;
     /// let login = pws.get_slot_login(0)?;
@@ -263,7 +264,7 @@ impl<'a> PasswordSafe<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// let pws = device.get_password_safe("123456")?;
     /// let name = pws.get_slot_name(0)?;
     /// let login = pws.get_slot_login(0)?;
@@ -294,7 +295,7 @@ impl<'a> PasswordSafe<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
+    /// let mut device = nitrokey::connect()?;
     /// let pws = device.get_password_safe("123456")?;
     /// let name = pws.get_slot_name(0)?;
     /// let login = pws.get_slot_login(0)?;
@@ -307,7 +308,7 @@ impl<'a> PasswordSafe<'a> {
     /// [`InvalidSlot`]: enum.LibraryError.html#variant.InvalidSlot
     /// [`InvalidString`]: enum.LibraryError.html#variant.InvalidString
     pub fn write_slot(
-        &self,
+        &mut self,
         slot: u8,
         name: &str,
         login: &str,
@@ -340,8 +341,8 @@ impl<'a> PasswordSafe<'a> {
     /// # use nitrokey::Error;
     ///
     /// # fn try_main() -> Result<(), Error> {
-    /// let device = nitrokey::connect()?;
-    /// let pws = device.get_password_safe("123456")?;
+    /// let mut device = nitrokey::connect()?;
+    /// let mut pws = device.get_password_safe("123456")?;
     /// match pws.erase_slot(0) {
     ///     Ok(()) => println!("Erased slot 0."),
     ///     Err(err) => eprintln!("Could not erase slot 0: {}", err),
@@ -351,7 +352,7 @@ impl<'a> PasswordSafe<'a> {
     /// ```
     ///
     /// [`InvalidSlot`]: enum.LibraryError.html#variant.InvalidSlot
-    pub fn erase_slot(&self, slot: u8) -> Result<(), Error> {
+    pub fn erase_slot(&mut self, slot: u8) -> Result<(), Error> {
         get_command_result(unsafe { nitrokey_sys::NK_erase_password_safe_slot(slot) })
     }
 }
@@ -364,19 +365,19 @@ impl<'a> Drop for PasswordSafe<'a> {
 }
 
 impl GetPasswordSafe for Pro {
-    fn get_password_safe(&self, user_pin: &str) -> Result<PasswordSafe<'_>, Error> {
+    fn get_password_safe(&mut self, user_pin: &str) -> Result<PasswordSafe<'_>, Error> {
         get_password_safe(self, user_pin)
     }
 }
 
 impl GetPasswordSafe for Storage {
-    fn get_password_safe(&self, user_pin: &str) -> Result<PasswordSafe<'_>, Error> {
+    fn get_password_safe(&mut self, user_pin: &str) -> Result<PasswordSafe<'_>, Error> {
         get_password_safe(self, user_pin)
     }
 }
 
 impl GetPasswordSafe for DeviceWrapper {
-    fn get_password_safe(&self, user_pin: &str) -> Result<PasswordSafe<'_>, Error> {
+    fn get_password_safe(&mut self, user_pin: &str) -> Result<PasswordSafe<'_>, Error> {
         get_password_safe(self, user_pin)
     }
 }