diff --git a/src/chat.rs b/src/chat.rs index 5952b4ea4..fb73ce7b2 100644 --- a/src/chat.rs +++ b/src/chat.rs @@ -46,7 +46,9 @@ use crate::{location, sql}; /// An chat item, such as a message or a marker. #[derive(Debug, Copy, Clone, PartialEq, Eq)] pub enum ChatItem { + /// Chat message stored in the database. Message { + /// Database ID of the messsage. msg_id: MsgId, }, @@ -1124,10 +1126,15 @@ impl rusqlite::types::FromSql for ChatId { /// if you want an update, you have to recreate the object. #[derive(Debug, Clone, Deserialize, Serialize)] pub struct Chat { + /// Database ID. pub id: ChatId, + + /// Chat type, e.g. 1:1 chat, group chat, mailing list. pub typ: Chattype, pub name: String, pub visibility: ChatVisibility, + + /// Group ID. pub grpid: String, pub(crate) blocked: Blocked, pub param: Params, @@ -1207,6 +1214,7 @@ impl Chat { self.param.exists(Param::Devicetalk) } + /// Returns true if chat is a mailing list. pub fn is_mailing_list(&self) -> bool { self.typ == Chattype::Mailinglist } @@ -1636,10 +1644,16 @@ impl Chat { } } +/// Whether the chat is pinned or archived. #[derive(Debug, Copy, Eq, PartialEq, Clone, Serialize, Deserialize)] pub enum ChatVisibility { + /// Chat is neither archived nor pinned. Normal, + + /// Chat is archived. Archived, + + /// Chat is pinned to the top of the chatlist. Pinned, } @@ -2334,6 +2348,7 @@ pub async fn send_text_msg( send_msg(context, chat_id, &mut msg).await } +/// Sends invitation to a videochat. pub async fn send_videochat_invitation(context: &Context, chat_id: ChatId) -> Result { ensure!( !chat_id.is_special(), @@ -2992,10 +3007,16 @@ pub(crate) async fn shall_attach_selfavatar(context: &Context, chat_id: ChatId) Ok(needs_attach) } +/// Chat mute duration. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub enum MuteDuration { + /// Chat is not muted. NotMuted, + + /// Chat is muted until the user unmutes the chat. Forever, + + /// Chat is muted for a limited period of time. Until(SystemTime), } @@ -3034,6 +3055,7 @@ impl rusqlite::types::FromSql for MuteDuration { } } +/// Mutes the chat for a given duration or unmutes it. pub async fn set_muted(context: &Context, chat_id: ChatId, duration: MuteDuration) -> Result<()> { ensure!(!chat_id.is_special(), "Invalid chat ID"); context @@ -3048,6 +3070,7 @@ pub async fn set_muted(context: &Context, chat_id: ChatId, duration: MuteDuratio Ok(()) } +/// Removes contact from the chat. pub async fn remove_contact_from_chat( context: &Context, chat_id: ChatId, @@ -3251,6 +3274,7 @@ pub async fn set_chat_profile_image( Ok(()) } +/// Forwards multiple messages to a chat. pub async fn forward_msgs(context: &Context, msg_ids: &[MsgId], chat_id: ChatId) -> Result<()> { ensure!(!msg_ids.is_empty(), "empty msgs_ids: nothing to forward"); ensure!(!chat_id.is_special(), "can not forward to special chat"); diff --git a/src/config.rs b/src/config.rs index 90ce185b2..3cdab6697 100644 --- a/src/config.rs +++ b/src/config.rs @@ -32,29 +32,75 @@ use crate::tools::{get_abs_path, improve_single_line_input, EmailAddress}; )] #[strum(serialize_all = "snake_case")] pub enum Config { + /// Email address, used in the `From:` field. Addr, + + /// IMAP server hostname. MailServer, + + /// IMAP server username. MailUser, + + /// IMAP server password. MailPw, + + /// IMAP server port. MailPort, + + /// IMAP server security (e.g. TLS, STARTTLS). MailSecurity, + + /// How to check IMAP server TLS certificates. ImapCertificateChecks, + + /// SMTP server hostname. SendServer, + + /// SMTP server username. SendUser, + + /// SMTP server password. SendPw, + + /// SMTP server port. SendPort, + + /// SMTP server security (e.g. TLS, STARTTLS). SendSecurity, + + /// How to check SMTP server TLS certificates. SmtpCertificateChecks, + + /// Whether to use OAuth 2. + /// + /// Historically contained other bitflags, which are now deprecated. + /// Should not be extended in the future, create new config keys instead. ServerFlags, + /// True if SOCKS5 is enabled. + /// + /// Can be used to disable SOCKS5 without erasing SOCKS5 configuration. Socks5Enabled, + + /// SOCKS5 proxy server hostname or address. Socks5Host, + + /// SOCKS5 proxy server port. Socks5Port, + + /// SOCKS5 proxy server username. Socks5User, + + /// SOCKS5 proxy server password. Socks5Password, + /// Own name to use in the `From:` field when sending messages. Displayname, + + /// Own status to display, sent in message footer. Selfstatus, + + /// Own avatar filename. Selfavatar, #[strum(props(default = "1"))] @@ -121,15 +167,33 @@ pub enum Config { SaveMimeHeaders, /// The primary email address. Also see `SecondaryAddrs`. ConfiguredAddr, + + /// Configured IMAP server hostname. ConfiguredMailServer, + + /// Configured IMAP server username. ConfiguredMailUser, + + /// Configured IMAP server password. ConfiguredMailPw, + + /// Configured IMAP server port. ConfiguredMailPort, + + /// Configured IMAP server security (e.g. TLS, STARTTLS). ConfiguredMailSecurity, ConfiguredImapCertificateChecks, + + /// Configured SMTP server hostname. ConfiguredSendServer, + + /// Configured SMTP server username. ConfiguredSendUser, + + /// Configured SMTP server password. ConfiguredSendPw, + + /// Configured SMTP server port. ConfiguredSendPort, ConfiguredSmtpCertificateChecks, ConfiguredServerFlags, @@ -200,6 +264,7 @@ pub enum Config { } impl Context { + /// Returns true if configuration value is set for the given key. pub async fn config_exists(&self, key: Config) -> Result { Ok(self.sql.get_raw_config(key.as_ref()).await?.is_some()) } diff --git a/src/context.rs b/src/context.rs index e58d742d6..f24ae79c4 100644 --- a/src/context.rs +++ b/src/context.rs @@ -193,6 +193,7 @@ impl Deref for Context { } } +/// Actual context, expensive to clone. #[derive(Debug)] pub struct InnerContext { /// Blob directory path @@ -570,6 +571,7 @@ impl Context { * UI chat/message related API ******************************************************************************/ + /// Returns information about the context as key-value pairs. pub async fn get_info(&self) -> Result> { let unset = "0"; let l = LoginParam::load_candidate_params_unchecked(self).await?; @@ -878,16 +880,19 @@ impl Context { Ok(list) } + /// Returns true if given folder name is the name of the inbox. pub async fn is_inbox(&self, folder_name: &str) -> Result { let inbox = self.get_config(Config::ConfiguredInboxFolder).await?; Ok(inbox.as_deref() == Some(folder_name)) } + /// Returns true if given folder name is the name of the "sent" folder. pub async fn is_sentbox(&self, folder_name: &str) -> Result { let sentbox = self.get_config(Config::ConfiguredSentboxFolder).await?; Ok(sentbox.as_deref() == Some(folder_name)) } + /// Returns true if given folder name is the name of the "Delta Chat" folder. pub async fn is_mvbox(&self, folder_name: &str) -> Result { let mvbox = self.get_config(Config::ConfiguredMvboxFolder).await?; Ok(mvbox.as_deref() == Some(folder_name)) @@ -908,6 +913,7 @@ impl Context { } } +/// Returns core version as a string. pub fn get_version_str() -> &'static str { &DC_VERSION_STR } diff --git a/src/events.rs b/src/events.rs index 378dab814..0e8dbed45 100644 --- a/src/events.rs +++ b/src/events.rs @@ -27,12 +27,14 @@ impl Default for Events { } impl Events { + /// Creates a new event channel. pub fn new() -> Self { let (sender, receiver) = channel::bounded(1_000); Self { receiver, sender } } + /// Emits an event. pub fn emit(&self, event: Event) { match self.sender.try_send(event) { Ok(()) => {} diff --git a/src/key.rs b/src/key.rs index 73967286c..c1d9b3c55 100644 --- a/src/key.rs +++ b/src/key.rs @@ -1,7 +1,5 @@ //! Cryptographic key module. -#![allow(missing_docs)] - use std::collections::BTreeMap; use std::fmt; use std::io::Cursor; @@ -332,6 +330,7 @@ pub async fn store_self_keypair( pub struct Fingerprint(Vec); impl Fingerprint { + /// Creates new 160-bit (20 bytes) fingerprint. pub fn new(v: Vec) -> Fingerprint { debug_assert_eq!(v.len(), 20); Fingerprint(v) diff --git a/src/pgp.rs b/src/pgp.rs index cacdecae0..b50ad8e5b 100644 --- a/src/pgp.rs +++ b/src/pgp.rs @@ -119,8 +119,13 @@ pub fn split_armored_data(buf: &[u8]) -> Result<(BlockType, BTreeMap>( } } +/// Reads directory and returns a vector of directory entries. pub async fn read_dir(path: &Path) -> Result> { let res = tokio_stream::wrappers::ReadDirStream::new(fs::read_dir(path).await?) .try_collect()