Add OpenOptions to windows-registry

[kennykerr]

Rather than adding more registry creation methods to satisfy #3269, #3346, or any future needs, this update introduces an OpenOptions type modeled after std::fs::OpenOptions. This new type provides the options and flags that you can set in order to configure how a registry key is opened. The Key type continues to provide the create and open methods as a convenience but internally they now also use OpenOptions for construction. Let's consider a few examples.

Today you can use create to create or open a registry key for read and write access:

let path = "software\\windows-rs\\sample";
let key = CURRENT_USER.create(path)?;

What if you only want to open the key if it already exists? Well you can use open instead but it offers only read access:

let key = CURRENT_USER.open(path)?;

This is where you can use the new options method to gain more control:

let key = CURRENT_USER.options().write(true).open(path)?;

key.set_u32("name", 123)?;

This opens the subkey with write access but only if it already exists. The call will fail if the key does not exist. Want to create the key in all cases? Just set the create option:

let key = CURRENT_USER.options().create(true).write(true).open(path)?;

You can also optionally create a Transaction object for transactional access to the registry:

let tx = Transaction::new()?;

let key = CURRENT_USER
    .options()
    .read(true)
    .write(true)
    .create(true)
    .transaction(&tx)
    .open(path)?;

key.set_u32("name", 123)?;

tx.commit()?;

Failure to commit the transaction will cause all changes to be rolled back when the transaction object is dropped. They are also not observable outside of the transaction until and unless commit is called.

Finally, I removed the Default implementation from the Key object. This just seemed confusing as you could try (and fail) to use the various registry functions on an invalid registry key handle. If for some reason you need to hold on to an invalid registry key you can still use the unsafe from_raw method.

Fixes: #3269
Fixes: #3346

[Nerixyz]

You can also optionally create a Transaction object for transactional access to the registry:

This example would be great in the README (so it shows up in the crate documentation on docs.rs).

[kennykerr]

Done - thanks for the suggestion!

[ChrisDenton]

This is a really nice API! The extensibility is a nice feature too as it'll make future feature requests much easier to accommodate.

[kennykerr]

@riverar - good feedback but I'd rather not add features opportunistically. If and when such needs present themselves, we can now more easily introduce them.