Mirrors/chatmail-core
1
0
Fork 0
mirror of https://github.com/chatmail/core.git synced 2026-09-22 04:58:47 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: add module documentation for calls

Browse Source
This commit is contained in:
link2xt
2026-08-28 14:47:09 +00:00
parent 506a78b5d4
commit 88930b6db4
1 changed files with 71 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
src/calls.rs
View File

@@ -1,7 +1,76 @@
//! # Handle calls.
//!
//! Internally, calls are bound a user-visible message initializing the call.
//! This means, the "Call ID" is a "Message ID" - similar to Webxdc IDs.
//! Calls are using [WebRTC].
//! Core does not implement WebRTC protocols and only offers a signalling channel.
//! Group calls are not supported, so calls can only be started in single chats.
//!
//! [WebRTC]: https://webrtc.org/
//!
//! ## How it works
//!
//! Caller (Alice) calls callee (Bob).
//!
//! Before starting a call, caller (Alice below) makes an SDP offer which contains socket addresses
//! that Alice can be reached on, called ICE candidates.
//! Creating an SDP offer requires having some STUN/TURN server,
//! so as a first step caller uses [`ice_servers`] to get a list
//! of the servers to put into
//! [`iceServers` argument of RTCPeerConnection constructor](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection#iceservers).
//!
//! Then Alice creates an SDP offer using
//! [`RTCPeerConnection.createOffer()` API](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createOffer)
//! and passes [created SDP offer in a text form](https://developer.mozilla.org/en-US/docs/Web/API/RTCSessionDescription/sdp)
//! to [`place_outgoing_call()` API][Context::place_outgoing_call] to start a new call.
//! `place_outgoing_call` returns ID of the call message that is visible in the chat.
//!
//! Starting a call results in sending a message with a `Chat-Webrtc-Room` header containing base64-encoded SDP offer.
//! When Bob receives a call, he gets a call message in chat with Alice.
//! and an [`EventType::IncomingCall`] event with an SDP offer.
//! Bob can also configure [`who_can_call_me`][crate::config::Config::WhoCanCallMe] configuration
//!
//! If Bob wants to answer a call, he needs to use this SDP offer
//! to construct an [SDP answer](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createAnswer).
//! Similarly to Alice, he uses [`ice_servers`] API.
//! Then Bob passes SDP answer to [`accept_incoming_call`][Context::accept_incoming_call].
//! This sends a message with `Chat-Content: call-accepted` header.
//!
//! When Alice's devices receive "call accepted" message from Bob,
//! they emit [`EventType::OutgoingCallAccepted`] event.
//! This message is also sent to self if [`Config::BccSelf`] is enabled.
//! When Bob's other device receives such message, it emits an [`EventType::IncomingCallAccepted`] event
//! so notification will disappear and the phone will stop ringing.
//!
//! If Bob does not answer the call within two minutes,
//! it becomes [missed][CallState::Missed]
//! and Bob gets an [`EventType::CallEnded`] event.
//! Call may also become missed immediately
//! if Bob was offline and receives an outdated call request.
//!
//! If Alice or Bob want to end a call, they use [`end_call` method][`Context::end_call`].
//! This results in sending a message with `Chat-Content: call-ended`.
//! Both Alice and Bob can end a call before the call actually starts,
//! in which case the call becomes
//! [canceled][CallState::Canceled] (for outgoing calls)
//! or [declined][CallState::Declined] (for incoming calls).
//!
//! For a reference implementation of the UI side refer to [Delta Chat webapp][webapp],
//! which can be used in a WebView on platforms that have it.
//! Using it is not required and does not prevent native implementations of the calls UI
//! or bots accepting and starting the calls, e.g. for bridging.
//!
//! [webapp]: https://github.com/deltachat/calls-webapp
//!
//! ## Public APIs
//!
//! Calls are uniquely identified by the [`MsgId`].
//! Internally, calls are bound to a user-visible message initializing the call.
//!
//! Public APIs for calls are:
//! - [`Context::place_outgoing_call`] (`dc_place_outgoing_call` for CFFI and `place_outgoing_call` for JSON-RPC)
//! - [`Context::accept_incoming_call`] (`dc_accept_incoming_call` for CFFI and `accept_incoming_call` for JSON-RPC)
//! - [`Context::end_call`] (`dc_end_call` for CFFI and `end_call` for JSON-RPC)
//! - [`CallInfo`] structure (loaded with `load_call_by_id` and `call_info` JSON-RPC API).
use crate::chat::ChatIdBlocked;
use crate::chat::{Chat, ChatId, send_msg};
use crate::config::Config;