Delta Chat Core C Interface
Getting started

This document describes how to handle the Delta Chat core library. For general information about Delta Chat itself, see https://delta.chat and https://github.com/deltachat.

Let's start.

First of all, you have to define an event-handler-function that is called by the library on specific events (eg. when the configuration is done or when fresh messages arrive). With this function you can create a Delta Chat context then:

#include <deltachat.h>
uintptr_t event_handler_func(dc_context_t* context, int event,
uintptr_t data1, uintptr_t data2)
{
return 0; // for unhandled events, it is always safe to return 0
}
dc_context_t* context = dc_context_new(event_handler_func, NULL, NULL);

After that, you should make sure, sending and receiving jobs are processed as needed. For this purpose, you have to create two threads:

#include <pthread.h>
void* imap_thread_func(void* context)
{
while (true) {
}
}
void* smtp_thread_func(void* context)
{
while (true) {
}
}
static pthread_t imap_thread, smtp_thread;
pthread_create(&imap_thread, NULL, imap_thread_func, context);
pthread_create(&smtp_thread, NULL, smtp_thread_func, context);

The example above uses "pthreads", however, you can also use anything else for thread handling. All deltachat-core-functions, unless stated otherwise, are thread-safe.

After that you can define and open a database. The database is a normal sqlite-file and is created as needed:

dc_open(context, "example.db", NULL);

Now you can configure the context:

// use some real test credentials here
dc_set_config(context, "addr", "alice@example.org");
dc_set_config(context, "mail_pw", "***");
dc_configure(context);

dc_configure() returns immediately, the configuration itself may take a while and is done by a job in the imap-thread you've defined above. Once done, the DC_EVENT_CONFIGURE_PROGRESS reports success to the event_handler_func() that is also defined above.

The configuration result is saved in the database, on subsequent starts it is not needed to call dc_configure() (you can check this using dc_is_configured()).

Now you can send the first message:

// use a real testing address here
uint32_t contact_id = dc_create_contact(context, NULL, "bob@example.org");
uint32_t chat_id = dc_create_chat_by_contact_id(context, contact_id);
dc_send_text_msg(context, chat_id, "Hi, here is my first message!");

dc_send_text_msg() returns immediately; the sending itself is done by a job in the smtp-thread you've defined above. If you check the testing address (bob) and you should have received a normal email. Answer this email in any email program with "Got it!" and the imap-thread you've create above will receive the message.

You can then list all messages of a chat as follow:

dc_array_t* msglist = dc_get_chat_msgs(context, chat_id, 0, 0);
for (int i = 0; i < dc_array_get_cnt(msglist); i++)
{
uint32_t msg_id = dc_array_get_id(msglist, i);
dc_msg_t* msg = dc_get_msg(context, msg_id);
char* text = dc_msg_get_text(msg);
printf("Message %i: %s\n", i+1, text);
dc_str_unref(text);
}
dc_array_unref(msglist);

This will output the following two lines:

Message 1: Hi, here is my first message!
Message 2: Got it!

Class reference

For a class reference, see the "Classes" link atop.

Further hints

Here are some additional, unsorted hints that may be useful.

The following points are important mainly for the authors of the library itself:

  • For indentation, use tabs. Alignments that are not placed at the beginning of a line should be done with spaces.
  • For padding between functions, classes etc. use 2 empty lines
  • Source files are encoded as UTF-8 with Unix line endings (a simple LF, 0x0A or \n)

If you need further assistance, please do not hesitate to contact us through the channels shown at https://delta.chat/en/contribute

Please keep in mind, that your derived work must respect the Mozilla Public License 2.0 of libdeltachat and the respective licenses of the libraries libdeltachat links with.

See you.

dc_context_t::dc_get_msg
dc_msg_t * dc_get_msg(dc_context_t *context, uint32_t msg_id)
Get a single message object of the type dc_msg_t.
dc_context_t::dc_perform_imap_jobs
void dc_perform_imap_jobs(dc_context_t *context)
Execute pending imap-jobs.
dc_context_t::dc_create_chat_by_contact_id
uint32_t dc_create_chat_by_contact_id(dc_context_t *context, uint32_t contact_id)
Create a normal chat with a single user.
dc_context_t::dc_get_chat_msgs
dc_array_t * dc_get_chat_msgs(dc_context_t *context, uint32_t chat_id, uint32_t flags, uint32_t marker1before)
Get all message IDs belonging to a chat.
dc_array_t
dc_context_t::dc_str_unref
void dc_str_unref(char *str)
Release a string returned by another deltachat-core function.
dc_context_t::dc_perform_smtp_idle
void dc_perform_smtp_idle(dc_context_t *context)
Wait for smtp-jobs.
dc_context_t::dc_perform_smtp_jobs
void dc_perform_smtp_jobs(dc_context_t *context)
Execute pending smtp-jobs.
dc_msg_t::dc_msg_unref
void dc_msg_unref(dc_msg_t *msg)
Free a message object.
dc_array_t::dc_array_get_id
uint32_t dc_array_get_id(const dc_array_t *array, size_t index)
Get the item at the given index as an ID.
dc_context_t::dc_perform_imap_idle
void dc_perform_imap_idle(dc_context_t *context)
Wait for messages or jobs.
dc_context_t
dc_context_t::dc_configure
void dc_configure(dc_context_t *context)
Configure a context.
dc_context_t::dc_send_text_msg
uint32_t dc_send_text_msg(dc_context_t *context, uint32_t chat_id, const char *text_to_send)
Send a simple text message a given chat.
dc_context_t::dc_create_contact
uint32_t dc_create_contact(dc_context_t *context, const char *name, const char *addr)
Add a single contact as a result of an explicit user action.
dc_array_t::dc_array_get_cnt
size_t dc_array_get_cnt(const dc_array_t *array)
Find out the number of items in an array.
dc_context_t::dc_perform_imap_fetch
void dc_perform_imap_fetch(dc_context_t *context)
Fetch new messages, if any.
dc_msg_t
dc_context_t::dc_open
int dc_open(dc_context_t *context, const char *dbfile, const char *blobdir)
Open context database.
dc_context_t::dc_context_new
dc_context_t * dc_context_new(dc_callback_t cb, void *userdata, const char *os_name)
Create a new context object.
dc_context_t::dc_set_config
int dc_set_config(dc_context_t *context, const char *key, const char *value)
Configure the context.
dc_array_t::dc_array_unref
void dc_array_unref(dc_array_t *array)
Free an array object.
dc_msg_t::dc_msg_get_text
char * dc_msg_get_text(const dc_msg_t *msg)
Get the text of the message.