dc_accounts_t Class Reference

This class provides functionality that can be used to manage several dc_context_t objects running at the same time. More...

#include <deltachat.h>

Public Member Functions
uint32_t	dc_accounts_add_account (dc_accounts_t *accounts)
	Add a new account to the account manager.
uint32_t	dc_accounts_add_closed_account (dc_accounts_t *accounts)
	Add a new closed account to the account manager.
int	dc_accounts_background_fetch (dc_accounts_t *accounts, uint64_t timeout)
	Perform a background fetch for all accounts in parallel with a timeout.
dc_context_t *	dc_accounts_get_account (dc_accounts_t *accounts, uint32_t account_id)
	Get an account context from an account ID.
dc_array_t *	dc_accounts_get_all (dc_accounts_t *accounts)
	List all accounts.
dc_event_emitter_t *	dc_accounts_get_event_emitter (dc_accounts_t *accounts)
	Create the event emitter that is used to receive events.
dc_context_t *	dc_accounts_get_selected_account (dc_accounts_t *accounts)
	Get the currently selected account.
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.
void	dc_accounts_maybe_network_lost (dc_accounts_t *accounts)
	This function can be called when there is a hint that the network is lost.
uint32_t	dc_accounts_migrate_account (dc_accounts_t *accounts, const char *dbfile)
	Migrate independent accounts into accounts managed by the account manager.
dc_accounts_t *	dc_accounts_new (const char *dir, int writable)
	Create a new account manager.
int	dc_accounts_remove_account (dc_accounts_t *accounts, uint32_t account_id)
	Remove an account from the account manager.
int	dc_accounts_select_account (dc_accounts_t *accounts, uint32_t account_id)
	Change the selected account.
void	dc_accounts_set_push_device_token (dc_accounts_t *accounts, const char *token)
	Sets device token for Apple Push Notification service.
void	dc_accounts_start_io (dc_accounts_t *accounts)
	Start job and IMAP/SMTP tasks for all accounts managed by the account manager.
void	dc_accounts_stop_io (dc_accounts_t *accounts)
	Stop job and IMAP/SMTP tasks for all accounts and return when they are finished.
void	dc_accounts_unref (dc_accounts_t *accounts)
	Free an account manager object.
dc_jsonrpc_instance_t *	dc_jsonrpc_init (dc_accounts_t *account_manager)
	Create the jsonrpc instance that is used to call the jsonrpc.

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 (e.g. 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:

• use dc_accounts_add_account() and dc_accounts_get_account() instead of dc_context_new()
• use dc_accounts_add_closed_account() instead of dc_context_new_closed()
• use dc_accounts_start_io() and dc_accounts_stop_io() instead of dc_start_io() and dc_stop_io()
• use dc_accounts_maybe_network() instead of dc_maybe_network()
• use dc_accounts_get_event_emitter() instead of dc_get_event_emitter()

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

accounts

The account manager as created by dc_accounts_new().

Returns

The account ID, use dc_accounts_get_account() to get the context object. On errors, 0 is returned.

dc_accounts_add_closed_account()

uint32_t dc_accounts_add_closed_account

(

dc_accounts_t *

accounts

)

Add a new closed account to the account manager.

Internally, dc_context_new_closed() 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

accounts

The account manager as created by dc_accounts_new().

Returns

The account ID, use dc_accounts_get_account() to get the context object. On errors, 0 is returned.

dc_accounts_background_fetch()

int dc_accounts_background_fetch	(	dc_accounts_t *	accounts,
		uint64_t	timeout )

Perform a background fetch for all accounts in parallel with a timeout.

Pauses the scheduler, fetches messages from imap and then resumes the scheduler.

dc_accounts_background_fetch() was created for the iOS Background fetch.

The DC_EVENT_ACCOUNTS_BACKGROUND_FETCH_DONE event is emitted at the end even in case of timeout, unless the function fails and returns 0. Process all events until you get this one and you can safely return to the background without forgetting to create notifications caused by timing race conditions.

Parameters

timeout

The timeout in seconds

Returns

Return 1 if DC_EVENT_ACCOUNTS_BACKGROUND_FETCH_DONE was emitted and 0 otherwise.

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

accounts	The account manager as created by dc_accounts_new().
account_id	The 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

accounts

The account 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_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_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

accounts

The account manager as created by dc_accounts_new().

Returns

Returns the event emitter, NULL on errors. Must be freed using dc_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

accounts

The account 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. If there is no selected account, NULL 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

accounts

The account manager as created by dc_accounts_new().

dc_accounts_maybe_network_lost()

void dc_accounts_maybe_network_lost

(

dc_accounts_t *

accounts

)

This function can be called when there is a hint that the network is lost.

This is similar to dc_accounts_maybe_network(), however, it does not retry job processing.

dc_accounts_maybe_network_lost() is needed only on systems where the core cannot find out the connectivity loss on its own, e.g. iOS. The function is not needed on Android, MacOS, Windows or Linux.

Parameters

accounts

The account 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

accounts	The account manager as created by dc_accounts_new().
dbfile	The unmanaged database file that was created at some point using dc_context_new().

Returns

The 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 *	dir,
		int	writable )

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() or dc_accounts_migrate_account(). All account information are persisted. To remove a context from the account manager, use dc_accounts_remove_account().

Parameters

dir	The directory to create the context-databases in. If the directory does not exist, dc_accounts_new() will try to create it.
writable	Whether the returned account manager is writable, i.e. calling these functions on it is possible: dc_accounts_add_account(), dc_accounts_add_closed_account(), dc_accounts_migrate_account(), dc_accounts_remove_account(), dc_accounts_select_account().

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

accounts	The account manager as created by dc_accounts_new().
account_id	The 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

accounts	Account manager as created by dc_accounts_new().
account_id	The account ID as returned e.g. by dc_accounts_get_all() or dc_accounts_add_account().

Returns

1=success, 0=error

dc_accounts_set_push_device_token()

void dc_accounts_set_push_device_token	(	dc_accounts_t *	accounts,
		const char *	token )

Sets device token for Apple Push Notification service.

Returns immediately.

Parameters

token

Hexadecimal device token

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

accounts

The account 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

accounts

The account manager as created by dc_accounts_new().

dc_accounts_unref()

void dc_accounts_unref

(

dc_accounts_t *

accounts

)

Free an account manager object.

Parameters

accounts

Account manager as created by dc_accounts_new().

dc_jsonrpc_init()

dc_jsonrpc_instance_t * dc_jsonrpc_init

(

dc_accounts_t *

account_manager

)

Create the jsonrpc instance that is used to call the jsonrpc.

Parameters

account_manager

The accounts object as created by dc_accounts_new().

Returns

Returns the jsonrpc instance, NULL on errors. Must be freed using dc_jsonrpc_unref() after usage.

---

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

• deltachat.h