yetangitu/deltachat-core
1
0
Fork 0
mirror of https://github.com/deltachat/deltachat-core.git synced 2025-10-06 03:50:08 +02:00
Code Issues Releases Wiki Activity

refine dc_configure() doc

Browse source
This commit is contained in:
B. Petersen 2018-11-16 15:53:10 +01:00
parent 0f5ad6711e
commit 9e23f48d70
No known key found for this signature in database
GPG key ID: 3B88E92DEA8E9AFC
1 changed files with 31 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

47
src/dc_configure.c
View file

@ -722,34 +722,49 @@ cleanup:
/** /**
* Configure and connect a context. * Configure a context.
* For this, the function creates a job that is executed in the IMAP-thread then; * For this purpose, the function creates a job
* that is executed in the IMAP-thread then;
* this requires to call dc_perform_imap_jobs() regularly. * this requires to call dc_perform_imap_jobs() regularly.
* *
* - Before you call this function, you should set at least `addr` and `mail_pw` * - Before you call this function,
* using dc_set_config(). * you must set at least `addr` and `mail_pw` using dc_set_config().
* *
* - Use `mail_user` to use a different user name than `addr` and `send_pw` to * - Use `mail_user` to use a different user name than `addr`
* use a different password for the SMTP server (otherwise `mail_pw` is used) * and `send_pw` to use a different password for the SMTP server.
* *
* - If _no_ more options are specified, the function tries to get these * - If _no_ more options are specified,
* **using autoconfigure/autodiscover**. * the function **uses autoconfigure/autodiscover**
* to get the full configuration from well-known URLs.
* *
* - If _more_ options as `mail_server`, `mail_port`, `send_server`, `send_port`, `send_user` or `server_flags` * - If _more_ options as `mail_server`, `mail_port`, `send_server`,
* are specified, **autoconfigure/autodiscover is skipped**. * `send_port`, `send_user` or `server_flags` are specified,
* **autoconfigure/autodiscover is skipped**.
* *
* - While dc_configure() returns immediately, the started configuration-job may take a while, * While dc_configure() returns immediately,
* you can stop it using dc_stop_ongoing_process(). * the started configuration-job may take a while.
* You can stop it using dc_stop_ongoing_process().
* *
* - The function sends out a number of #DC_EVENT_CONFIGURE_PROGRESS events that may be used to create * During configuration, #DC_EVENT_CONFIGURE_PROGRESS events are emmited;
* a progress bar or stuff like that. * they may be used to create a progress bar.
*
* On a successfull configuration,
* the core makes a copy of the parameters mentioned above:
* the original parameters as are never modified by the core.
*
* UI-implementors should keep this in mind -
* eg. if the UI wants to prefill a configure-edit-dialog with these parameters,
* the UI should reset them if the user cancels the dialog
* after a configure-attempts has failed.
* Otherwise the parameters may not reflect the current configuation.
* *
* @memberof dc_context_t * @memberof dc_context_t
* @param context The context object as created by dc_context_new(). * @param context The context object as created by dc_context_new().
* @return None. * @return None.
* *
* There is no need to call this every program start, the result is saved in the * There is no need to call dc_configure() every program start,
* database and you can use the connection directly: * the configuration result is saved in the database
* and you can use the connection directly:
* *
* ~~~ * ~~~
* if (!dc_is_configured(context)) { * if (!dc_is_configured(context)) {