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

#include <deltachat.h>

Public Member Functions

uint32_t dc_accounts_add_account (dc_accounts_t *accounts)
 Add a new account to the account manager. More...
 
dc_context_tdc_accounts_get_account (dc_accounts_t *accounts, uint32_t account_id)
 Get an account-context from an account-id. More...
 
dc_array_tdc_accounts_get_all (dc_accounts_t *accounts)
 List all accounts. More...
 
dc_accounts_event_emitter_tdc_accounts_get_event_emitter (dc_accounts_t *accounts)
 Create the event emitter that is used to receive events. More...
 
dc_context_tdc_accounts_get_selected_account (dc_accounts_t *accounts)
 Get the currently selected account. More...
 
uint32_t dc_accounts_import_account (dc_accounts_t *accounts, const char *tarfile)
 Import a tarfile-backup to the account manager. More...
 
void dc_accounts_maybe_network (dc_accounts_t *accounts)
 This function should be called when there is a hint that the network is available again. More...
 
uint32_t dc_accounts_migrate_account (dc_accounts_t *accounts, const char *dbfile)
 Migrate independent accounts into accounts managed by the account manager. More...
 
dc_accounts_tdc_accounts_new (const char *os_name, const char *dir)
 Create a new account manager. More...
 
int dc_accounts_remove_account (dc_accounts_t *accounts, uint32_t account_id)
 Remove an account from the account manager. More...
 
int dc_accounts_select_account (dc_accounts_t *accounts, uint32_t account_id)
 Change the selected account. More...
 
void dc_accounts_start_io (dc_accounts_t *accounts)
 Start job and IMAP/SMTP tasks for all accounts managed by the account manager. More...
 
void dc_accounts_stop_io (dc_accounts_t *accounts)
 Stop job and IMAP/SMTP tasks for all accounts and return when they are finished. More...
 
void dc_accounts_unref (dc_accounts_t *accounts)
 Free an account manager object. More...
 

Detailed Description

This class provides functionality that can be used to manage several dc_context_t objects running at the same time. The account manager takes a directory where all context-databases are created in.

You can add, remove, import account to the account manager, all context-databases are persisted and stay available once the account manager is created again for the same directory.

All accounts may receive messages at the same time (eg. by DC_EVENT_INCOMING_MSG), and all accounts may be accessed by their own dc_context_t object.

To make this possible, some dc_context_t functions must not be called when using the account manager:

Additionally, there are functions to list, import and migrate accounts and to handle a "selected" account, see below.

Member Function Documentation

◆ dc_accounts_add_account()

uint32_t dc_accounts_add_account ( dc_accounts_t accounts)

Add a new account to the account manager.

Internally, dc_context_new() is called using a unique database-name in the directory specified at dc_accounts_new().

If the function succeeds, dc_accounts_get_all() will return one more account and you can access the newly created account using dc_accounts_get_account(). Moreover, the newly created account will be the selected one.

Parameters
accountsAccount manager as created by dc_accounts_new().
Returns
Account-id, use dc_accounts_get_account() to get the context object. On errors, 0 is returned.

◆ dc_accounts_get_account()

dc_context_t * dc_accounts_get_account ( dc_accounts_t accounts,
uint32_t  account_id 
)

Get an account-context from an account-id.

Parameters
accountsAccount manager as created by dc_accounts_new().
account_idThe account-id as returned e.g. by dc_accounts_get_all() or dc_accounts_add_account().
Returns
The account-context, this can be used most similar as a normal, unmanaged account-context as created by dc_context_new(). Once you do no longer need the context-object, you have to call dc_context_unref() on it, which, however, will not close the account but only decrease a reference counter.

◆ dc_accounts_get_all()

dc_array_t * dc_accounts_get_all ( dc_accounts_t accounts)

List all accounts.

Parameters
accountsAccount manager as created by dc_accounts_new().
Returns
An array containing all account-ids, use dc_array_get_id() to get the ids.

◆ dc_accounts_get_event_emitter()

dc_accounts_event_emitter_t * dc_accounts_get_event_emitter ( dc_accounts_t accounts)

Create the event emitter that is used to receive events.

The library will emit various DC_EVENT events as "new message", "message read" etc. To get these events, you have to create an event emitter using this function and call dc_accounts_get_next_event() on the emitter.

This is similar to dc_get_event_emitter(), which, however, must not be called for accounts handled by the account manager.

Parameters
accountsAccount manager as created by dc_accounts_new().
Returns
Returns the event emitter, NULL on errors. Must be freed using dc_accounts_event_emitter_unref() after usage.

Note: Use only one event emitter per account manager. Having more than one event emitter running at the same time on the same account manager will result in events randomly delivered to the one or to the other.

◆ dc_accounts_get_selected_account()

dc_context_t * dc_accounts_get_selected_account ( dc_accounts_t accounts)

Get the currently selected account.

If there is at least one account in the account-manager, there is always a selected one. To change the selected account, use dc_accounts_select_account(); also adding/importing/migrating accounts may change the selection.

Parameters
accountsAccount manager as created by dc_accounts_new().
Returns
The account-context, this can be used most similar as a normal, unmanaged account-context as created by dc_context_new(). Once you do no longer need the context-object, you have to call dc_context_unref() on it, which, however, will not close the account but only decrease a reference counter.

◆ dc_accounts_import_account()

uint32_t dc_accounts_import_account ( dc_accounts_t accounts,
const char *  tarfile 
)

Import a tarfile-backup to the account manager.

On success, a new account is added to the account-manager, with all the data provided by the backup-file. Moreover, the newly created account will be the selected one.

Parameters
accountsAccount manager as created by dc_accounts_new().
tarfileBackup as created by dc_imex().
Returns
Account-id, use dc_accounts_get_account() to get the context object. On errors, 0 is returned.

◆ dc_accounts_maybe_network()

void dc_accounts_maybe_network ( dc_accounts_t accounts)

This function should be called when there is a hint that the network is available again.

This is similar to dc_maybe_network(), which, however, must not be called for accounts handled by the account manager.

Parameters
accountsAccount manager as created by dc_accounts_new().

◆ dc_accounts_migrate_account()

uint32_t dc_accounts_migrate_account ( dc_accounts_t accounts,
const char *  dbfile 
)

Migrate independent accounts into accounts managed by the account manager.

This will move the database-file and all blob-files to the directory managed by the account-manager (to save disk-space on small devices, the files are not copied Once the migration is done, the original file is no longer existent). Moreover, the newly created account will be the selected one.

Parameters
accountsAccount manager as created by dc_accounts_new().
dbfileUnmanaged database-file that was created at some point using dc_context_new().
Returns
Account-id, use dc_accounts_get_account() to get the context object. On errors, 0 is returned.

◆ dc_accounts_new()

dc_accounts_t * dc_accounts_new ( const char *  os_name,
const char *  dir 
)

Create a new account manager.

The account manager takes an directory where all context-databases are placed in. To add a context to the account manager, use dc_accounts_add_account(), dc_accounts_import_account or dc_accounts_migrate_account(). All account information are persisted. To remove a context from the account manager, use dc_accounts_remove_account().

Parameters
os_name
dirThe directory to create the context-databases in. If the directory does not exist, dc_accounts_new() will try to create it.
Returns
An account manager object. The object must be passed to the other account manager functions and must be freed using dc_accounts_unref() after usage. On errors, NULL is returned.

◆ dc_accounts_remove_account()

int dc_accounts_remove_account ( dc_accounts_t accounts,
uint32_t  account_id 
)

Remove an account from the account manager.

This also removes the database-file and all blobs physically. If the removed account is the selected account, one of the other accounts will be selected.

Parameters
accountsAccount manager as created by dc_accounts_new().
account_idThe account-id as returned e.g. by dc_accounts_add_account().
Returns
1=success, 0=error

◆ dc_accounts_select_account()

int dc_accounts_select_account ( dc_accounts_t accounts,
uint32_t  account_id 
)

Change the selected account.

Parameters
accountsAccount manager as created by dc_accounts_new().
account_idThe account-id as returned e.g. by dc_accounts_get_all() or dc_accounts_add_account().
Returns
1=success, 0=error

◆ dc_accounts_start_io()

void dc_accounts_start_io ( dc_accounts_t accounts)

Start job and IMAP/SMTP tasks for all accounts managed by the account manager.

If IO is already running, nothing happens. This is similar to dc_start_io(), which, however, must not be called for accounts handled by the account manager.

Parameters
accountsAccount manager as created by dc_accounts_new().

◆ dc_accounts_stop_io()

void dc_accounts_stop_io ( dc_accounts_t accounts)

Stop job and IMAP/SMTP tasks for all accounts and return when they are finished.

This is similar to dc_stop_io(), which, however, must not be called for accounts handled by the account manager.

Parameters
accountsAccount manager as created by dc_accounts_new().

◆ dc_accounts_unref()

void dc_accounts_unref ( dc_accounts_t accounts)

Free an account manager object.

Parameters
accountsAccount manager as created by dc_accounts_new().

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