diff --git a/deltachat-ffi/deltachat.h b/deltachat-ffi/deltachat.h index f79c4ba9a..59b7e8ced 100644 --- a/deltachat-ffi/deltachat.h +++ b/deltachat-ffi/deltachat.h @@ -2143,11 +2143,6 @@ dc_contact_t* dc_get_contact (dc_context_t* context, uint32_t co void dc_imex (dc_context_t* context, int what, const char* param1, const char* param2); -dc_backup_sender_t* dc_send_backup(dc_context_t* context, const char* folder, const char* passphrase); -char* dc_backup_sender_qr(dc_context_t* context, const dc_backup_sender_t* bs); -void dc_backup_sender_unref(dc_backup_sender_t* bs); - - /** * Check if there is a backup file. * May only be used on fresh installations (e.g. dc_is_configured() returns 0). @@ -2297,6 +2292,7 @@ void dc_stop_ongoing_process (dc_context_t* context); #define DC_QR_FPR_MISMATCH 220 // id=contact #define DC_QR_FPR_WITHOUT_ADDR 230 // test1=formatted fingerprint #define DC_QR_ACCOUNT 250 // text1=domain +#define DC_QR_BACKUP 251 // text1=ticket #define DC_QR_WEBRTC_INSTANCE 260 // text1=domain, text2=instance pattern #define DC_QR_ADDR 320 // id=contact #define DC_QR_TEXT 330 // text1=text @@ -2342,6 +2338,10 @@ void dc_stop_ongoing_process (dc_context_t* context); * ask the user if they want to create an account on the given domain, * if so, call dc_set_config_from_qr() and then dc_configure(). * + * - DC_QR_BACKUP with dc_lot_t::text1=ticket + * ask the user if they want to set up a new device. + * If so, get pass the ticket to dc_receive_backup(). + * * - DC_QR_WEBRTC_INSTANCE with dc_lot_t::text1=domain: * ask the user if they want to use the given service for video chats; * if so, call dc_set_config_from_qr(). @@ -2632,6 +2632,84 @@ char* dc_get_last_error (dc_context_t* context); void dc_str_unref (char* str); +/** + * @class dc_backup_sender_t + * + * Set up another device. + */ + +/** + * Create an object for sending a backup to another device. + * The backup is sent through an peer-to-peer channel which is bootstrapped by a QR-code. + * As a backup contains the whole state of the account, including credentials, + * this can be used to setup a new device. + * + * @memberof dc_backup_sender_t + * @param context The context. + * @param folder Path to create the backup in before it is sent out. + * The path must exist and being accessible at least until the other device has received all data. + * The folder is not cleaned up by the backup send; + * a temporary directory seems to be good place therefore. + * @param passphrase Used to at-rest-encrypt the backuped database in `folder` before sending, + * similar to dc_imex(). + * The same passphrase must be given to dc_receive_backup() on the other device. + * If NULL or empty string is given, the sent backup is not encrypted at rest. + * The transport of the backup is always encrypted additionally. + * @return Opaque object for sending the backup. + * On errors, NULL is returned and dc_get_last_error() returns an error that should be shown to the user. + */ +dc_backup_sender_t* dc_send_backup (dc_context_t* context, const char* folder, const char* passphrase); + + +/** + * Get QR code text that will offer the backup to other devices. + * The QR code contains a ticket that will unambiguously identify the backup. + * + * The scanning device will pass the scanned content to dc_check_qr() then; + * if dc_check_qr() returns DC_QR_BACKUP, + * the backup transfer can be started using dc_receive_backup(). + * + * @memberof dc_backup_sender_t + * @param context The context. + * @param backup_sender The backup sender object as created by dc_send_backup(). + * @return The text that should go to the QR code, + * On errors, an empty QR code is returned, NULL is never returned. + * The returned string must be released using dc_str_unref() after usage. + */ +char* dc_backup_sender_qr (dc_context_t* context, const dc_backup_sender_t* backup_sender); + + +/** + * Free a backup sender object. + * + * @memberof dc_backup_sender_t + * @param backup_sender The backup sender object as created by dc_send_backup(), + * If NULL is given, nothing is done. + */ +void dc_backup_sender_unref (dc_backup_sender_t* backup_sender); + + +/** + * Receive a backup offered by a dc_backup_sender_t object on another device. + * + * This function is typically not called on the device where the dc_backup_sender_t object exist, + * but on a device that has scanned the QR code generated by dc_backup_sender_qr(). + * + * While dc_receive_backup() returns immediately, the started job may take a while; + * you can stop it using dc_stop_ongoing_process(). + * During execution of the job #DC_EVENT_IMEX_PROGRESS is sent out several times to indicate state and progress. + * + * @memberof dc_backup_sender_t + * @param context The context. + * @param ticket The ticket of the backup from the QR code: + * If dc_check_qr() returns DC_QR_BACKUP, you can get the ticket from the QR code using dc_lot_get_text1(). + * @param passphrase Passphrase for the additional at-rest-encryption + * as defined at dc_send_backup() on the other device. + * If no passphrase is used, pass NULL or empty string. + */ +void dc_receive_backup (dc_context_t* context, const char* ticket, const char* passphrase); + + /** * @class dc_accounts_t *