feat: add call ringing API (#6650)

this PR adds a "ringing" api that can be used for calls later.

see deltachat.h for details about the API; jsonrpc is left out until
things are settled for the needs of android/iOS

UI using this PR already successfully are
deltachat/deltachat-ios#2638 and
deltachat/deltachat-android#3785 ; the "payload"
passed forth and back is optimised for
https://github.com/deltachat/calls-webapp

---------

Co-authored-by: l <[email protected]>

Author: r10s

deltachat-ffi/deltachat.h

@@ -1215,6 +1215,103 @@ void             dc_set_webxdc_integration (dc_context_t* context, const char* f
 uint32_t        dc_init_webxdc_integration    (dc_context_t* context, uint32_t chat_id);
 
 
+/**
+ * Start an outgoing call.
+ * This sends a message with all relevant information to the callee,
+ * who will get informed by an #DC_EVENT_INCOMING_CALL event and rings.
+ *
+ * Possible actions during ringing:
+ *
+ * - caller cancels the call using dc_end_call():
+ *   callee receives #DC_EVENT_CALL_ENDED
+ *
+ * - callee accepts using dc_accept_incoming_call():
+ *   caller receives #DC_EVENT_OUTGOING_CALL_ACCEPTED.
+ *   callee's devices receive #DC_EVENT_INCOMING_CALL_ACCEPTED, call starts
+ *
+ * - callee rejects using dc_end_call():
+ *   caller receives #DC_EVENT_CALL_ENDED after 1 minute timeout.
+ *   callee's other devices receive #DC_EVENT_CALL_ENDED
+ *
+ * - callee is already in a call:
+ *   in this case, UI may decide to show a notification instead of ringing.
+ *   otherwise, this is same as timeout
+ *
+ * - timeout:
+ *   after 1 minute without action,
+ *   caller and callee receive #DC_EVENT_CALL_ENDED
+ *   to prevent endless ringing of callee
+ *   in case caller got offline without being able to send cancellation message
+ *
+ * Actions during the call:
+ *
+ * - caller ends the call using dc_end_call():
+ *   callee receives #DC_EVENT_CALL_ENDED
+ *
+ * - callee ends the call using dc_end_call():
+ *   caller receives #DC_EVENT_CALL_ENDED
+ *
+ * Note, that the events are for updating the call screen,
+ * possible status messages are added and updated as usual, including the known events.
+ * In the UI, the sorted chatlist is used as an overview about calls as well as messages.
+ * To place a call with a contact that has no chat yet, use dc_create_chat_by_contact_id() first.
+ *
+ * UI will usually allow only one call at the same time,
+ * this has to be tracked by UI across profile, the core does not track this.
+ *
+ * @memberof dc_context_t
+ * @param context The context object.
+ * @param chat_id The chat to place a call for.
+ *     This needs to be a one-to-one chat.
+ * @param place_call_info any data that other devices receive
+ *     in #DC_EVENT_INCOMING_CALL.
+ * @return ID of the system message announcing the call.
+ */
+uint32_t        dc_place_outgoing_call       (dc_context_t* context, uint32_t chat_id, const char* place_call_info);
+
+
+/**
+ * Accept incoming call.
+ *
+ * This implicitly accepts the contact request, if not yet done.
+ * All affected devices will receive
+ * either #DC_EVENT_OUTGOING_CALL_ACCEPTED or #DC_EVENT_INCOMING_CALL_ACCEPTED.
+ *
+ * @memberof dc_context_t
+ * @param context The context object.
+ * @param msg_id The ID of the call to accept.
+ *     This is the ID reported by #DC_EVENT_INCOMING_CALL
+ *     and equals to the ID of the corresponding info message.
+ * @param accept_call_info any data that other devices receive
+ *     in #DC_EVENT_OUTGOING_CALL_ACCEPTED or #DC_EVENT_INCOMING_CALL_ACCEPTED.
+ * @return 1=success, 0=error
+ */
+ int            dc_accept_incoming_call      (dc_context_t* context, uint32_t msg_id, const char* accept_call_info);
+
+
+ /**
+  * End incoming or outgoing call.
+  *
+  * From the view of the caller, a "cancellation",
+  * from the view of callee, a "rejection".
+  * If the call was accepted, this is a "hangup".
+  *
+  * For accepted calls,
+  * all participant devices get informed about the ended call via #DC_EVENT_CALL_ENDED.
+  * For not accepted calls, only the caller will inform the callee.
+  *
+  * If the callee rejects, the caller will get a timeout or give up at some point -
+  * same as for all other reasons the call cannot be established: Device not in reach, device muted, connectivity etc.
+  * This is to protect privacy of the callee, avoiding to check if callee is online.
+  *
+  * @memberof dc_context_t
+  * @param context The context object.
+  * @param msg_id the ID of the call.
+  * @return 1=success, 0=error
+  */
+ int            dc_end_call                  (dc_context_t* context, uint32_t msg_id);
+
+
 /**
  * Save a draft for a chat in the database.
  *
@@ -4546,6 +4643,8 @@ int             dc_msg_is_info                (const dc_msg_t* msg);
  *   and also offer a way to fix the encryption, eg. by a button offering a QR scan
  * - DC_INFO_WEBXDC_INFO_MESSAGE (32) - Info-message created by webxdc app sending `update.info`
  * - DC_INFO_CHAT_E2EE (50) - Info-message for "Chat is end-to-end-encrypted"
+ * - DC_INFO_OUTGOING_CALL (60) - Info-message refers to an outgoing call
+ * - DC_INFO_INCOMING_CALL (65) - Info-message refers to an incoming call
  *
  * For the messages that refer to a CONTACT,
  * dc_msg_get_info_contact_id() returns the contact ID.
@@ -4602,6 +4701,8 @@ uint32_t        dc_msg_get_info_contact_id    (const dc_msg_t* msg);
 #define         DC_INFO_INVALID_UNENCRYPTED_MAIL  13
 #define         DC_INFO_WEBXDC_INFO_MESSAGE       32
 #define         DC_INFO_CHAT_E2EE                 50
+#define         DC_INFO_OUTGOING_CALL             60
+#define         DC_INFO_INCOMING_CALL             65
 
 
 /**
@@ -6636,6 +6737,63 @@ void dc_event_unref(dc_event_t* event);
  */
 #define DC_EVENT_CHANNEL_OVERFLOW              2400
 
+
+
+/**
+ * Incoming call.
+ * UI will usually start ringing,
+ * or show a notification if there is already a call in some profile.
+ *
+ * Together with this event,
+ * an info-message is added to the corresponding chat.
+ * The info-message, however, is _not_ additionally notified using #DC_EVENT_INCOMING_MSG,
+ * if needed, this has to be done by the UI explicitly.
+ *
+ * If user takes action, dc_accept_incoming_call() or dc_end_call() should be called.
+ *
+ * Otherwise, ringing should end on #DC_EVENT_CALL_ENDED
+ * or #DC_EVENT_INCOMING_CALL_ACCEPTED
+ *
+ * @param data1 (int) msg_id ID of the info-message referring to the call.
+ * @param data2 (char*) place_call_info, text passed to dc_place_outgoing_call()
+ */
+#define DC_EVENT_INCOMING_CALL                            2550
+
+/**
+ * The callee accepted an incoming call on another device using dc_accept_incoming_call().
+ * The caller gets the event #DC_EVENT_OUTGOING_CALL_ACCEPTED at the same time.
+ *
+ * The event is sent unconditionally when the corresponding message is received.
+ * UI should only take action in case call UI was opened before, otherwise the event should be ignored.
+ *
+ * @param data1 (int) msg_id ID of the info-message referring to the call
+ * @param data2 (char*) accept_call_info, text passed to dc_place_outgoing_call()
+ */
+ #define DC_EVENT_INCOMING_CALL_ACCEPTED                  2560
+
+/**
+ * A call placed using dc_place_outgoing_call() was accepted by the callee using dc_accept_incoming_call().
+ *
+ * The event is sent unconditionally when the corresponding message is received.
+ * UI should only take action in case call UI was opened before, otherwise the event should be ignored.
+ *
+ * @param data1 (int) msg_id ID of the info-message referring to the call
+ * @param data2 (char*) accept_call_info, text passed to dc_accept_incoming_call()
+ */
+#define DC_EVENT_OUTGOING_CALL_ACCEPTED                   2570
+
+/**
+ * An incoming or outgoing call was ended using dc_end_call().
+ * Moreover, the event is sent when the call was not accepted within 1 minute timeout.
+ *
+ * The event is sent unconditionally when the corresponding message is received.
+ * UI should only take action in case call UI was opened before, otherwise the event should be ignored.
+ *
+ * @param data1 (int) msg_id ID of the info-message referring to the call
+ */
+#define DC_EVENT_CALL_ENDED                               2580
+
+
 /**
  * @}
  */

deltachat-ffi/src/lib.rs

@@ -556,6 +556,10 @@ pub unsafe extern "C" fn dc_event_get_id(event: *mut dc_event_t) -> libc::c_int
         EventType::AccountsChanged => 2302,
         EventType::AccountsItemChanged => 2303,
         EventType::EventChannelOverflow { .. } => 2400,
+        EventType::IncomingCall { .. } => 2550,
+        EventType::IncomingCallAccepted { .. } => 2560,
+        EventType::OutgoingCallAccepted { .. } => 2570,
+        EventType::CallEnded { .. } => 2580,
         #[allow(unreachable_patterns)]
         #[cfg(test)]
         _ => unreachable!("This is just to silence a rust_analyzer false-positive"),
@@ -619,7 +623,11 @@ pub unsafe extern "C" fn dc_event_get_data1_int(event: *mut dc_event_t) -> libc:
         EventType::WebxdcRealtimeData { msg_id, .. }
         | EventType::WebxdcStatusUpdate { msg_id, .. }
         | EventType::WebxdcRealtimeAdvertisementReceived { msg_id }
-        | EventType::WebxdcInstanceDeleted { msg_id, .. } => msg_id.to_u32() as libc::c_int,
+        | EventType::WebxdcInstanceDeleted { msg_id, .. }
+        | EventType::IncomingCall { msg_id, .. }
+        | EventType::IncomingCallAccepted { msg_id, .. }
+        | EventType::OutgoingCallAccepted { msg_id, .. }
+        | EventType::CallEnded { msg_id, .. } => msg_id.to_u32() as libc::c_int,
         EventType::ChatlistItemChanged { chat_id } => {
             chat_id.unwrap_or_default().to_u32() as libc::c_int
         }
@@ -671,6 +679,10 @@ pub unsafe extern "C" fn dc_event_get_data2_int(event: *mut dc_event_t) -> libc:
         | EventType::ChatModified(_)
         | EventType::ChatDeleted { .. }
         | EventType::WebxdcRealtimeAdvertisementReceived { .. }
+        | EventType::IncomingCall { .. }
+        | EventType::IncomingCallAccepted { .. }
+        | EventType::OutgoingCallAccepted { .. }
+        | EventType::CallEnded { .. }
         | EventType::EventChannelOverflow { .. } => 0,
         EventType::MsgsChanged { msg_id, .. }
         | EventType::ReactionsChanged { msg_id, .. }
@@ -767,8 +779,23 @@ pub unsafe extern "C" fn dc_event_get_data2_str(event: *mut dc_event_t) -> *mut
         | EventType::ChatlistChanged
         | EventType::AccountsChanged
         | EventType::AccountsItemChanged
-        | EventType::WebxdcRealtimeAdvertisementReceived { .. }
-        | EventType::EventChannelOverflow { .. } => ptr::null_mut(),
+        | EventType::WebxdcRealtimeAdvertisementReceived { .. } => ptr::null_mut(),
+        EventType::IncomingCall {
+            place_call_info, ..
+        } => {
+            let data2 = place_call_info.to_c_string().unwrap_or_default();
+            data2.into_raw()
+        }
+        EventType::IncomingCallAccepted {
+            accept_call_info, ..
+        }
+        | EventType::OutgoingCallAccepted {
+            accept_call_info, ..
+        } => {
+            let data2 = accept_call_info.to_c_string().unwrap_or_default();
+            data2.into_raw()
+        }
+        EventType::CallEnded { .. } | EventType::EventChannelOverflow { .. } => ptr::null_mut(),
         EventType::ConfigureProgress { comment, .. } => {
             if let Some(comment) = comment {
                 comment.to_c_string().unwrap_or_default().into_raw()
@@ -1167,6 +1194,61 @@ pub unsafe extern "C" fn dc_init_webxdc_integration(
         .unwrap_or(0)
 }
 
+#[no_mangle]
+pub unsafe extern "C" fn dc_place_outgoing_call(
+    context: *mut dc_context_t,
+    chat_id: u32,
+    place_call_info: *const libc::c_char,
+) -> u32 {
+    if context.is_null() || chat_id == 0 {
+        eprintln!("ignoring careless call to dc_place_outgoing_call()");
+        return 0;
+    }
+    let ctx = &*context;
+    let chat_id = ChatId::new(chat_id);
+    let place_call_info = to_string_lossy(place_call_info);
+
+    block_on(ctx.place_outgoing_call(chat_id, place_call_info))
+        .context("Failed to place call")
+        .log_err(ctx)
+        .map(|msg_id| msg_id.to_u32())
+        .unwrap_or_log_default(ctx, "Failed to place call")
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn dc_accept_incoming_call(
+    context: *mut dc_context_t,
+    msg_id: u32,
+    accept_call_info: *const libc::c_char,
+) -> libc::c_int {
+    if context.is_null() || msg_id == 0 {
+        eprintln!("ignoring careless call to dc_accept_incoming_call()");
+        return 0;
+    }
+    let ctx = &*context;
+    let msg_id = MsgId::new(msg_id);
+    let accept_call_info = to_string_lossy(accept_call_info);
+
+    block_on(ctx.accept_incoming_call(msg_id, accept_call_info))
+        .context("Failed to accept call")
+        .is_ok() as libc::c_int
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn dc_end_call(context: *mut dc_context_t, msg_id: u32) -> libc::c_int {
+    if context.is_null() || msg_id == 0 {
+        eprintln!("ignoring careless call to dc_end_call()");
+        return 0;
+    }
+    let ctx = &*context;
+    let msg_id = MsgId::new(msg_id);
+
+    block_on(ctx.end_call(msg_id))
+        .context("Failed to end call")
+        .log_err(ctx)
+        .is_ok() as libc::c_int
+}
+
 #[no_mangle]
 pub unsafe extern "C" fn dc_set_draft(
     context: *mut dc_context_t,

deltachat-jsonrpc/src/api/types/events.rs

@@ -416,6 +416,37 @@ pub enum EventType {
         /// Number of events skipped.
         n: u64,
     },
+
+    /// Incoming call.
+    IncomingCall {
+        /// ID of the info message referring to the call.
+        msg_id: u32,
+        /// User-defined info as passed to place_outgoing_call()
+        place_call_info: String,
+    },
+
+    /// Incoming call accepted.
+    /// This is esp. interesting to stop ringing on other devices.
+    IncomingCallAccepted {
+        /// ID of the info message referring to the call.
+        msg_id: u32,
+        /// User-defined info passed to dc_accept_incoming_call()
+        accept_call_info: String,
+    },
+
+    /// Outgoing call accepted.
+    OutgoingCallAccepted {
+        /// ID of the info message referring to the call.
+        msg_id: u32,
+        /// User-defined info passed to dc_accept_incoming_call(
+        accept_call_info: String,
+    },
+
+    /// Call ended.
+    CallEnded {
+        /// ID of the info message referring to the call.
+        msg_id: u32,
+    },
 }
 
 impl From<CoreEventType> for EventType {
@@ -566,6 +597,30 @@ impl From<CoreEventType> for EventType {
             CoreEventType::EventChannelOverflow { n } => EventChannelOverflow { n },
             CoreEventType::AccountsChanged => AccountsChanged,
             CoreEventType::AccountsItemChanged => AccountsItemChanged,
+            CoreEventType::IncomingCall {
+                msg_id,
+                place_call_info,
+            } => IncomingCall {
+                msg_id: msg_id.to_u32(),
+                place_call_info,
+            },
+            CoreEventType::IncomingCallAccepted {
+                msg_id,
+                accept_call_info,
+            } => IncomingCallAccepted {
+                msg_id: msg_id.to_u32(),
+                accept_call_info,
+            },
+            CoreEventType::OutgoingCallAccepted {
+                msg_id,
+                accept_call_info,
+            } => OutgoingCallAccepted {
+                msg_id: msg_id.to_u32(),
+                accept_call_info,
+            },
+            CoreEventType::CallEnded { msg_id } => CallEnded {
+                msg_id: msg_id.to_u32(),
+            },
             #[allow(unreachable_patterns)]
             #[cfg(test)]
             _ => unreachable!("This is just to silence a rust_analyzer false-positive"),