From d96c9f85a1d7f5a930440259acae96eb25a22b8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Thu, 8 Oct 2020 14:50:35 +0200 Subject: [PATCH] crypto: Add doces for the get_missing_sessions method. --- matrix_sdk_crypto/src/session_manager.rs | 27 ++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/matrix_sdk_crypto/src/session_manager.rs b/matrix_sdk_crypto/src/session_manager.rs index f9ec8913..e0dc57bf 100644 --- a/matrix_sdk_crypto/src/session_manager.rs +++ b/matrix_sdk_crypto/src/session_manager.rs @@ -42,6 +42,33 @@ impl SessionManager { } } + /// Get the a key claiming request for the user/device pairs that we are + /// missing Olm sessions for. + /// + /// Returns None if no key claiming request needs to be sent out. + /// + /// Sessions need to be established between devices so group sessions for a + /// room can be shared with them. + /// + /// This should be called every time a group session needs to be shared as + /// well as between sync calls. After a sync some devices may request room + /// keys without us having a valid Olm session with them, making it + /// impossible to server the room key request, thus it's necessary to check + /// for missing sessions between sync as well. + /// + /// **Note**: Care should be taken that only one such request at a time is + /// in flight, e.g. using a lock. + /// + /// The response of a successful key claiming requests needs to be passed to + /// the `OlmMachine` with the [`receive_keys_claim_response`]. + /// + /// # Arguments + /// + /// `users` - The list of users that we should check if we lack a session + /// with one of their devices. This can be an empty iterator when calling + /// this method between sync requests. + /// + /// [`receive_keys_claim_response`]: #method.receive_keys_claim_response pub async fn get_missing_sessions( &self, users: &mut impl Iterator,