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.
* For this, the function creates a job that is executed in the IMAP-thread then;
* Configure a context.
* 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.
*
* - Before you call this function, you should set at least `addr` and `mail_pw`
* using dc_set_config().
* - Before you call this function,
* 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 a different password for the SMTP server (otherwise `mail_pw` is used)
* - Use `mail_user` to use a different user name than `addr`
* and `send_pw` to use a different password for the SMTP server.
*
* - If _no_ more options are specified, the function tries to get these
* **using autoconfigure/autodiscover**.
* - If _no_ more options are specified,
* 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`
* are specified, **autoconfigure/autodiscover is skipped**.
* - If _more_ options as `mail_server`, `mail_port`, `send_server`,
* `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,
* you can stop it using dc_stop_ongoing_process().
* While dc_configure() returns immediately,
* 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
* a progress bar or stuff like that.
* During configuration, #DC_EVENT_CONFIGURE_PROGRESS events are emmited;
* 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
* @param context The context object as created by dc_context_new().
* @return None.
*
* There is no need to call this every program start, the result is saved in the
* database and you can use the connection directly:
* There is no need to call dc_configure() every program start,
* the configuration result is saved in the database
* and you can use the connection directly:
*
* ~~~
* if (!dc_is_configured(context)) {