name unlabelled device-messages as such

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.

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())

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.");

src/chat.rs

@@ -1952,7 +1952,7 @@ pub fn get_chat_id_by_grpid(context: &Context, grpid: impl AsRef<str>) -> (u32,
         .unwrap_or((0, false, Blocked::Not))
 }
 
-pub fn add_device_msg(context: &Context, msg: &mut Message) -> Result<MsgId, Error> {
+pub fn add_device_msg_unlabelled(context: &Context, msg: &mut Message) -> Result<MsgId, Error> {
     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;