Add staff recipients search and filters

Author: Suiram1701

API.Test/MessagesTests.cs

@@ -88,6 +88,20 @@ public void GetReceptionPeople()
             Assert.Fail();
     }
 
+    [Test]
+    public void GetStaffFilters()
+    {
+        Client.LoginAsync(s_Server, s_LoginName, s_UserName, s_Password).Wait();
+
+        Task<Dictionary<string, FilterItem[]>> filters = Client.GetStaffSearchFiltersAsync();
+        filters.Wait();
+
+        if (filters.Result.Count > 0)
+            Assert.Pass();
+        else
+            Assert.Fail();
+    }
+
     [Test]
     public void GetDrafts()
     {

WebUntisAPI.Client/Models/Messages/FilterItem.cs

@@ -0,0 +1,27 @@
+using Newtonsoft.Json;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace WebUntisAPI.Client.Models.Messages
+{
+    /// <summary>
+    /// A filter item that can applied to a staff search
+    /// </summary>
+    public struct FilterItem
+    {
+        /// <summary>
+        /// The id of this filter item
+        /// </summary>
+        [JsonProperty("referenceId")]
+        public int ReferenceId { get; set; }
+
+        /// <summary>
+        /// The displayed name of this filter item
+        /// </summary>
+        [JsonProperty("name")]
+        public string Name { get; set; }
+    }
+}

WebUntisAPI.Client/WebUntisClient.Messages.cs

@@ -45,8 +45,11 @@ public async Task<MessagePermissions> GetMessagePermissionsAsync(CancellationTok
         }
 
         /// <summary>
-        /// Get all available reception people
+        /// Get all available reception teachers people
         /// </summary>
+        /// <remarks>
+        /// Use this method only when <see cref="MessagePermissions.RecipientOptions"/> contains "TEACHER"
+        /// </remarks>
         /// <param name="ct">Cancellation token</param>
         /// <returns>The people (<see cref="KeyValuePair{TKey, TValue}.Key"/> is the type of people that are contained in <see cref="KeyValuePair{TKey, TValue}.Value"/>)</returns>
         /// <exception cref="ObjectDisposedException">Thrown when the instance was disposed</exception>
@@ -64,6 +67,111 @@ public async Task<Dictionary<string, MessagePerson[]>> GetMessagePeopleAsync(Can
             return personTypes;
         }
 
+        /// <summary>
+        /// Get all possible filters for the staff
+        /// </summary>
+        /// <remarks>
+        /// Use this method only when <see cref="MessagePermissions.RecipientOptions"/> contains "STAFF"
+        /// </remarks>
+        /// <param name="ct">Cancellation token</param>
+        /// <returns>The filters (the <see cref="KeyValuePair{TKey, TValue}.Key"/> is the type of the filter and <see cref="KeyValuePair{TKey, TValue}.Value"/> are the available filters for that type)</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<Dictionary<string, FilterItem[]>> GetStaffSearchFiltersAsync(CancellationToken ct = default)
+        {
+            string responseString = await MakeAPIGetRequestAsync("/WebUntis/api/rest/view/v2/messages/recipients/STAFF/filter", ct);
+
+            JObject obj = JObject.Parse(responseString);
+            JArray types = obj["filters"].Value<JArray>();
+
+            Dictionary<string, FilterItem[]> filters = new Dictionary<string, FilterItem[]>();
+            foreach (JObject filter in types.Cast<JObject>())
+                filters.Add(filter["type"].ToObject<string>(), filter["items"].ToObject<List<FilterItem>>().ToArray());
+
+            return filters;
+        }
+
+        /// <summary>
+        /// Get all staff recipients for the applied filters
+        /// </summary>
+        /// <remarks>
+        /// Use this method only when <see cref="MessagePermissions.RecipientOptions"/> contains "STAFF"
+        /// </remarks>
+        /// <param name="searchText">The search text</param>
+        /// <param name="filters">The applied filters (use the data from <see cref="GetStaffSearchFiltersAsync(CancellationToken)"/>)</param>
+        /// <param name="ct">Cancellation token</param>
+        /// <returns>The recipients</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<MessagePerson[]> GetStaffFilterSearchResultAsync(string searchText, Dictionary<string, FilterItem[]> filters, CancellationToken ct = default)
+        {
+            // Check for disposing
+            if (_disposedValue)
+                throw new ObjectDisposedException(GetType().FullName);
+
+            // Check if you logged in
+            if (!LoggedIn)
+                throw new UnauthorizedAccessException("You're not logged in");
+
+            // Write request
+            StringWriter sw = new StringWriter();
+            using (JsonWriter writer = new JsonTextWriter(sw))
+            {
+                writer.WriteStartObject();
+
+                writer.WritePropertyName("filters");
+                writer.WriteStartArray();
+                foreach (KeyValuePair<string, FilterItem[]> filter in filters)
+                {
+                    writer.WriteStartObject();
+
+                    writer.WritePropertyName("type");
+                    writer.WriteValue(filter.Key);
+
+                    writer.WritePropertyName("items");
+                    writer.WriteRawValue(JsonConvert.SerializeObject(filter.Value));
+
+                    writer.WriteEndObject();
+                }
+
+                writer.WriteEndArray();
+
+                writer.WritePropertyName("searchText");
+                writer.WriteValue(searchText);
+
+                writer.WriteEndObject();
+            }
+
+            HttpRequestMessage request = new HttpRequestMessage()
+            {
+                Method = HttpMethod.Post,
+                RequestUri = new Uri(ServerUrl + $"/WebUntis/api/rest/view/v2/messages/recipients/STAFF/filter"),
+                Content = new StringContent(sw.ToString())
+            };
+            request.Headers.Add("JSESSIONID", _sessionId);
+            request.Headers.Add("schoolname", _schoolName);
+            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _bearerToken);
+
+            HttpResponseMessage response = await _client.SendAsync(request, ct);
+
+            // Verify response
+            if (response.StatusCode == HttpStatusCode.Unauthorized || response.StatusCode == HttpStatusCode.Forbidden)
+            {
+                _ = LogoutAsync();
+                throw new UnauthorizedAccessException("You're not logged in");
+            }
+
+            if (response.StatusCode != HttpStatusCode.OK)
+                throw new HttpRequestException($"There was an error while the http request (Code: {response.StatusCode}).");
+
+            string responseString = await response.Content.ReadAsStringAsync();
+            
+            JObject obj = JObject.Parse(responseString);
+            return obj["users"].Value<List<MessagePerson>>().ToArray();
+        }
+
         /// <summary>
         /// Get the your message inbox
         /// </summary>

WebUntisAPI.Client/WebUntisclient.Profile.cs

@@ -36,13 +36,13 @@ public partial class WebUntisClient
         ///     The rendered image will be rendered to 300px * 300px and a font size of 124
         ///     </para>
         /// </remarks>
-        /// <param name="person"></param>
-        /// <param name="fontName"></param>
-        /// <param name="ct"></param>
+        /// <param name="person">The person for the image</param>
+        /// <param name="fontName">The font size to render</param>
+        /// <param name="ct">Cancellation token</param>
         /// <returns></returns>
-        /// <exception cref="ObjectDisposedException"></exception>
-        /// <exception cref="UnauthorizedAccessException"></exception>
-        /// <exception cref="HttpRequestException"></exception>
+        /// <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>
 #if NET47 || NET481
         public async Task<Image> GetMessagePersonProfileImageAsync(MessagePerson person, string fontName = "Segoe UI", CancellationToken ct = default)
 #elif NET6_0_OR_GREATER
@@ -172,5 +172,7 @@ public async Task<Image> GetMessagePersonProfileImageAsync(MessagePerson person,
             return image;
 #endif
         }
+
+
     }
 }