diff --git a/deltachat-ffi/deltachat.h b/deltachat-ffi/deltachat.h index 8fdefbea5..bb7807d16 100644 --- a/deltachat-ffi/deltachat.h +++ b/deltachat-ffi/deltachat.h @@ -1096,9 +1096,9 @@ void dc_set_draft (dc_context_t* context, uint32_t ch * Add a message to the device-chat. * Device-messages usually contain update information * and some hints that are added during the program runs, multi-device etc. - * - * Device-messages may be added from the core, - * however, with this function, this can be done from the ui as well. + * The device-message is defined by a label; + * If a message with the same label was added or skipped before, + * the message is not added again, even if the message was deleted in between. * If needed, the device-chat is created before. * * Sends the event #DC_EVENT_MSGS_CHANGED on success. @@ -1106,50 +1106,13 @@ void dc_set_draft (dc_context_t* context, uint32_t ch * * @memberof dc_context_t * @param context The context as created by dc_context_new(). - * @param msg Message to be added to the device-chat. - * The message appears to the user as an incoming message. - * @return The ID of the added message. - */ -uint32_t dc_add_device_msg (dc_context_t* context, dc_msg_t* msg); - - -/** - * Add a message only one time to the device-chat. - * The device-message is defined by a name. - * If a message with the same name was added before, - * the message is not added again, even if the message was deleted in between. - * Use dc_add_device_msg() to add device-messages unconditionally. - * - * Sends the event #DC_EVENT_MSGS_CHANGED on success. - * - * @memberof dc_context_t - * @param context The context as created by dc_context_new(). * @param label A unique name for the message to add. * The label is typically not displayed to the user and * must be created from the characters `A-Z`, `a-z`, `0-9`, `_` or `-`. * @param msg Message to be added to the device-chat. * The message appears to the user as an incoming message. * @return The ID of the added message, - * if the message was already added before or on errors, 0 is returned. - */ -uint32_t dc_add_device_msg_once (dc_context_t* context, const char* label, dc_msg_t* msg); - - -/** - * Skip a device-message permanently. - * Subsequent calls to dc_add_device_msg_once() with the same label - * won't add the device-message then. - * This might be handy if you want to add - * eg. different messages for first-install and updates. - * - * @memberof dc_context_t - * @param context The context as created by dc_context_new(). - * @param label A unique name for the message to skip. - * The label is typically not displayed to the user and - * must be created from the characters `A-Z`, `a-z`, `0-9`, `_` or `-`. - * If a message with that label already exist, - * nothing happens. - * @return None. + * if the message was already added or skipped before or on errors, 0 is returned. * * Example: * ~~~ @@ -1170,6 +1133,41 @@ uint32_t dc_add_device_msg_once (dc_context_t* context, const char* * } * ~~~ */ +uint32_t dc_add_device_msg_once (dc_context_t* context, const char* label, dc_msg_t* msg); + + +/** + * Add a message to the device-chat unconditionally. + * As this skips the test if the message was added before, + * normally, you should prefer dc_add_device_msg_once() over this function + * + * Sends the event #DC_EVENT_MSGS_CHANGED on success. + * + * @memberof dc_context_t + * @param context The context as created by dc_context_new(). + * @param msg Message to be added to the device-chat. + * The message appears to the user as an incoming message. + * @return The ID of the added message. + */ +uint32_t dc_add_device_msg_unlabelled(dc_context_t* context, dc_msg_t* msg); + + +/** + * Skip a device-message permanently. + * Subsequent calls to dc_add_device_msg_once() with the same label + * won't add the device-message then. + * This might be handy if you want to add + * eg. different messages for first-install and updates. + * + * @memberof dc_context_t + * @param context The context as created by dc_context_new(). + * @param label A unique name for the message to skip. + * The label is typically not displayed to the user and + * must be created from the characters `A-Z`, `a-z`, `0-9`, `_` or `-`. + * If a message with that label already exist, + * nothing happens. + * @return None. + */ void dc_skip_device_msg (dc_context_t* context, const char* label); @@ -2798,9 +2796,7 @@ int dc_chat_is_self_talk (const dc_chat_t* chat); * From the ui view, device-talks are not very special, * the user can delete and forward messages, archive the chat, set notifications etc. * - * Messages may be added from the core to the device chat, - * so the chat just pops up as usual. - * However, if needed the ui can also add messages using dc_add_device_msg() + * Messages can be added to the device-talk using dc_add_device_msg_once() * * @memberof dc_chat_t * @param chat The chat object. diff --git a/deltachat-ffi/src/lib.rs b/deltachat-ffi/src/lib.rs index b0f469f9c..a8722ef47 100644 --- a/deltachat-ffi/src/lib.rs +++ b/deltachat-ffi/src/lib.rs @@ -812,16 +812,19 @@ pub unsafe extern "C" fn dc_set_draft( } #[no_mangle] -pub unsafe extern "C" fn dc_add_device_msg(context: *mut dc_context_t, msg: *mut dc_msg_t) -> u32 { +pub unsafe extern "C" fn dc_add_device_msg_unlabelled( + context: *mut dc_context_t, + msg: *mut dc_msg_t, +) -> u32 { if context.is_null() || msg.is_null() { - eprintln!("ignoring careless call to dc_add_device_msg()"); + eprintln!("ignoring careless call to dc_add_device_msg_unlabelled()"); return 0; } let ffi_context = &mut *context; let ffi_msg = &mut *msg; ffi_context .with_inner(|ctx| { - chat::add_device_msg(ctx, &mut ffi_msg.message) + chat::add_device_msg_unlabelled(ctx, &mut ffi_msg.message) .unwrap_or_log_default(ctx, "Failed to add device message") }) .map(|msg_id| msg_id.to_u32()) diff --git a/examples/repl/cmdline.rs b/examples/repl/cmdline.rs index 365853457..179f60499 100644 --- a/examples/repl/cmdline.rs +++ b/examples/repl/cmdline.rs @@ -837,7 +837,7 @@ pub unsafe fn dc_cmdline(context: &Context, line: &str) -> Result<(), failure::E ); let mut msg = Message::new(Viewtype::Text); msg.set_text(Some(arg1.to_string())); - chat::add_device_msg(context, &mut msg)?; + chat::add_device_msg_unlabelled(context, &mut msg)?; } "listmedia" => { ensure!(sel_chat.is_some(), "No chat selected."); diff --git a/src/chat.rs b/src/chat.rs index 289c31540..2ae1fa16a 100644 --- a/src/chat.rs +++ b/src/chat.rs @@ -1952,7 +1952,7 @@ pub fn get_chat_id_by_grpid(context: &Context, grpid: impl AsRef) -> (u32, .unwrap_or((0, false, Blocked::Not)) } -pub fn add_device_msg(context: &Context, msg: &mut Message) -> Result { +pub fn add_device_msg_unlabelled(context: &Context, msg: &mut Message) -> Result { add_device_msg_maybe_labelled(context, None, msg) } @@ -2147,18 +2147,18 @@ mod tests { } #[test] - fn test_add_device_msg() { + fn test_add_device_msg_unlabelled() { let t = test_context(Some(Box::new(logging_cb))); // add two device-messages let mut msg1 = Message::new(Viewtype::Text); msg1.text = Some("first message".to_string()); - let msg1_id = add_device_msg(&t.ctx, &mut msg1); + let msg1_id = add_device_msg_unlabelled(&t.ctx, &mut msg1); assert!(msg1_id.is_ok()); let mut msg2 = Message::new(Viewtype::Text); msg2.text = Some("second message".to_string()); - let msg2_id = add_device_msg(&t.ctx, &mut msg2); + let msg2_id = add_device_msg_unlabelled(&t.ctx, &mut msg2); assert!(msg2_id.is_ok()); assert_ne!(msg1_id.as_ref().unwrap(), msg2_id.as_ref().unwrap()); @@ -2263,7 +2263,7 @@ mod tests { let t = dummy_context(); let mut msg = Message::new(Viewtype::Text); msg.text = Some("foo".to_string()); - let msg_id = add_device_msg(&t.ctx, &mut msg).unwrap(); + let msg_id = add_device_msg_unlabelled(&t.ctx, &mut msg).unwrap(); let chat_id1 = message::Message::load_from_db(&t.ctx, msg_id) .unwrap() .chat_id;