Add message inbox and support for messages read and attachments

Author: Suiram1701

API.Test/MessagesTests.cs

@@ -15,7 +15,7 @@ public void GetUnreadMessages()
     {
         Client.LoginAsync(s_Server, s_LoginName, s_UserName, s_Password).Wait();
 
-        Task<int> messages = Client.GetUnreadMessagesCountAsync();
+        Task<int> messages = Client.MessageClient.GetUnreadMessagesCountAsync();
         messages.Wait();
         if (messages.Result == 0)
             Assert.Pass();
@@ -28,11 +28,37 @@ public void GetMessagePermissions()
     {
         Client.LoginAsync(s_Server, s_LoginName, s_UserName, s_Password).Wait();
 
-        Task<MessagePermissions> permissions = Client.GetMessagePermissionsAsync();
+        Task<MessagePermissions> permissions = Client.MessageClient.GetMessagePermissionsAsync();
         permissions.Wait();
         if (permissions.Result != null)
             Assert.Pass();
         else
             Assert.Fail();
     }
+
+    [Test]
+    public void GetMessageInbox()
+    {
+        Client.LoginAsync(s_Server, s_LoginName, s_UserName, s_Password).Wait();
+
+        Task<MessagePreview[]> messages = Client.MessageClient.GetMessageInboxAsync();
+        messages.Wait();
+        if (messages.Result.Length > 0)
+            Assert.Pass();
+        else
+            Assert.Fail();
+    }
+
+    [Test]
+    public void GetFullMessage()
+    {
+        Client.LoginAsync(s_Server, s_LoginName, s_UserName, s_Password).Wait();
+
+        Task<MessagePreview[]> messages = Client.MessageClient.GetMessageInboxAsync();
+        messages.Wait();
+        Task<Message> msg = messages.Result.First(msg => msg.Subject == "Test").GetFullMessageAsync(Client);
+        msg.Wait();
+        _ = msg.Result;
+        return;
+    }
 }

WebUntisAPI.Client/Converter/APIDateTimeJsonConverter.cs

@@ -0,0 +1,26 @@
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Threading.Tasks;
+
+namespace WebUntisAPI.Client.Converter
+{
+    internal class APIDateTimeJsonConverter : JsonConverter<DateTime>
+    {
+        public override DateTime ReadJson(JsonReader reader, Type objectType, DateTime existingValue, bool hasExistingValue, JsonSerializer serializer)
+        {
+            JToken token = JToken.Load(reader);
+            return token.Value<DateTime>();
+        }
+
+        public override void WriteJson(JsonWriter writer, DateTime value, JsonSerializer serializer)
+        {
+            string dateTimeString = value.ToString("yyyy-MM-dd") + "T" + value.ToString("HH:mm:ss");
+            writer.WriteValue(dateTimeString);
+        }
+    }
+}

WebUntisAPI.Client/MessageClient.cs

@@ -0,0 +1,77 @@
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Net.Http;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using WebUntisAPI.Client.Models;
+
+namespace WebUntisAPI.Client
+{
+    /// <summary>
+    /// A client with them you could load and send untis messages
+    /// </summary>
+    /// <remarks>
+    /// Under no circumstances should 10 req. per sec., more than 1800req. per hr (but in no case more than 3600 req. per hr). If the specifications are exceeded, access to WebUntis could permanently blocked by the WebUntis API.
+    /// </remarks>
+    public class MessageClient
+    {
+        private readonly WebUntisClient _client;
+
+        /// <summary>
+        /// Create a new message client to access the untis messages
+        /// </summary>
+        /// <param name="client">The client from which account they want to receive the messages</param>
+        public MessageClient(WebUntisClient client)
+        {
+            _client = client;
+        }
+
+        /// <summary>
+        /// Get the count of unread messages
+        /// </summary>
+        /// <param name="ct">Cancellation token</param>
+        /// <returns>The count of unread messages</returns>
+        /// <exception cref="ObjectDisposedException">Thrown when the instance was disposed</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown when you're logged in</exception>
+        /// <exception cref="HttpRequestException">Thrown when an error happened while the http request</exception>
+        public async Task<int> GetUnreadMessagesCountAsync(CancellationToken ct = default)
+        {
+            string responseString = await _client.MakeAPIGetRequestAsync("/WebUntis/api/rest/view/v1/messages/status", ct);
+            return JObject.Parse(responseString).Value<int>("unreadMessagesCount");
+        }
+
+        /// <summary>
+        /// Get the permissions you have to send messages
+        /// </summary>
+        /// <param name="ct">Cancllation token</param>
+        /// <returns></returns>
+        /// <exception cref="ObjectDisposedException">Thrown when the instance was disposed</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown when you're logged in</exception>
+        /// <exception cref="HttpRequestException">Thrown when an error happened while the http request</exception>
+        public async Task<MessagePermissions> GetMessagePermissionsAsync(CancellationToken ct = default)
+        {
+            string responseString = await _client.MakeAPIGetRequestAsync("/WebUntis/api/rest/view/v1/messages/permissions", ct);
+            return JsonConvert.DeserializeObject<MessagePermissions>(responseString);
+        }
+
+        /// <summary>
+        /// Get the you message inbox
+        /// </summary>
+        /// <param name="ct">Cancellation token</param>
+        /// <returns>The message previews</returns>
+        /// <exception cref="ObjectDisposedException">Thrown when the instance was disposed</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown when you're logged in</exception>
+        /// <exception cref="HttpRequestException">Thrown when an error happened while the http request</exception>
+        public async Task<MessagePreview[]> GetMessageInboxAsync(CancellationToken ct = default)
+        {
+            string responseString = await _client.MakeAPIGetRequestAsync("/WebUntis/api/rest/view/v1/messages", ct);
+
+            JArray jsonMsg = JObject.Parse(responseString).Value<JArray>("incomingMessages");
+            return new JsonSerializer().Deserialize<List<MessagePreview>>(jsonMsg.CreateReader()).ToArray();
+        }
+    }
+}

WebUntisAPI.Client/Models/Attachment.cs

@@ -0,0 +1,92 @@
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.IO;
+using System.Linq;
+using System.Net;
+using System.Net.Http;
+using System.Net.Http.Headers;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace WebUntisAPI.Client.Models
+{
+    /// <summary>
+    /// An attachment from a message
+    /// </summary>
+    [DebuggerDisplay("{Name, nq}")]
+    public struct Attachment
+    {
+        /// <summary>
+        /// The file name of the attachment
+        /// </summary>
+        [JsonProperty("name")]
+        public string Name { get; set; }
+
+        /// <summary>
+        /// The attachment id
+        /// </summary>
+        [JsonProperty("id")]
+        private readonly string _id;
+
+        /// <summary>
+        /// Get the content of the attachment as stream
+        /// </summary>
+        /// <param name="client">The client with them you got this instane (It doesn't have to be the same client but the same account)</param>
+        /// <param name="timeout">The time after that the download of the content will cancelled (In miliseconds)</param>
+        /// <param name="ct">Cancellation token</param>
+        /// <returns>The attachment as stream</returns>
+        /// <exception cref="ObjectDisposedException">Thrown when the instance was disposed</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown when you're logged in</exception>
+        /// <exception cref="HttpRequestException">Thrown when an error happened while the http request</exception>
+        public async Task<MemoryStream> DownloadContentAsStreamAsync(WebUntisClient client, int timeout = 2000, CancellationToken ct = default)
+        {
+            string storageResponseString = await client.MakeAPIGetRequestAsync($"/WebUntis/api/rest/view/v1/messages/{_id}/attachmentstorageurl", ct);
+
+            JObject data = JObject.Parse(storageResponseString);
+            JArray headerArray = data.Value<JArray>("additionalHeaders");
+            
+            HttpRequestMessage request = new HttpRequestMessage()
+            {
+                Method = HttpMethod.Get,
+                RequestUri = new Uri(data.Value<string>("downloadUrl"))
+            };
+
+            // Auth headers
+            foreach (JObject jsonHeader in headerArray.Cast<JObject>())
+                request.Headers.Add(jsonHeader.Value<string>("key"), jsonHeader.Value<string>("value"));
+
+            // Date header
+            string dateStr = DateTime.Now.ToString("yyyyMMdd");
+            string timeStr = DateTime.Now.ToString("HHmmss");
+            request.Headers.Add("x-amz-date", $"{dateStr}T{timeStr}Z");
+
+            using (HttpClient downloadClient = new HttpClient())
+            {
+                downloadClient.Timeout = TimeSpan.FromMilliseconds(timeout);
+                HttpResponseMessage response = await downloadClient.SendAsync(request, ct);
+
+                // Check cancellation token
+                if (ct.IsCancellationRequested)
+                    return default;
+
+                // Verify response
+                if (response.StatusCode != HttpStatusCode.OK)
+                    throw new HttpRequestException($"There was an error while the http request (Code: {response.StatusCode}).");
+
+                if (response.StatusCode == HttpStatusCode.Unauthorized || response.StatusCode == HttpStatusCode.Forbidden)
+                {
+
+                    string detail = Regex.Match(await response.Content.ReadAsStringAsync(), @"<Message>([a-zA-z0-9\s]+)</Message>").Groups[1].Value;     // Get the error message
+                    throw new UnauthorizedAccessException($"Invalid authentication. Detail: {detail}");
+                }
+
+                return (MemoryStream)await response.Content.ReadAsStreamAsync();
+            }
+        }
+    }
+}

WebUntisAPI.Client/Models/Message.cs

@@ -0,0 +1,105 @@
+using Newtonsoft.Json;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using WebUntisAPI.Client.Converter;
+
+namespace WebUntisAPI.Client.Models
+{
+    /// <summary>
+    /// The full message
+    /// </summary>
+    public class Message
+    {
+        /// <summary>
+        /// The id of the message
+        /// </summary>
+        [JsonProperty("id")]
+        public int Id { get; set; }
+
+        /// <summary>
+        /// The subject of the message
+        /// </summary>
+        [JsonProperty("subject")]
+        public string Subject { get; set; }
+
+        /// <summary>
+        /// The full content of the message
+        /// </summary>
+        [JsonProperty("content")]
+        public string Content { get; set; }
+
+        /// <summary>
+        /// The sender of the message
+        /// </summary>
+        [JsonProperty("sender")]
+        public MessageProfile Sender { get; set; }
+
+        /// <summary>
+        /// All the recipients for a message
+        /// </summary>
+        /// <remarks>
+        /// When its <see langword="null"/> is the recipient the current user
+        /// </remarks>
+        [JsonProperty("recipients")]
+        public List<MessageProfile> Recipients { get; set; } = null;
+
+        /// <summary>
+        /// The send time of the message
+        /// </summary>
+        [JsonProperty("sentDateTime")]
+        [JsonConverter(typeof(APIDateTimeJsonConverter))]
+        public DateTime SentTime { get; set; }
+
+        /// <summary>
+        /// Is allowed to delete the message
+        /// </summary>
+        [JsonProperty("allowMessageDeletion")]
+        public bool AllowMessageDeletion { get; set; }
+
+        /// <summary>
+        /// Is the message revoked
+        /// </summary>
+        [JsonProperty("isRevoked")]
+        public bool IsRevoked { get; set; }
+
+        /// <summary>
+        /// The file attachments of the message
+        /// </summary>
+        [JsonProperty("storageAttachments")]
+        public List<Attachment> Attachments { get; set; }
+
+        /// <summary>
+        /// Is the message a reply
+        /// </summary>
+        [JsonProperty("isReply")]
+        public bool IsReply { get; set; } = false;
+
+        /// <summary>
+        /// Can you reply the message
+        /// </summary>
+        [JsonProperty("isReplyAllowed")]
+        public bool IsReplyAllowed { get; set; } = true;
+        
+        /// <summary>
+        /// Is this a report message
+        /// </summary>
+        [JsonProperty("isReportMessage")]
+        public bool IsReportMessage { get; set; } = false;
+
+        /// <summary>
+        /// Is a reply for this forbidden
+        /// </summary>
+        [JsonProperty("isReplyForbidden")]
+        public bool IsReplyForbidden { get; set; } = false;
+
+        /// <summary>
+        /// The history of all replies
+        /// </summary>
+        [JsonProperty("replyHistory")]
+        public List<Message> ReplyHistory { get; set; } = new List<Message>();
+    }
+}