From d52cbf6817de9f38cddc919e7dbc73c7f880af0a Mon Sep 17 00:00:00 2001 From: ijungleboy Date: Mon, 31 May 2021 15:45:07 +0200 Subject: [PATCH] More docs for https://github.com/oqtane/oqtane.framework/issues/1382 - should not affect any code --- .../Services/Interfaces/IAliasService.cs | 2 +- .../Services/Interfaces/IFileService.cs | 84 +++++++++++++++++++ .../Services/Interfaces/IFolderService.cs | 52 +++++++++++- .../Services/Interfaces/IRoleService.cs | 36 ++++++++ .../Services/Interfaces/ITenantService.cs | 29 ++++++- .../Services/Interfaces/IUserRoleService.cs | 34 +++++++- .../Services/Interfaces/IUserService.cs | 64 ++++++++++++++ 7 files changed, 297 insertions(+), 4 deletions(-) diff --git a/Oqtane.Client/Services/Interfaces/IAliasService.cs b/Oqtane.Client/Services/Interfaces/IAliasService.cs index 89c25605..1ab43fa9 100644 --- a/Oqtane.Client/Services/Interfaces/IAliasService.cs +++ b/Oqtane.Client/Services/Interfaces/IAliasService.cs @@ -6,7 +6,7 @@ using System.Threading.Tasks; namespace Oqtane.Services { /// - /// Retrieve and store information. + /// Service to retrieve and store information. /// public interface IAliasService { diff --git a/Oqtane.Client/Services/Interfaces/IFileService.cs b/Oqtane.Client/Services/Interfaces/IFileService.cs index ba6a88e1..1a756e4a 100644 --- a/Oqtane.Client/Services/Interfaces/IFileService.cs +++ b/Oqtane.Client/Services/Interfaces/IFileService.cs @@ -4,19 +4,103 @@ using System.Threading.Tasks; namespace Oqtane.Services { + /// + /// Service to get / create / upload / download files. + /// public interface IFileService { + /// + /// Get all s in the specified Folder + /// + /// The folder ID + /// Task> GetFilesAsync(int folderId); + + /// + /// Get all s in the specified folder. + /// + /// + /// The folder path relative to where the files are stored. + /// TODO: todoc verify exactly from where the folder path must start + /// + /// Task> GetFilesAsync(string folder); + + /// + /// Get one + /// + /// + /// Task GetFileAsync(int fileId); + + /// + /// Add / store a record. + /// This does not contain the file contents. + /// + /// + /// Task AddFileAsync(File file); + + /// + /// Update a record. + /// Use this for rename a file or change some attributes. + /// This does not contain the file contents. + /// + /// + /// Task UpdateFileAsync(File file); + + /// + /// Delete a + /// + /// + /// Task DeleteFileAsync(int fileId); + + /// + /// Upload a file from a URL to a + /// + /// + /// + /// Task UploadFileAsync(string url, int folderId); + + /// + /// Upload one or more files. + /// + /// Target + /// The files to upload, serialized as a string. + /// A task-identifier, to ensure communication about this upload. + /// Task UploadFilesAsync(int folderId, string[] files, string fileUploadName); + + + /// + /// Upload one or more files. + /// + /// Target + /// TODO: todoc verify exactly from where the folder path must start + /// + /// The files to upload, serialized as a string. + /// A task-identifier, to ensure communication about this upload. + /// Task UploadFilesAsync(string folder, string[] files, string fileUploadName); + + /// + /// Get / download a file (the body). + /// + /// Reference to a + /// The bytes of the file Task DownloadFileAsync(int fileId); + /// + /// Retrieve a list of files from a and + /// + /// Reference to the + /// Path of the folder + /// TODO: todoc verify exactly from where the folder path must start + /// + /// Task> GetFilesAsync(int siteId, string folderPath); } } diff --git a/Oqtane.Client/Services/Interfaces/IFolderService.cs b/Oqtane.Client/Services/Interfaces/IFolderService.cs index 34edb609..a3085f3a 100644 --- a/Oqtane.Client/Services/Interfaces/IFolderService.cs +++ b/Oqtane.Client/Services/Interfaces/IFolderService.cs @@ -1,18 +1,68 @@ -using Oqtane.Models; +using Oqtane.Models; using System.Collections.Generic; using System.Diagnostics.CodeAnalysis; using System.Threading.Tasks; namespace Oqtane.Services { + /// + /// Service to get / create / modify objects. + /// public interface IFolderService { + /// + /// Retrieve root folders of a + /// + /// + /// Task> GetFoldersAsync(int siteId); + + /// + /// Retrieve the information of one + /// + /// + /// Task GetFolderAsync(int folderId); + + /// + /// Create one Folder using a object. + /// + /// + /// Task AddFolderAsync(Folder folder); + + /// + /// Update the information about a + /// Use this to rename the folder etc. + /// + /// + /// Task UpdateFolderAsync(Folder folder); + + /// + /// Update the internal Folder-Order within the list of Folders. + /// + /// Reference to the + /// Reference to a for the security check + /// Reference to the Parent or null - this Folders children will be re-sorted. + /// Task UpdateFolderOrderAsync(int siteId, int folderId, int? parentId); + + /// + /// Delete a + /// + /// Reference to a + /// Task DeleteFolderAsync(int folderId); + + /// + /// Get a of a based on the path. + /// + /// Reference to the + /// Path of the folder + /// TODO: todoc verify exactly from where the folder path must start + /// + /// Task GetFolderAsync(int siteId, [NotNull]string folderPath); } } diff --git a/Oqtane.Client/Services/Interfaces/IRoleService.cs b/Oqtane.Client/Services/Interfaces/IRoleService.cs index 66edc8de..65d91023 100644 --- a/Oqtane.Client/Services/Interfaces/IRoleService.cs +++ b/Oqtane.Client/Services/Interfaces/IRoleService.cs @@ -4,18 +4,54 @@ using System.Threading.Tasks; namespace Oqtane.Services { + /// + /// Service to manage s on a + /// public interface IRoleService { + /// + /// Get all s of this . + /// + /// Will exclude global roles which are for all sites. To get those as well, use the overload + /// + /// ID-reference of a + /// Task> GetRolesAsync(int siteId); + /// + /// Get roles of the and optionally include global Roles. + /// + /// ID-reference to a + /// True if it should also include global roles. False will return the same data as just calling + /// Task> GetRolesAsync(int siteId, bool includeGlobalRoles); + /// + /// Get one specific + /// + /// ID-reference of a + /// Task GetRoleAsync(int roleId); + /// + /// Add / save a new to the database. + /// + /// + /// Task AddRoleAsync(Role role); + /// + /// Update a in the database. + /// + /// + /// Task UpdateRoleAsync(Role role); + /// + /// Delete / mark-as-deleted a in the database. + /// + /// ID-reference of a + /// Task DeleteRoleAsync(int roleId); } } diff --git a/Oqtane.Client/Services/Interfaces/ITenantService.cs b/Oqtane.Client/Services/Interfaces/ITenantService.cs index 24bdd79b..12738f58 100644 --- a/Oqtane.Client/Services/Interfaces/ITenantService.cs +++ b/Oqtane.Client/Services/Interfaces/ITenantService.cs @@ -1,19 +1,46 @@ -using Oqtane.Models; +using Oqtane.Models; using System.Collections.Generic; using System.Threading.Tasks; namespace Oqtane.Services { + /// + /// Service to manage s on the Oqtane installation. + /// public interface ITenantService { + /// + /// Get all s + /// + /// Task> GetTenantsAsync(); + /// + /// Get one specific + /// + /// ID-reference of the + /// Task GetTenantAsync(int tenantId); + /// + /// Add / save another to the database + /// + /// A object containing the configuration + /// Task AddTenantAsync(Tenant tenant); + /// + /// Update the information in the database. + /// + /// + /// Task UpdateTenantAsync(Tenant tenant); + /// + /// Delete / remove a + /// + /// + /// Task DeleteTenantAsync(int tenantId); } } diff --git a/Oqtane.Client/Services/Interfaces/IUserRoleService.cs b/Oqtane.Client/Services/Interfaces/IUserRoleService.cs index 25cb9ab4..b0897554 100644 --- a/Oqtane.Client/Services/Interfaces/IUserRoleService.cs +++ b/Oqtane.Client/Services/Interfaces/IUserRoleService.cs @@ -1,15 +1,47 @@ -using Oqtane.Models; +using Oqtane.Models; using System.Collections.Generic; using System.Threading.Tasks; namespace Oqtane.Services { + /// + /// Manage s assigned to a specific + /// public interface IUserRoleService { + /// + /// Get all s on a + /// + /// ID-reference to a + /// Task> GetUserRolesAsync(int siteId); + + /// + /// Get one specific + /// + /// ID-reference to a + /// Task GetUserRoleAsync(int userRoleId); + + /// + /// Save a new + /// + /// + /// Task AddUserRoleAsync(UserRole userRole); + + /// + /// Update a in the database + /// + /// + /// Task UpdateUserRoleAsync(UserRole userRole); + + /// + /// Delete a in the database + /// + /// + /// Task DeleteUserRoleAsync(int userRoleId); } } diff --git a/Oqtane.Client/Services/Interfaces/IUserService.cs b/Oqtane.Client/Services/Interfaces/IUserService.cs index b47b3481..08289bea 100644 --- a/Oqtane.Client/Services/Interfaces/IUserService.cs +++ b/Oqtane.Client/Services/Interfaces/IUserService.cs @@ -3,26 +3,90 @@ using System.Threading.Tasks; namespace Oqtane.Services { + /// + /// Manage (get / update) user information + /// public interface IUserService { + /// + /// Get a of a specific site + /// + /// ID of a + /// ID of a + /// Task GetUserAsync(int userId, int siteId); + + /// + /// Get a of a specific site + /// + /// Username / login of a + /// ID of a + /// Task GetUserAsync(string username, int siteId); + /// + /// Save a user to the Database. + /// The object contains all the information incl. what it belongs to. + /// + /// + /// Task AddUserAsync(User user); + /// + /// Update an existing user in the database. + /// + /// + /// Task UpdateUserAsync(User user); + /// + /// Delete / remove a user in the database + /// + /// ID-reference to the + /// ID-reference to the + /// Task DeleteUserAsync(int userId, int siteId); + /// + /// Will login the specified . + /// + /// Note that this will probably not be a real User, but a user object where the `Username` and `Password` have been filled. + /// + /// A object which should have at least the and set. + /// Determines if the login should be stored in the cookie. + /// Determines if the login should be persisted in the cookie for a long time. + /// Task LoginUserAsync(User user, bool setCookie, bool isPersistent); + /// + /// Logout a + /// + /// + /// Task LogoutUserAsync(User user); + /// + /// Update e-mail verification status of a user. + /// + /// The we're verifying + /// A Hash value in the URL which verifies this user got the e-mail (containing this token) + /// Task VerifyEmailAsync(User user, string token); + /// + /// Trigger a forgot-password e-mail for this . + /// + /// + /// Task ForgotPasswordAsync(User user); + /// + /// Reset the password of this + /// + /// + /// + /// Task ResetPasswordAsync(User user, string token); } }