crates/nonstick: src/items.rs annotate

annotate src/items.rs @ 60:05cc2c27334f

The Big Refactor: clean up docs and exports. - Brings the most important symbols in the library to the root with `pub use` statements. - Expands and updates documentation. - Rearranges things extensively to make the external interface nicer and make the structure easier to understand. - Renames a few things (e.g. `Result`).

author	Paul Fisher <paul@pfish.zone>
date	Wed, 21 May 2025 19:00:51 -0400
parents	3f4a77aa88be
children	d83623951070

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,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	24 /// The [crate::Conversation] structure.
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
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	57 /// A type that can be requested by [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.
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	60 type Raw;
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	61
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	62 /// The `ItemType` for this type
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	63 fn type_id() -> ItemType;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	64
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 45 diff changeset	65 /// 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	66 ///
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	67 /// # Safety
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	68 ///
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 45 diff changeset	69 /// 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	70 unsafe fn from_raw(raw: *const Self::Raw) -> Self;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	71
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	72 /// 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	73 fn into_raw(self) -> *const Self::Raw;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	74 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	75
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	76 macro_rules! cstr_item {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	77 ($name:ident) => {
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	78 #[doc = concat!("The [ItemType::", stringify!($name), "]")]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	79 #[doc = " item, represented as a [CStr]."]
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	80 #[derive(Debug)]
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 45 diff changeset	81 pub struct $name<'s>(pub &'s CStr);
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	82
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	83 impl<'s> std::ops::Deref for $name<'s> {
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 45 diff changeset	84 type Target = &'s CStr;
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	85 fn deref(&self) -> &Self::Target {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	86 &self.0
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	87 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	88 }
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	89
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	90 impl<'s> Item for $name<'s> {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	91 type Raw = libc::c_char;
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	92
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	93 fn type_id() -> ItemType {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	94 ItemType::$name
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
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	97 unsafe fn from_raw(raw: *const Self::Raw) -> Self {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	98 Self(std::ffi::CStr::from_ptr(raw))
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
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	101 fn into_raw(self) -> *const Self::Raw {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	102 self.0.as_ptr()
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 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	105 };
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	106 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	107
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	108 // 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	109
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	110 cstr_item!(Service);
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	111 cstr_item!(User);
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	112 cstr_item!(Tty);
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	113 cstr_item!(RemoteHost);
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	114 cstr_item!(AuthTok);
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	115 cstr_item!(OldAuthTok);
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	116 cstr_item!(RemoteUser);
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 15 diff changeset	117 cstr_item!(UserPrompt);

Mercurial > crates > nonstick

annotate src/items.rs @ 60:05cc2c27334f