Struct Contact

pub struct Contact {
    pub id: ContactId,
    name: String,
    authname: String,
    addr: String,
    pub blocked: bool,
    last_seen: i64,
    pub origin: Origin,
    pub param: Params,
    status: String,
    is_bot: bool,
}

An object representing a single contact in memory.

The contact object is not updated. If you want an update, you have to recreate the object.

The library makes sure only to use names authorized by the contact in To: or Cc:. Given-names as “Daddy” or “Honey” are not used there. For this purpose, internally, two names are tracked - authorized name and given name. By default, these names are equal, but functions working with contact names only affect the given name.

Fields

id: ContactId

The contact ID.

name: String

Contact name. It is recommended to use Contact::get_name, Contact::get_display_name or Contact::get_name_n_addr to access this field. May be empty, initially set to authname.

authname: String

Name authorized by the contact himself. Only this name may be spread to others, e.g. in To:-lists. May be empty. It is recommended to use Contact::get_authname, to access this field.

addr: String

E-Mail-Address of the contact. It is recommended to use Contact::get_addr to access this field.

blocked: bool

Blocked state. Use contact_is_blocked to access this field.

last_seen: i64

Time when the contact was seen last time, Unix time in seconds.

origin: Origin

The origin/source of the contact.

param: Params

Parameters as Param::ProfileImage

status: String

Last seen message signature for this contact, to be displayed in the profile.

is_bot: bool

If the contact is a bot.

Implementations

impl Contact

pub async fn get_by_id(context: &Context, contact_id: ContactId) -> Result<Self>

Loads a single contact object from the database.

Returns an error if the contact does not exist.

For contact ContactId::SELF (1), the function returns sth. like “Me” in the selected language and the email address defined by set_config().

For contact ContactId::DEVICE, the function overrides the contact name and status with localized address.

pub async fn get_by_id_optional( context: &Context, contact_id: ContactId, ) -> Result<Option<Self>>

Loads a single contact object from the database.

Similar to Contact::get_by_id() but returns None if the contact does not exist.

pub fn is_blocked(&self) -> bool

Returns true if this contact is blocked.

pub fn last_seen(&self) -> i64

Returns last seen timestamp.

pub fn was_seen_recently(&self) -> bool

Returns true if this contact was seen recently.

pub async fn is_blocked_load(context: &Context, id: ContactId) -> Result<bool>

Check if a contact is blocked.

pub async fn block(context: &Context, id: ContactId) -> Result<()>

Block the given contact.

pub async fn unblock(context: &Context, id: ContactId) -> Result<()>

Unblock the given contact.

pub async fn create( context: &Context, name: &str, addr: &str, ) -> Result<ContactId>

Add a single contact as a result of an explicit user action.

We assume, the contact name, if any, is entered by the user and is used “as is” therefore, normalize() is not called for the name. If the contact is blocked, it is unblocked.

To add a number of contacts, see add_address_book() which is much faster for adding a bunch of addresses.

May result in a #DC_EVENT_CONTACTS_CHANGED event.

pub(crate) async fn create_ex( context: &Context, sync: Sync, name: &str, addr: &str, ) -> Result<ContactId>

pub async fn mark_noticed(context: &Context, id: ContactId) -> Result<()>

Mark messages from a contact as noticed.

pub fn is_bot(&self) -> bool

Returns whether contact is a bot.

pub async fn lookup_id_by_addr( context: &Context, addr: &str, min_origin: Origin, ) -> Result<Option<ContactId>>

Check if an e-mail address belongs to a known and unblocked contact.

Known and unblocked contacts will be returned by get_contacts().

To validate an e-mail address independently of the contact database use may_be_valid_addr().

Returns the contact ID of the contact belonging to the e-mail address or 0 if there is no contact that is or was introduced by an accepted contact.

pub(crate) async fn lookup_id_by_addr_ex( context: &Context, addr: &str, min_origin: Origin, blocked: Option<Blocked>, ) -> Result<Option<ContactId>>

The same as lookup_id_by_addr(), but internal function. Currently also allows looking up not unblocked contacts.

pub(crate) async fn add_or_lookup( context: &Context, name: &str, addr: &ContactAddress, origin: Origin, ) -> Result<(ContactId, Modifier)>

Lookup a contact and create it if it does not exist yet. The contact is identified by the email-address, a name and an “origin” can be given.

The “origin” is where the address comes from - from-header, cc-header, addressbook, qr, manual-edit etc. In general, “better” origins overwrite the names of “worse” origins - Eg. if we got a name in cc-header and later in from-header, the name will change - this does not happen the other way round.

The “best” origin are manually created contacts - names given manually can only be overwritten by further manual edits (until they are set empty again or reset to the name seen in the From-header).

These manually edited names are never used for sending on the wire - this should avoid sending sth. as “Mama” or “Daddy” to some 3rd party. Instead, for the wire, we use so called “authnames” that can only be set and updated by a From-header.

The different names used in the function are:

• “name”: name passed as function argument, belonging to the given origin
• “row_name”: current name used in the database, typically set to “name”
• “row_authname”: name as authorized from a contact, set only through a From-header Depending on the origin, both, “row_name” and “row_authname” are updated from “name”.

Returns the contact_id and a Modifier value indicating if a modification occurred.

pub async fn add_address_book( context: &Context, addr_book: &str, ) -> Result<usize>

Add a number of contacts.

Typically used to add the whole address book from the OS. As names here are typically not well formatted, we call normalize() for each name given.

No email-address is added twice. Trying to add email-addresses that are already in the contact list, results in updating the name unless the name was changed manually by the user. If any email-address or any name is really updated, the event DC_EVENT_CONTACTS_CHANGED is sent.

To add a single contact entered by the user, you should prefer Contact::create, however, for adding a bunch of addresses, this function is much faster.

The addr_book is a multiline string in the format Name one\nAddress one\nName two\nAddress two.

Returns the number of modified contacts.

pub async fn get_all( context: &Context, listflags: u32, query: Option<&str>, ) -> Result<Vec<ContactId>>

Returns known and unblocked contacts.

To get information about a single contact, see get_contact().

listflags is a combination of flags:

• if the flag DC_GCL_ADD_SELF is set, SELF is added to the list unless filtered by other parameters
• if the flag DC_GCL_VERIFIED_ONLY is set, only verified contacts are returned. if DC_GCL_VERIFIED_ONLY is not set, verified and unverified contacts are returned. query is a string to filter the list.

async fn update_blocked_mailinglist_contacts(context: &Context) -> Result<()>

Adds blocked mailinglists as contacts to allow unblocking them as if they are contacts (this way, only one unblock-ffi is needed and only one set of ui-functions, from the users perspective, there is not much difference in an email- and a mailinglist-address)

pub async fn get_blocked_cnt(context: &Context) -> Result<usize>

Returns number of blocked contacts.

pub async fn get_all_blocked(context: &Context) -> Result<Vec<ContactId>>

Get blocked contacts.

pub async fn get_encrinfo( context: &Context, contact_id: ContactId, ) -> Result<String>

Returns a textual summary of the encryption state for the contact.

This function returns a string explaining the encryption state of the contact and if the connection is encrypted the fingerprints of the keys involved.

pub async fn delete(context: &Context, contact_id: ContactId) -> Result<()>

Delete a contact so that it disappears from the corresponding lists. Depending on whether there are ongoing chats, deletion is done by physical deletion or hiding. The contact is deleted from the local device.

May result in a #DC_EVENT_CONTACTS_CHANGED event.

pub async fn update_param(&self, context: &Context) -> Result<()>

Updates param column in the database.

pub async fn update_status(&self, context: &Context) -> Result<()>

Updates status column in the database.

pub fn get_id(&self) -> ContactId

Get the ID of the contact.

pub fn get_addr(&self) -> &str

Get email address. The email address is always set for a contact.

pub fn get_authname(&self) -> &str

Get name authorized by the contact.

pub fn get_name(&self) -> &str

Get the contact name. This is the name as modified by the local user. May be an empty string.

This name is typically used in a form where the user can edit the name of a contact. To get a fine name to display in lists etc., use Contact::get_display_name or Contact::get_name_n_addr.

pub fn get_display_name(&self) -> &str

Get display name. This is the name as defined by the contact himself, modified by the user or, if both are unset, the email address.

This name is typically used in lists. To get the name editable in a formular, use Contact::get_name.

pub fn get_authname_n_addr(&self) -> String

Get a summary of authorized name and address.

The returned string is either “Name (email@domain.com)” or just “email@domain.com” if the name is unset.

This string is suitable for sending over email as it does not leak the locally set name.

pub fn get_name_n_addr(&self) -> String

Get a summary of name and address.

The returned string is either “Name (email@domain.com)” or just “email@domain.com” if the name is unset.

The result should only be used locally and never sent over the network as it leaks the local contact name.

The summary is typically used when asking the user something about the contact. The attached email address makes the question unique, eg. “Chat with Alan Miller (am@uniquedomain.com)?”

pub async fn get_profile_image( &self, context: &Context, ) -> Result<Option<PathBuf>>

Get the contact’s profile image. This is the image set by each remote user on their own using set_config(context, “selfavatar”, image).

pub fn get_color(&self) -> u32

Get a color for the contact. The color is calculated from the contact’s email address and can be used for an fallback avatar with white initials as well as for headlines in bubbles of group chats.

pub fn get_status(&self) -> &str

Gets the contact’s status.

Status is the last signature received in a message from this contact.

pub async fn e2ee_avail(&self, context: &Context) -> Result<bool>

Returns whether end-to-end encryption to the contact is available.

pub async fn is_verified(&self, context: &Context) -> Result<bool>

Returns true if the contact can be added to verified chats, i.e. has a verified key and Autocrypt key matches the verified key.

If contact is verified UI should display green checkmark after the contact name in contact list items and in chat member list items.

In contact profile view, us this function only if there is no chat with the contact, otherwise use is_chat_protected(). Use Self::get_verifier_id to display the verifier contact in the info section of the contact profile.

pub async fn is_forward_verified(&self, context: &Context) -> Result<bool>

Returns true if we have a verified key for the contact and it is the same as Autocrypt key. This is enough to send messages to the contact in verified chat and verify received messages, but not enough to display green checkmark or add the contact to verified groups.

pub async fn get_verifier_id( &self, context: &Context, ) -> Result<Option<ContactId>>

Returns the ContactId that verified the contact.

If the function returns non-zero result, display green checkmark in the profile and “Introduced by …” line with the name and address of the contact formatted by Self::get_name_n_addr.

If this function returns a verifier, this does not necessarily mean you can add the contact to verified chats. Use Self::is_verified to check if a contact can be added to a verified chat instead.

pub async fn is_profile_verified(&self, context: &Context) -> Result<bool>

Returns if the contact profile title should display a green checkmark.

This generally should be consistent with the 1:1 chat with the contact so 1:1 chat with the contact and the contact profile either both display the green checkmark or both don’t display a green checkmark.

UI often knows beforehand if a chat exists and can also call chat.is_protected() (if there is a chat) or contact.is_verified() (if there is no chat) directly. This is often easier and also skips some database calls.

pub async fn get_real_cnt(context: &Context) -> Result<usize>

Returns the number of real (i.e. non-special) contacts in the database.

pub async fn real_exists_by_id( context: &Context, contact_id: ContactId, ) -> Result<bool>

Returns true if a contact with this ID exists.

Trait Implementations

impl Debug for Contact

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.