From 1208de7c92f00687ccbbafcfcdc5f4a2bc72d7b0 Mon Sep 17 00:00:00 2001 From: "B. Petersen" Date: Wed, 10 Jun 2020 14:42:38 +0200 Subject: [PATCH 1/4] draft a possible download-api --- deltachat-ffi/deltachat.h | 84 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/deltachat-ffi/deltachat.h b/deltachat-ffi/deltachat.h index e2d363e6f..37d436ef0 100644 --- a/deltachat-ffi/deltachat.h +++ b/deltachat-ffi/deltachat.h @@ -3163,6 +3163,80 @@ int dc_msg_is_setupmessage (const dc_msg_t* msg); char* dc_msg_get_setupcodebegin (const dc_msg_t* msg); +/** + * Check if the message is completely downloaded. + * The UI should render the message as usual, + * using all the information available by the dc_msg_get_*() and related functions. + * In addition to that, there should be a download button indicating + * that the message is not yet downloaded and offering download. + * + * Once the button is clicked, + * the UI can call dc_download_msg() to start the download in the core + * or do the download on its own using dc_msg_get_download_url(). + * + * @memberof dc_msg_t + * @param msg The message object. + * @return 0=Message is completely downloaded, no special action required. + * 1=Message is not completely downloaded, download button needed. + */ +int dc_msg_needs_download(const dc_msg_t* msg); + + +/** + * Advices the core to start downloading a message. + * This function should only be called when the user hit the "Download" button + * that is shown by the UI in case dc_msg_needs_download() indicates a message is incomplete. + * During the download, the progress, errors and success are reported using @ref DC_EVENT_DOWNLOAD_PROGRESS. + * + * As an alternative, in some cases, also the UI can try to download the file, + * see dc_msg_get_download_url() and dc_set_download(). + * + * @memberof dc_context_t + * @param context The context object. + * @param msg_id Message-ID to download the content for. + */ +void dc_download_msg(dc_context_t* context, int msg_id); + + +/** + * Alternative approach to download messages. + * Get the URL that is needed to download the message. + * This function should only be called when the user hit the "Download" button + * that is shown by the UI in case dc_msg_needs_download() indicates a message is incomplete. + * Once the download is complete, + * the UI should call dc_set_download(). + * + * Instead of dc_msg_get_download_url() and a later dc_set_download(), + * calling dc_download_msg() might be easier, however, not all operating system support long lasting + * background tasks. With dc_msg_get_download_url(), it might be possible to delegate the work. + * + * @memberof dc_msg_t + * @param msg The message object. + * @return A URL that should downloaded, the result has to be passed to dc_set_download(). + * If the download is not possible by a simple URL or on errors, NULL is returned. + * In these cases, download using dc_download_msg() might be tried. + * The returned string must be released using dc_str_unref(). + */ +char* dc_msg_get_download_url(const dc_msg_t* msg); + + +/** + * Tell the core about a successfully completely download + * of the URL returned by dc_msg_get_download_url(). + * After this function is called, dc_msg_needs_download() will typically stop reporting the need of download. + * + * @memberof dc_context_t + * @param context The context object. + * @param msg_id Message-ID to set the download for. + * @param file_with_data File with the raw, complete download. If this file is already in the blob-directory, + * the core takes ownership of the file, otherwise, it is copied as needed. + * Please do not mix that with dc_msg_get_file() - + * the download may or may not be the file reported to the user later. + * @return 1=success, 0=error + */ +int dc_set_download(dc_context_t* context, int msg_id, const char* file_with_data); + + /** * Set the text of a message object. * This does not alter any information in the database; this may be done by dc_send_msg() later. @@ -4231,6 +4305,16 @@ void dc_event_unref(dc_event_t* event); */ #define DC_EVENT_SECUREJOIN_JOINER_PROGRESS 2061 + +/** + * Inform about the progress of a download started by dc_download_msg(). + * + * @param data1 (int) Message-ID the progress is reported for. + * @param data2 (int) 0=error, 1-999=progress in permille, 1000=success and done + */ +#define DC_EVENT_DOWNLOAD_PROGRESS 2070 + + /** * @} */ From 194970a164307103b436e7f52989bd7856e267ee Mon Sep 17 00:00:00 2001 From: "B. Petersen" Date: Wed, 10 Jun 2020 14:48:55 +0200 Subject: [PATCH 2/4] wording --- deltachat-ffi/deltachat.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deltachat-ffi/deltachat.h b/deltachat-ffi/deltachat.h index 37d436ef0..83706dd16 100644 --- a/deltachat-ffi/deltachat.h +++ b/deltachat-ffi/deltachat.h @@ -3165,7 +3165,7 @@ char* dc_msg_get_setupcodebegin (const dc_msg_t* msg); /** * Check if the message is completely downloaded. - * The UI should render the message as usual, + * If not, the UI should render the message as usual, * using all the information available by the dc_msg_get_*() and related functions. * In addition to that, there should be a download button indicating * that the message is not yet downloaded and offering download. From fa159cde3dbdea9194c8bf7a081f086751755f1c Mon Sep 17 00:00:00 2001 From: "B. Petersen" Date: Thu, 11 Jun 2020 01:44:03 +0200 Subject: [PATCH 3/4] draft, 2nd round --- deltachat-ffi/deltachat.h | 111 +++++++++++++++++++------------------- 1 file changed, 54 insertions(+), 57 deletions(-) diff --git a/deltachat-ffi/deltachat.h b/deltachat-ffi/deltachat.h index 83706dd16..33f614176 100644 --- a/deltachat-ffi/deltachat.h +++ b/deltachat-ffi/deltachat.h @@ -3164,77 +3164,51 @@ char* dc_msg_get_setupcodebegin (const dc_msg_t* msg); /** - * Check if the message is completely downloaded. - * If not, the UI should render the message as usual, - * using all the information available by the dc_msg_get_*() and related functions. - * In addition to that, there should be a download button indicating - * that the message is not yet downloaded and offering download. + * Check if the message is completely downloaded + * or if some further action is needed. * - * Once the button is clicked, - * the UI can call dc_download_msg() to start the download in the core - * or do the download on its own using dc_msg_get_download_url(). + * The function returns one of: + * - @ref DC_DOWNLOAD_NOT_NEEDED - The message does not need any further download action + * and should be rendered as usual. + * - @ref DC_DOWNLOAD_AVAILABLE - There is additional content to download. + * Tn addition to the usual message rendering, + * the UI shall show a download button that starts dc_schedule_download() + * - @ref DC_DOWNLOAD_IN_PROGRESS - Download was started with dc_schedule_download() and is still in progress. + * On progress changes and if the download fails or succeeds, + * the event @ref DC_EVENT_DOWNLOAD_PROGRESS will be emitted. + * - @ref DC_DOWNLOAD_DONE - Download finished successfully + * - @ref DC_DOWNLOAD_FAILURE - Download error, the user may start over calling dc_schedule_download() again. * * @memberof dc_msg_t * @param msg The message object. - * @return 0=Message is completely downloaded, no special action required. - * 1=Message is not completely downloaded, download button needed. + * @return One of the @ref DC_DOWNLOAD values */ -int dc_msg_needs_download(const dc_msg_t* msg); +int dc_msg_download_status(const dc_msg_t* msg); /** * Advices the core to start downloading a message. - * This function should only be called when the user hit the "Download" button - * that is shown by the UI in case dc_msg_needs_download() indicates a message is incomplete. - * During the download, the progress, errors and success are reported using @ref DC_EVENT_DOWNLOAD_PROGRESS. + * This function is typically called when the user hits the "Download" button + * that is shown by the UI in case dc_msg_download_status() + * returns @ref DC_DOWNLOAD_AVAILABLE or @ref DC_DOWNLOAD_FAILURE. * - * As an alternative, in some cases, also the UI can try to download the file, - * see dc_msg_get_download_url() and dc_set_download(). + * The UI may want to show a file selector and let the user chose a download location. + * The file name in the file selector may be prefilled using dc_msg_get_filename(). + * + * During the download, the progress, errors and success + * are reported using @ref DC_EVENT_DOWNLOAD_PROGRESS. + * + * Once the @ref DC_EVENT_DOWNLOAD_PROGRESS reports success, + * The file can be accessed as usual using dc_msg_get_file(). * * @memberof dc_context_t * @param context The context object. + * @param path Path to the destination file. + * You can specify NULL here to download + * to a reasonable file name in the internal blob-directory. * @param msg_id Message-ID to download the content for. */ -void dc_download_msg(dc_context_t* context, int msg_id); - - -/** - * Alternative approach to download messages. - * Get the URL that is needed to download the message. - * This function should only be called when the user hit the "Download" button - * that is shown by the UI in case dc_msg_needs_download() indicates a message is incomplete. - * Once the download is complete, - * the UI should call dc_set_download(). - * - * Instead of dc_msg_get_download_url() and a later dc_set_download(), - * calling dc_download_msg() might be easier, however, not all operating system support long lasting - * background tasks. With dc_msg_get_download_url(), it might be possible to delegate the work. - * - * @memberof dc_msg_t - * @param msg The message object. - * @return A URL that should downloaded, the result has to be passed to dc_set_download(). - * If the download is not possible by a simple URL or on errors, NULL is returned. - * In these cases, download using dc_download_msg() might be tried. - * The returned string must be released using dc_str_unref(). - */ -char* dc_msg_get_download_url(const dc_msg_t* msg); - - -/** - * Tell the core about a successfully completely download - * of the URL returned by dc_msg_get_download_url(). - * After this function is called, dc_msg_needs_download() will typically stop reporting the need of download. - * - * @memberof dc_context_t - * @param context The context object. - * @param msg_id Message-ID to set the download for. - * @param file_with_data File with the raw, complete download. If this file is already in the blob-directory, - * the core takes ownership of the file, otherwise, it is copied as needed. - * Please do not mix that with dc_msg_get_file() - - * the download may or may not be the file reported to the user later. - * @return 1=success, 0=error - */ -int dc_set_download(dc_context_t* context, int msg_id, const char* file_with_data); +void dc_schedule_download(dc_context_t* context, int msg_id, const char* path); /** @@ -4307,7 +4281,7 @@ void dc_event_unref(dc_event_t* event); /** - * Inform about the progress of a download started by dc_download_msg(). + * Inform about the progress of a download started by dc_schedule_download(). * * @param data1 (int) Message-ID the progress is reported for. * @param data2 (int) 0=error, 1-999=progress in permille, 1000=success and done @@ -4454,6 +4428,29 @@ void dc_event_unref(dc_event_t* event); */ +/** + * @defgroup DC_DOWNLOAD DC_DOWNLOAD + * + * These constants describe the download state of a message. + * The download state can be retrieved using dc_msg_download_status() + * and usually changes after calling dc_schedule_download(). + * + * @addtogroup DC_DOWNLOAD + * @{ + */ + +#define DC_DOWNLOAD_NOT_NEEDED 10 ///< Download not needed, see dc_msg_download_status() for details. +#define DC_DOWNLOAD_AVAILABLE 20 ///< Download available, see dc_msg_download_status() for details. +#define DC_DOWNLOAD_IN_PROGRESS 30 ///< Download in progress, see dc_msg_download_status() for details. +#define DC_DOWNLOAD_DONE 40 ///< Download done, see dc_msg_download_status() for details. +#define DC_DOWNLOAD_FAILURE 50 ///< Download failed, see dc_msg_download_status() for details. + +/** + * @} + */ + + + /* * TODO: Strings need some doumentation about used placeholders. * From 4da6177219727c02ed170ce7bb130a2de233f70c Mon Sep 17 00:00:00 2001 From: "B. Petersen" Date: Thu, 11 Jun 2020 17:10:26 +0200 Subject: [PATCH 4/4] use DC_DOWNLOAD_NO_URL --- deltachat-ffi/deltachat.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deltachat-ffi/deltachat.h b/deltachat-ffi/deltachat.h index 33f614176..e22ee1b69 100644 --- a/deltachat-ffi/deltachat.h +++ b/deltachat-ffi/deltachat.h @@ -3168,7 +3168,7 @@ char* dc_msg_get_setupcodebegin (const dc_msg_t* msg); * or if some further action is needed. * * The function returns one of: - * - @ref DC_DOWNLOAD_NOT_NEEDED - The message does not need any further download action + * - @ref DC_DOWNLOAD_NO_URL - The message does not need any further download action * and should be rendered as usual. * - @ref DC_DOWNLOAD_AVAILABLE - There is additional content to download. * Tn addition to the usual message rendering, @@ -4439,7 +4439,7 @@ void dc_event_unref(dc_event_t* event); * @{ */ -#define DC_DOWNLOAD_NOT_NEEDED 10 ///< Download not needed, see dc_msg_download_status() for details. +#define DC_DOWNLOAD_NO_URL 10 ///< Download not needed, see dc_msg_download_status() for details. #define DC_DOWNLOAD_AVAILABLE 20 ///< Download available, see dc_msg_download_status() for details. #define DC_DOWNLOAD_IN_PROGRESS 30 ///< Download in progress, see dc_msg_download_status() for details. #define DC_DOWNLOAD_DONE 40 ///< Download done, see dc_msg_download_status() for details.