Mercurial > crates > nonstick

comparison src/items.rs @ 62:d83623951070

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Further improve docs and put `conv` behind a feature gate.
author Paul Fisher <paul@pfish.zone>
date Wed, 21 May 2025 23:10:09 -0400
parents 05cc2c27334f
children
comparison
equal deleted inserted replaced
61:5eecd797fc69 62:d83623951070
19 User = 2, 19 User = 2,
20 /// The TTY name. 20 /// The TTY name.
21 Tty = 3, 21 Tty = 3,
22 /// The remote host (if applicable). 22 /// The remote host (if applicable).
23 RemoteHost = 4, 23 RemoteHost = 4,
24 /// The [crate::Conversation] structure. 24 /// The conversation struct (not a CStr-based item).
25 Conversation = 5, 25 Conversation = 5,
26 /// The authentication token (password). 26 /// The authentication token (password).
27 AuthTok = 6, 27 AuthTok = 6,
28 /// The old authentication token (when changing passwords). 28 /// The old authentication token (when changing passwords).
29 OldAuthTok = 7, 29 OldAuthTok = 7,
52 fn from(val: ItemType) -> Self { 52 fn from(val: ItemType) -> Self {
53 val as Self 53 val as Self
54 } 54 }
55 } 55 }
56 56
57 /// A type that can be requested by [crate::PamHandle::get_item]. 57 /// A type that can be requested by [`PamHandle::get_item`](crate::PamHandle::get_item).
58 pub trait Item { 58 pub trait Item {
59 /// The `repr(C)` type that is returned (by pointer) by the underlying `pam_get_item` function. 59 /// The `repr(C)` type that is returned (by pointer) by the underlying `pam_get_item` function.
60 /// This memory is owned by the PAM session.
60 type Raw; 61 type Raw;
61 62
62 /// The `ItemType` for this type 63 /// The [ItemType] corresponding to this Rust type.
63 fn type_id() -> ItemType; 64 fn type_id() -> ItemType;
64 65
65 /// The function to convert from the pointer to the C-representation to this safer wrapper type. 66 /// The function to convert from the pointer to the C-representation to this safer wrapper type.
66 /// 67 ///
67 /// # Safety 68 /// # Safety
68 /// 69 ///
69 /// This function assumes the pointer is a valid pointer to a `Self::Raw` instance. 70 /// This function assumes the pointer is a valid pointer to a [Self::Raw] instance.
70 unsafe fn from_raw(raw: *const Self::Raw) -> Self; 71 unsafe fn from_raw(raw: *const Self::Raw) -> Self;
71 72
72 /// The function to convert from this wrapper type to a C-compatible pointer. 73 /// The function to convert from this wrapper type to a C-compatible pointer.
73 fn into_raw(self) -> *const Self::Raw; 74 fn into_raw(self) -> *const Self::Raw;
74 } 75 }
75 76
77 /// Macro to generate PAM [Item]s represented as [CStr]s.
76 macro_rules! cstr_item { 78 macro_rules! cstr_item {
77 ($name:ident) => { 79 ($name:ident) => {
78 #[doc = concat!("The [ItemType::", stringify!($name), "]")] 80 #[doc = "The [CStr] representation of the "]
79 #[doc = " item, represented as a [CStr]."] 81 #[doc = concat!("[`", stringify!($name), "`](ItemType::", stringify!($name), ")")]
82 #[doc = " [Item]."]
80 #[derive(Debug)] 83 #[derive(Debug)]
81 pub struct $name<'s>(pub &'s CStr); 84 pub struct $name<'s>(pub &'s CStr);
82 85
83 impl<'s> std::ops::Deref for $name<'s> { 86 impl<'s> std::ops::Deref for $name<'s> {
84 type Target = &'s CStr; 87 type Target = &'s CStr;