proto-reg 0.1.0

Manage custom URL protocols in the Windows registry
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

//! # proto-reg
//!
//! A library for managing **custom URL protocols** on Windows.
//!
//! Custom URL protocols (schemes such as `myapp://`) are registered in the
//! Windows registry under `HKEY_CLASSES_ROOT\<scheme>`:
//!
//! ```text
//! HKEY_CLASSES_ROOT\<scheme>
//!     (Default)          = friendly name / description
//!     "URL Protocol"     = ""   (marker that makes it a URL protocol)
//!     DefaultIcon
//!         (Default)      = icon path
//!     shell\open\command
//!         (Default)      = command line ("%1" is replaced by the URL)
//! ```
//!
//! # Features
//!
//! * Query protocol information by name — [`ProtocolManager::query`]
//! * Register new or update existing protocols — [`ProtocolManager::add`]
//! * Delete protocols — [`ProtocolManager::remove`]
//! * List all registered URL protocols — [`ProtocolManager::list`]
//! * Backup protocols to JSON and restore them — [`ProtocolManager::backup_to_file`]
//!   / [`ProtocolManager::restore_from_file`]
//!
//! # Requirements
//!
//! * Windows only.
//! * Write operations (`add`, `remove`, `restore`) target
//!   `HKLM\Software\Classes` and therefore require an **elevated
//!   (Administrator)** process; they fail fast with
//!   [`Error::ElevationRequired`] otherwise. Check beforehand with
//!   [`ProtocolManager::is_elevated`]. Read operations (`query`, `list`,
//!   backup) do not require elevation.
//!
//! # Example
//!
//! ```no_run
//! use proto_reg::{Protocol, ProtocolManager};
//!
//! # fn main() -> proto_reg::Result<()> {
//! // Register `myapp://`
//! let protocol = Protocol::new(
//!     "myapp",
//!     r#""C:\Program Files\MyApp\myapp.exe" "%1""#,
//! )?;
//! ProtocolManager::add(&protocol)?;
//!
//! // Look it up again
//! let found = ProtocolManager::query("myapp")?.expect("just added");
//! assert_eq!(found.command, protocol.command);
//! # Ok(())
//! # }
//! ```
//!
//! # Browser dialog policy
//!
//! Chrome and Edge hide the "Always open these links" checkbox in the
//! external-protocol confirmation dialog by default, forcing users to confirm
//! the prompt on every click. [`ProtocolManager::set_browser_policy`] shows
//! the checkbox again by writing the
//! `ExternalProtocolDialogShowAlwaysOpenCheckbox` group-policy value under
//! `HKLM\Software\Policies\...` for both browsers (requires elevation).

#![cfg(windows)]

pub mod backup;
pub mod error;
pub mod protocol;
mod registry;

pub use backup::RestoreReport;
pub use error::{Error, Result};
pub use protocol::{Protocol, ProtocolManager};