crates/nonstick: src/items.rs annotate

annotate src/items.rs @ 64:bbe84835d6db v0.0.5

More organization; add lots of docs. - moves `PamHandle` to its own module, since it will be used by both modules and clients. - adds a ton of documentation to the `PamModule` trait and reorders methods to most-interesting-first. - adds more flag values from pam_modules.h. - other misc cleanup.

author	Paul Fisher <paul@pfish.zone>
date	Thu, 22 May 2025 01:52:32 -0400
parents	d83623951070
children	a674799a5cd3

rev	line source
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	1 //! Things that can be gotten with the `pam_get_item` function.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	2
59 3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	3 use crate::constants::InvalidEnum;
3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	4 use num_derive::FromPrimitive;
3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	5 use num_traits::FromPrimitive;
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	6 use std::ffi::{c_int, CStr};
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 45 diff changeset	7
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	8 /// Enum identifying what a `pam_get_item` return is.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	9 ///
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	10 /// Generally, you shouldn’t have to worry about this, and instead
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	11 /// just use the various [Item] implementations.
59 3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	12 #[derive(FromPrimitive)]
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	13 #[repr(i32)]
59 3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	14 #[non_exhaustive] // because C could give us anything!
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	15 pub enum ItemType {
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	16 /// The PAM service name.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	17 Service = 1,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	18 /// The user's login name.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	19 User = 2,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	20 /// The TTY name.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	21 Tty = 3,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	22 /// The remote host (if applicable).
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	23 RemoteHost = 4,
62 d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	24 /// The conversation struct (not a CStr-based item).
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	25 Conversation = 5,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	26 /// The authentication token (password).
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	27 AuthTok = 6,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	28 /// The old authentication token (when changing passwords).
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	29 OldAuthTok = 7,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	30 /// The remote user's name.
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	31 RemoteUser = 8,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	32 /// The prompt shown when requesting a username.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	33 UserPrompt = 9,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	34 /// App-supplied function to override failure delays.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	35 FailDelay = 10,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	36 /// X display name.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	37 XDisplay = 11,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	38 /// X server authentication data.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	39 XAuthData = 12,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	40 /// The type of `pam_get_authtok`.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	41 AuthTokType = 13,
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	42 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	43
59 3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	44 impl TryFrom<c_int> for ItemType {
3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	45 type Error = InvalidEnum<Self>;
3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	46 fn try_from(value: c_int) -> Result<Self, Self::Error> {
3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	47 Self::from_i32(value).ok_or(value.into())
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	48 }
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	49 }
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	50
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	51 impl From<ItemType> for c_int {
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	52 fn from(val: ItemType) -> Self {
59 3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	53 val as Self
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	54 }
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	55 }
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	56
62 d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	57 /// A type that can be requested by [`PamHandle::get_item`](crate::PamHandle::get_item).
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	58 pub trait Item {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	59 /// The `repr(C)` type that is returned (by pointer) by the underlying `pam_get_item` function.
62 d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	60 /// This memory is owned by the PAM session.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	61 type Raw;
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	62
62 d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	63 /// The [ItemType] corresponding to this Rust type.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	64 fn type_id() -> ItemType;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	65
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 45 diff changeset	66 /// The function to convert from the pointer to the C-representation to this safer wrapper type.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	67 ///
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	68 /// # Safety
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	69 ///
62 d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	70 /// This function assumes the pointer is a valid pointer to a [Self::Raw] instance.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	71 unsafe fn from_raw(raw: *const Self::Raw) -> Self;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	72
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	73 /// The function to convert from this wrapper type to a C-compatible pointer.
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	74 fn into_raw(self) -> *const Self::Raw;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	75 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	76
62 d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	77 /// Macro to generate PAM [Item]s represented as [CStr]s.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	78 macro_rules! cstr_item {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	79 ($name:ident) => {
62 d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	80 #[doc = "The [CStr] representation of the "]
d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	81 #[doc = concat!("[`", stringify!($name), "`](ItemType::", stringify!($name), ")")]
d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	82 #[doc = " [Item]."]
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	83 #[derive(Debug)]
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 45 diff changeset	84 pub struct $name<'s>(pub &'s CStr);
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	85
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	86 impl<'s> std::ops::Deref for $name<'s> {
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 45 diff changeset	87 type Target = &'s CStr;
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	88 fn deref(&self) -> &Self::Target {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	89 &self.0
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	90 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	91 }
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	92
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	93 impl<'s> Item for $name<'s> {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	94 type Raw = libc::c_char;
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	95
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	96 fn type_id() -> ItemType {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	97 ItemType::$name
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	98 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	99
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	100 unsafe fn from_raw(raw: *const Self::Raw) -> Self {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	101 Self(std::ffi::CStr::from_ptr(raw))
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	102 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	103
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	104 fn into_raw(self) -> *const Self::Raw {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	105 self.0.as_ptr()
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	106 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	107 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	108 };
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	109 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	110
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	111 // Conversation is not included here since it's special.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	112
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	113 cstr_item!(Service);
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	114 cstr_item!(User);
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	115 cstr_item!(Tty);
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	116 cstr_item!(RemoteHost);
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	117 cstr_item!(AuthTok);
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	118 cstr_item!(OldAuthTok);
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	119 cstr_item!(RemoteUser);
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	120 cstr_item!(UserPrompt);

Mercurial > crates > nonstick

annotate src/items.rs @ 64:bbe84835d6db v0.0.5