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 create a context object bound to a database. The database is a normal SQLite file with a "blob directory" beside it. This will create "example.db" database and "example.db-blobs" directory if they don't exist already:

dc_context_t* context = dc_context_new(NULL, "example.db", NULL);
An object representing a single account.
dc_context_t * dc_context_new(const char *os_name, const char *dbfile, const char *blobdir)
Create a new context object and try to open it without passphrase.

After that, make sure you can receive events from the context. For that purpose, create an event emitter you can ask for events. If there is no event, the emitter will wait until there is one, so, in many situations, you will do this in a thread:

void* event_handler(void* context)
{
dc_event_t* event;
while ((event = dc_get_next_event(emitter)) != NULL) {
// use the event as needed, e.g. dc_event_get_id() returns the type.
// once you're done, unref the event to avoid memory leakage:
}
}
static pthread_t event_thread;
pthread_create(&event_thread, NULL, event_handler, context);
dc_event_emitter_t * dc_get_event_emitter(dc_context_t *context)
Create the event emitter that is used to receive events.
Opaque object that is used to get events from a single context.
void dc_event_emitter_unref(dc_event_emitter_t *emitter)
Free a context event emitter object.
dc_event_t * dc_get_next_event(dc_event_emitter_t *emitter)
Get the next event from a context event emitter object.
Opaque object describing a single event.
void dc_event_unref(dc_event_t *event)
Free memory used by an event object.

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.

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);
void dc_configure(dc_context_t *context)
Configure a context.
int dc_set_config(dc_context_t *context, const char *key, const char *value)
Configure the context.

dc_configure() returns immediately. The configuration itself runs in the background and may take a while. Once done, the DC_EVENT_CONFIGURE_PROGRESS reports success to the event_handler() you've 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()).

On a successfully configured context, you can finally connect to the servers:

dc_start_io(context);
void dc_start_io(dc_context_t *context)
Start job and IMAP/SMTP tasks.

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!");
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.
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.
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_send_text_msg() returns immediately; the sending itself is done in the background. If you check the testing address (bob), you should receive a normal e-mail. Answer this e-mail in any e-mail program with "Got it!", and the IO you started above will receive the message.

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

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);
An object containing a simple array.
void dc_array_unref(dc_array_t *array)
Free an array object.
size_t dc_array_get_cnt(const dc_array_t *array)
Find out the number of items in an array.
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_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_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.
void dc_str_unref(char *str)
Release a string returned by another deltachat-core function.
An object representing a single message in memory.
char * dc_msg_get_text(const dc_msg_t *msg)
Get the text of the message.
void dc_msg_unref(dc_msg_t *msg)
Free a message object.

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.

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.