From a7bce18b59fba5d5faa3e0621a7d885cc7c20071 Mon Sep 17 00:00:00 2001
From: Victor Berger <victor.berger@m4x.org>
Date: Wed, 4 Jan 2017 20:00:37 +0100
Subject: [PATCH] Update /register to most recent spec

---
 src/r0/account.rs | 63 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 4 deletions(-)

diff --git a/src/r0/account.rs b/src/r0/account.rs
index fa31316d..72d6b5b7 100644
--- a/src/r0/account.rs
+++ b/src/r0/account.rs
@@ -2,15 +2,55 @@
 
 /// [POST /_matrix/client/r0/register](https://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-register)
 pub mod register {
+    use ruma_identifiers::UserId;
+
     /// This API endpoint's body parameters.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct BodyParams {
+        /// If true, the server binds the email used for authentication
+        /// to the Matrix ID with the ID Server.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub bind_email: Option<bool>,
-        pub password: String,
+        /// The desired password for the account.
+        ///
+        /// Should only be empty for guest accounts.
+        // TODO: the spec says nothing about when it is actually required.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub password: Option<String>,
+        /// local part of the desired Matrix ID.
+        ///
+        /// If omitted, the homeserver MUST generate a Matrix ID local part.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub username: Option<String>,
-        // TODO: `auth` field
+        /// ID of the client device.
+        ///
+        /// If this does not correspond to a known client device, a new device will be created.
+        /// The server will auto-generate a device_id if this is not specified.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub device_id: Option<String>,
+        /// A display name to assign to the newly-created device.
+        ///
+        /// Ignored if `device_id` corresponds to a known device.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub initial_device_display_name: Option<String>,
+        /// Additional authentication information for the user-interactive authentication API.
+        ///
+        /// Note that this information is not used to define how the registered user should be
+        /// authenticated, but is instead used to authenticate the register call itself.
+        /// It should be left empty, or omitted, unless an earlier call returned an response
+        /// with status code 401.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub auth: Option<AuthenticationData>
+    }
+
+    /// Additional authentication information for the user-interactive authentication API.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    pub struct AuthenticationData {
+        /// The login type that the client is attempting to complete.
+        #[serde(rename = "type")]
+        kind: String,
+        /// The value of the session key given by the homeserver.
+        session: Option<String>
     }
 
     /// Details about this API endpoint.
@@ -20,6 +60,9 @@ pub mod register {
     /// This API endpoint's query string parameters.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct QueryParams {
+        /// Kind of account to register
+        ///
+        /// Defaults to `User` if ommited.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub kind: Option<RegistrationKind>,
     }
@@ -27,8 +70,12 @@ pub mod register {
     /// The kind of account being registered.
     #[derive(Copy, Clone, Debug, Deserialize, Serialize)]
     pub enum RegistrationKind {
+        /// A guest account
+        ///
+        /// These accounts may have limited permissions and may not be supported by all servers.
         #[serde(rename="guest")]
         Guest,
+        /// A regular user account
         #[serde(rename="user")]
         User,
     }
@@ -36,10 +83,18 @@ pub mod register {
     /// This API endpoint's response.
     #[derive(Clone, Debug, Deserialize, Serialize)]
     pub struct Response {
+        /// An access token for the account.
+        ///
+        /// This access token can then be used to authorize other requests.
         pub access_token: String,
+        /// The hostname of the homeserver on which the account has been registered.
         pub home_server: String,
-        pub user_id: String,
-        // TODO: `refresh_token` field? (more or less deprecated?)
+        /// The fully-qualified Matrix ID that has been registered.
+        pub user_id: UserId,
+        /// ID of the registered device.
+        ///
+        /// Will be the same as the corresponding parameter in the request, if one was specified.
+        pub device_id: String
     }
 
     impl ::Endpoint for Endpoint {