Delta Chat Core C Interface
Public Member Functions | List of all members
dc_contact_t Class Reference

#include <deltachat.h>

Public Member Functions

char * dc_contact_get_addr (const dc_contact_t *contact)
 Get email address. More...
 
char * dc_contact_get_auth_name (const dc_contact_t *contact)
 Get original contact name. More...
 
uint32_t dc_contact_get_color (const dc_contact_t *contact)
 Get a color for the contact. More...
 
char * dc_contact_get_display_name (const dc_contact_t *contact)
 Get display name. More...
 
uint32_t dc_contact_get_id (const dc_contact_t *contact)
 Get the ID of the contact. More...
 
char * dc_contact_get_name (const dc_contact_t *contact)
 Get the edited contact name. More...
 
char * dc_contact_get_name_n_addr (const dc_contact_t *contact)
 Get a summary of name and address. More...
 
char * dc_contact_get_profile_image (const dc_contact_t *contact)
 Get the contact's profile image. More...
 
char * dc_contact_get_status (const dc_contact_t *contact)
 Get the contact's status. More...
 
int dc_contact_is_blocked (const dc_contact_t *contact)
 Check if a contact is blocked. More...
 
int dc_contact_is_verified (dc_contact_t *contact)
 Check if a contact was verified. More...
 
void dc_contact_unref (dc_contact_t *contact)
 Free a contact object. More...
 

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 email address.

The email address is always set for a contact.

Parameters
contactThe contact object.
Returns
String with the email 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, eg. 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
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 email 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
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 email 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
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 the contact.

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

◆ 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
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 email address makes the question unique, e.g. "Chat with Alan Miller (am@uniquedomain.com)?"

Parameters
contactThe contact object.
Returns
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
Path and file if 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
Contact status, if any. Empty string otherwise. Must be released by using dc_str_unref() after usage.

◆ 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_verified()

int dc_contact_is_verified ( dc_contact_t contact)

Check if a contact was verified.

E.g. by a secure-join QR code scan and if the key has not changed since this verification.

The UI may draw a checkbox or something like that beside verified contacts.

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.

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