rust-sdk: Document the cross signing bootstrap method.

This commit is contained in:
Damir Jelić 2020-11-05 14:33:45 +01:00
parent b27f1b0e34
commit 11fcf5c42f

View file

@ -1832,7 +1832,58 @@ impl Client {
}))
}
/// TODO
/// Create and upload a new cross signing identity.
///
/// # Arguments
///
/// * `auth_data` - This request requires user interactive auth, the first
/// request needs to set this to `None` and will always fail with an
/// `UiaaResponse`. The response will contain information for the
/// interactive auth and the same request needs to be made but this time
/// with some `auth_data` provided.
///
/// # Examples
/// ```no_run
/// # use std::{convert::TryFrom, collections::BTreeMap};
/// # use matrix_sdk::{Client, identifiers::UserId};
/// # use matrix_sdk::api::r0::uiaa::AuthData;
/// # use url::Url;
/// # use futures::executor::block_on;
/// # use serde_json::json;
/// # let user_id = UserId::try_from("@alice:example.org").unwrap();
/// # let homeserver = Url::parse("http://example.com").unwrap();
/// # let client = Client::new(homeserver).unwrap();
/// # block_on(async {
///
/// fn auth_data<'a>(user: &UserId, password: &str, session: Option<&'a str>) -> AuthData<'a> {
/// let mut auth_parameters = BTreeMap::new();
/// let identifier = json!({
/// "type": "m.id.user",
/// "user": user,
/// });
/// auth_parameters.insert("identifier".to_owned(), identifier);
/// auth_parameters.insert("password".to_owned(), password.to_owned().into());
/// // This is needed because of https://github.com/matrix-org/synapse/issues/5665
/// auth_parameters.insert("user".to_owned(), user.as_str().into());
/// AuthData::DirectRequest {
/// kind: "m.login.password",
/// auth_parameters,
/// session,
/// }
/// }
///
/// if let Err(e) = client.bootstrap_cross_signing(None).await {
/// if let Some(response) = e.uiaa_response() {
/// let auth_data = auth_data(&user_id, "wordpass", response.session.as_deref());
/// client
/// .bootstrap_cross_signing(Some(auth_data))
/// .await
/// .expect("Couldn't bootstrap cross signing")
/// } else {
/// panic!("Error durign cross signing bootstrap {:#?}", e);
/// }
/// }
/// # })
#[cfg(feature = "encryption")]
#[cfg_attr(feature = "docs", doc(cfg(encryption)))]
pub async fn bootstrap_cross_signing(&self, auth_data: Option<AuthData<'_>>) -> Result<()> {