swap paramters in sendUpdate(); the 'descr' may be split up in the future, so it makes sense to have that at the end

deltachat-ffi/deltachat.h

@@ -987,7 +987,7 @@ uint32_t dc_send_videochat_invitation (dc_context_t* context, uint32_t chat_id);
  *
  * In js-land, that would be mapped to sth. as:
  * ```
- * success = window.webxdc.sendUpdate('move A3 B4', '{"action":"move","src":"A3","dest":"B4"}');
+ * success = window.webxdc.sendUpdate('{"action":"move","src":"A3","dest":"B4"}', 'move A3 B4');
  * ```
  * `context` and `msg_id` is not needed in js as that is unique within an webxdc instance.
  * See dc_get_webxdc_status_updates() for the receiving counterpart.
@@ -1004,12 +1004,12 @@ uint32_t dc_send_videochat_invitation (dc_context_t* context, uint32_t chat_id);
  * @memberof dc_context_t
  * @param context The context object
  * @param msg_id id of the message with the webxdc instance
+ * @param json program-readable data, the actual payload
  * @param descr user-visible description of the json-data,
  *     in case of a chess game, eg. the move.
- * @param json program-readable data, the actual payload
  * @return 1=success, 0=error
  */
-int dc_send_webxdc_status_update (dc_context_t* context, uint32_t msg_id, const char* descr, const char* json);
+int dc_send_webxdc_status_update (dc_context_t* context, uint32_t msg_id, const char* json, const char* descr);
 
 
 /**

deltachat-ffi/src/lib.rs

@@ -881,8 +881,8 @@ pub unsafe extern "C" fn dc_send_videochat_invitation(
 pub unsafe extern "C" fn dc_send_webxdc_status_update(
     context: *mut dc_context_t,
     msg_id: u32,
-    descr: *const libc::c_char,
     json: *const libc::c_char,
+    descr: *const libc::c_char,
 ) -> libc::c_int {
     if context.is_null() {
         eprintln!("ignoring careless call to dc_send_webxdc_status_update()");
@@ -892,8 +892,8 @@ pub unsafe extern "C" fn dc_send_webxdc_status_update(
 
     block_on(ctx.send_webxdc_status_update(
         MsgId::new(msg_id),
-        &to_string_lossy(descr),
         &to_string_lossy(json),
+        &to_string_lossy(descr),
     ))
     .log_err(ctx, "Failed to send webxdc update")
     .is_ok() as libc::c_int

draft/webxdc-dev-reference.md

@@ -21,15 +21,15 @@ no need to add `webxdc.js` to your ZIP-file):
 ### sendUpdate()
 
 ```js
-window.webxdc.sendUpdate(descr, payload);
+window.webxdc.sendUpdate(payload, descr);
 ```
 
 Webxdc apps are usually shared in a chat and run independently on each peer.
 To get a shared state, the peers use `sendUpdate()` to send updates to each other.
 
+- `payload`: any javascript primitive, array or object.
 - `descr`: short, human-readable description what this update is about.
   this is shown eg. as a fallback text in an email program.
-- `payload`: any javascript primitive, array or object.
 
 All peers, including the sending one,
 will receive the update by the callback given to `setUpdateListener()`.
@@ -130,7 +130,7 @@ The following example shows an input field and  every input is show on all peers
     
       function sendMsg() {
         msg = document.getElementById("input").value;
-        window.webxdc.sendUpdate('Someone typed "'+msg+'".', msg);
+        window.webxdc.sendUpdate(msg, 'Someone typed "'+msg+'".');
       }
     
       function receiveUpdate(update) {

examples/repl/cmdline.rs

@@ -915,7 +915,7 @@ pub async fn cmdline(context: Context, line: &str, chat_id: &mut ChatId) -> Resu
             );
             let msg_id = MsgId::new(arg1.parse()?);
             context
-                .send_webxdc_status_update(msg_id, "this is a webxdc status update", arg2)
+                .send_webxdc_status_update(msg_id, arg2, "this is a webxdc status update")
                 .await?;
         }
         "videochat" => {

src/webxdc.rs

@@ -112,8 +112,8 @@ impl Context {
     pub async fn send_webxdc_status_update(
         &self,
         instance_msg_id: MsgId,
-        descr: &str,
         payload: &str,
+        descr: &str,
     ) -> Result<Option<MsgId>> {
         let instance = Message::load_from_db(self, instance_msg_id).await?;
         if instance.viewtype != Viewtype::Webxdc {
@@ -463,7 +463,7 @@ mod tests {
         .await?;
         chat_id.set_draft(&t, Some(&mut instance)).await?;
         let instance = chat_id.get_draft(&t).await?.unwrap();
-        t.send_webxdc_status_update(instance.id, "descr", "42")
+        t.send_webxdc_status_update(instance.id, "42", "descr")
             .await?;
         assert_eq!(
             t.get_webxdc_status_updates(instance.id, None).await?,
@@ -610,7 +610,7 @@ mod tests {
         assert!(!sent1.payload().contains("report-type=status-update"));
 
         let status_update_msg_id = alice
-            .send_webxdc_status_update(alice_instance.id, "descr text", r#"{"foo":"bar"}"#)
+            .send_webxdc_status_update(alice_instance.id, r#"{"foo":"bar"}"#, "descr text")
             .await?
             .unwrap();
         expect_status_update_event(&alice, alice_instance.id).await?;
@@ -636,7 +636,7 @@ mod tests {
         );
 
         alice
-            .send_webxdc_status_update(alice_instance.id, "bla text", r#"{"snipp":"snapp"}"#)
+            .send_webxdc_status_update(alice_instance.id, r#"{"snipp":"snapp"}"#, "bla text")
             .await?
             .unwrap();
         assert_eq!(
@@ -696,12 +696,12 @@ mod tests {
         let mut alice_instance = alice_chat_id.get_draft(&alice).await?.unwrap();
 
         let status_update_msg_id = alice
-            .send_webxdc_status_update(alice_instance.id, "descr", r#"{"foo":"bar"}"#)
+            .send_webxdc_status_update(alice_instance.id, r#"{"foo":"bar"}"#, "descr")
             .await?;
         assert_eq!(status_update_msg_id, None);
         expect_status_update_event(&alice, alice_instance.id).await?;
         let status_update_msg_id = alice
-            .send_webxdc_status_update(alice_instance.id, "descr", r#"42"#)
+            .send_webxdc_status_update(alice_instance.id, r#"42"#, "descr")
             .await?;
         assert_eq!(status_update_msg_id, None);
 
@@ -740,7 +740,7 @@ mod tests {
         let chat_id = create_group_chat(&t, ProtectionStatus::Unprotected, "foo").await?;
         let msg_id = send_text_msg(&t, chat_id, "ho!".to_string()).await?;
         assert!(t
-            .send_webxdc_status_update(msg_id, "descr", r#"{"foo":"bar"}"#)
+            .send_webxdc_status_update(msg_id, r#"{"foo":"bar"}"#, "descr")
             .await
             .is_err());
         Ok(())