Delta Chat Core C-API
 All Classes Functions Typedefs Groups Pages
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 email address. 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...
 
char * dc_contact_get_first_name (const dc_contact_t *contact)
 Get the part of the name before the first space. 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 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...
 
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 (eg. dc_contact_get_name(), dc_contact_get_display_name(), dc_contact_get_name_n_addr(), dc_contact_get_first_name(), dc_create_contact() or dc_add_address_book()) only affect the given-name.

Member Function Documentation

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 free()'d. Never returns NULL.
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
chatThe contact object.
Returns
Color as 0x00rrggbb with rr=red, gg=green, bb=blue each in the range 0-255.
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().

Parameters
contactThe contact object.
Returns
String with the name to display, must be free()'d. Never returns NULL.
char * dc_contact_get_first_name ( const dc_contact_t contact)

Get the part of the name before the first space.

In most languages, this seems to be the prename. If there is no space, the full display name is returned. If the display name is not set, the e-mail address is returned.

Parameters
contactThe contact object.
Returns
String with the name to display, must be free()'d. Never returns NULL.
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.
char * dc_contact_get_name ( const dc_contact_t contact)

Get the contact name.

This is the name as defined by the contact himself or modified by the 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 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 free()'d. Empty string if unset, never returns NULL.
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, eg. "Chat with Alan Miller (am@uniquedomain.com)?"

Parameters
contactThe contact object.
Returns
Summary string, must be free()'d. Never returns NULL.
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 free()'d after usage.
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.
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.
void dc_contact_unref ( dc_contact_t contact)

Free a contact object.

Parameters
contactThe contact object as created eg. by dc_get_contact(). If NULL is given, nothing is done.
Returns
None.

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