Delta Chat Core C Interface
Loading...
Searching...
No Matches
Public Member Functions | List of all members
dc_contact_t Class Reference

An object representing a single contact in memory. More...

#include <deltachat.h>

Public Member Functions

char * dc_contact_get_addr (const dc_contact_t *contact)
 Get the e-mail address of a contact.
 
char * dc_contact_get_auth_name (const dc_contact_t *contact)
 Get original contact name.
 
uint32_t dc_contact_get_color (const dc_contact_t *contact)
 Get a color for the contact.
 
char * dc_contact_get_display_name (const dc_contact_t *contact)
 Get display name.
 
uint32_t dc_contact_get_id (const dc_contact_t *contact)
 Get the ID of a contact.
 
int64_t dc_contact_get_last_seen (const dc_contact_t *contact)
 Get the contact's last seen timestamp.
 
char * dc_contact_get_name (const dc_contact_t *contact)
 Get the edited contact name.
 
char * dc_contact_get_name_n_addr (const dc_contact_t *contact)
 Get a summary of name and address.
 
char * dc_contact_get_profile_image (const dc_contact_t *contact)
 Get the contact's profile image.
 
char * dc_contact_get_status (const dc_contact_t *contact)
 Get the contact's status.
 
uint32_t dc_contact_get_verifier_id (dc_contact_t *contact)
 Return the contact ID that verified a contact.
 
int dc_contact_is_blocked (const dc_contact_t *contact)
 Check if a contact is blocked.
 
int dc_contact_is_bot (dc_contact_t *contact)
 Returns whether contact is a bot.
 
int dc_contact_is_verified (dc_contact_t *contact)
 Check if the contact can be added to verified chats, i.e.
 
void dc_contact_unref (dc_contact_t *contact)
 Free a contact object.
 
int dc_contact_was_seen_recently (const dc_contact_t *contact)
 Check if the contact was seen recently.
 

Detailed Description

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 (e.g. dc_contact_get_name(), dc_contact_get_display_name(), dc_contact_get_name_n_addr(), dc_create_contact() or dc_add_address_book()) only affect the given-name.

Member Function Documentation

◆ dc_contact_get_addr()

char * dc_contact_get_addr ( const dc_contact_t contact)

Get the e-mail address of a contact.

The e-mail address is always set for a contact.

Parameters
contactThe contact object.
Returns
A string with the e-mail address, must be released using dc_str_unref(). Never returns NULL.

◆ dc_contact_get_auth_name()

char * dc_contact_get_auth_name ( const dc_contact_t contact)

Get original contact name.

This is the name of the contact as defined by the contact themself. If the contact themself does not define such a name, an empty string is returned.

This function is typically only needed for the controls that allow the local user to edit the name, e.g. you want to show the original name somewhere in the edit dialog (you cannot use dc_contact_get_display_name() for that as this would return previously set edited names).

In most other situations than the name-edit-dialog, as lists, messages etc. use dc_contact_get_display_name().

Returns
A string with the original name, must be released using dc_str_unref(). Empty string if unset, never returns NULL.

◆ dc_contact_get_color()

uint32_t dc_contact_get_color ( const dc_contact_t contact)

Get a color for the contact.

The color is calculated from the contact's e-mail address and can be used for an fallback avatar with white initials as well as for headlines in bubbles of group chats.

Parameters
contactThe contact object.
Returns
A color as 0x00rrggbb with rr=red, gg=green, bb=blue each in the range 0-255.

◆ dc_contact_get_display_name()

char * dc_contact_get_display_name ( const dc_contact_t contact)

Get display name.

This is the name as defined by the contact himself, modified by the user or, if both are unset, the e-mail address.

This name is typically used in lists. To get the name editable in a formular, use dc_contact_get_name().

In a group, you should show the sender's name over a message. To get it, call dc_msg_get_override_sender_name() first and if it returns NULL, call dc_contact_get_display_name().

Parameters
contactThe contact object.
Returns
A string with the name to display, must be released using dc_str_unref(). Never returns NULL.

◆ dc_contact_get_id()

uint32_t dc_contact_get_id ( const dc_contact_t contact)

Get the ID of a contact.

Parameters
contactThe contact object.
Returns
The ID of the contact, 0 on errors.

◆ dc_contact_get_last_seen()

int64_t dc_contact_get_last_seen ( const dc_contact_t contact)

Get the contact's last seen timestamp.

Parameters
contactThe contact object.
Returns
The last seen timestamp. 0 on error or if the contact was never seen.

◆ dc_contact_get_name()

char * dc_contact_get_name ( const dc_contact_t contact)

Get the edited contact name.

This is the name as given or modified by the local user using dc_create_contact(). If there is no such name for the contact, an empty string is returned. The function does not return the contact name as received from the network.

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 dc_contact_get_display_name() or dc_contact_get_name_n_addr().

Parameters
contactThe contact object.
Returns
A string with the name to display, must be released using dc_str_unref(). Empty string if unset, never returns NULL.

◆ dc_contact_get_name_n_addr()

char * dc_contact_get_name_n_addr ( const dc_contact_t contact)

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 summary is typically used when asking the user something about the contact. The attached e-mail address makes the question unique, e.g. "Chat with Alan Miller (am@uniquedomain.com)?"

Parameters
contactThe contact object.
Returns
A summary string, must be released using dc_str_unref(). Never returns NULL.

◆ dc_contact_get_profile_image()

char * dc_contact_get_profile_image ( const dc_contact_t contact)

Get the contact's profile image.

This is the image set by each remote user on their own using dc_set_config(context, "selfavatar", image).

Parameters
contactThe contact object.
Returns
The path and the file of the profile image, if any. NULL otherwise. Must be released using dc_str_unref() after usage.

◆ dc_contact_get_status()

char * dc_contact_get_status ( const dc_contact_t contact)

Get the contact's status.

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

Parameters
contactThe contact object.
Returns
The contact status, if any. Empty string otherwise. Must be released by using dc_str_unref() after usage.

◆ dc_contact_get_verifier_id()

uint32_t dc_contact_get_verifier_id ( dc_contact_t contact)

Return the contact ID that verified a 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 dc_contact_get_name_n_addr.

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

Parameters
contactThe contact object.
Returns
The contact ID of the verifier. If it is DC_CONTACT_ID_SELF, we verified the contact ourself. If it is 0, we don't have verifier information or the contact is not verified.

◆ dc_contact_is_blocked()

int dc_contact_is_blocked ( const dc_contact_t contact)

Check if a contact is blocked.

To block or unblock a contact, use dc_block_contact().

Parameters
contactThe contact object.
Returns
1=contact is blocked, 0=contact is not blocked.

◆ dc_contact_is_bot()

int dc_contact_is_bot ( dc_contact_t contact)

Returns whether contact is a bot.

Parameters
contactThe contact object.
Returns
0 if the contact is not a bot, 1 otherwise.

◆ dc_contact_is_verified()

int dc_contact_is_verified ( dc_contact_t contact)

Check 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, in chat member list items and in profiles if no chat with the contact exist (otherwise, use dc_chat_is_protected()).

Parameters
contactThe contact object.
Returns
0: contact is not verified. 2: SELF and contact have verified their fingerprints in both directions; in the UI typically checkmarks are shown.

◆ dc_contact_unref()

void dc_contact_unref ( dc_contact_t contact)

Free a contact object.

Parameters
contactThe contact object as created e.g. by dc_get_contact(). If NULL is given, nothing is done.

◆ dc_contact_was_seen_recently()

int dc_contact_was_seen_recently ( const dc_contact_t contact)

Check if the contact was seen recently.

The UI may highlight these contacts, eg. draw a little green dot on the avatars of the users recently seen. DC_CONTACT_ID_SELF and other special contact IDs are defined as never seen recently (they should not get a dot). To get the time a contact was seen, use dc_contact_get_last_seen().

Parameters
contactThe contact object.
Returns
1=contact seen recently, 0=contact not seen recently.

The documentation for this class was generated from the following file: