piwigodotnet/PiwigoDotnet/Piwigo.Client/IImageApi.cs

using Piwigo.Client.Contract;

namespace Piwigo.Client;

public interface IImageApi
{
    /// <summary>
    ///     Adds an image to piwigo after all parts have been uploaded.
    /// </summary>
    /// <param name="imageUpload">The metadata of the uploaded image</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>Information about the uploaded image</returns>
    /// <remarks>Ensure that you called <see cref="AddChunkAsync" /> for every chunk of the image.</remarks>
    Task<ImageUploaded> AddAsync(ImageUpload imageUpload, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Updates an image to piwigo after all parts have been uploaded.
    /// </summary>
    /// <param name="imageId">The image id to update</param>
    /// <param name="imageUpload">The metadata of the uploaded image</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>Information about the uploaded image</returns>
    /// <remarks>Ensure that you called <see cref="AddChunkAsync" /> for every chunk of the image.</remarks>
    Task<ImageUploaded> UpdateAsync(int imageId, ImageUpload imageUpload, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Adds a comment to the given image.
    /// </summary>
    /// <param name="imageId">The id of the image</param>
    /// <param name="author">The author</param>
    /// <param name="content">The content</param>
    /// <param name="key">
    ///     The key to post: The key can read from <see cref="GetInfoAsync" /> and <see cref="CommentPost.Key" />
    /// </param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>The id of the new comment</returns>
    Task<int> AddCommentAsync(int imageId, string? author, string content, string key, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Adds a chunk of an image to piwigo.
    ///     This enables uploading of large images using multiple chunks of data.
    /// </summary>
    /// <param name="data">The chunk to upload</param>
    /// <param name="originalSum">The original image checksum</param>
    /// <param name="position">The chunk position</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    Task AddChunkAsync(byte[] data, string originalSum, int position, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Checks if piwigo is ready to get images uploaded.
    /// </summary>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>true if ready; otherwise false</returns>
    Task<bool> ReadyForUploadAsync(CancellationToken cancellationToken = default);

    /// <summary>
    ///     Gets detailed information about the image.
    /// </summary>
    /// <param name="imageId">The image id to read</param>
    /// <param name="commentsPage">The requested comments page</param>
    /// <param name="commentsPerPage">Number of comments per page</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>The metadata of a given image id</returns>
    Task<Image> GetInfoAsync(int imageId, int? commentsPage, int? commentsPerPage, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Gets a list of images for a given album.
    /// </summary>
    /// <param name="albumId">The album id</param>
    /// <param name="recursive">true to get images from sub-albums</param>
    /// <param name="page">Information about the paging</param>
    /// <param name="filter">Filter criteria applied to the returned images</param>
    /// <param name="order">How the list should be sorted</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>a paged list of the images of a given album</returns>
    Task<PagedImages> GetImages(int albumId, bool recursive, PagingInfo page, ImageFilter filter, ImageOrder order = ImageOrder.Name,
        CancellationToken cancellationToken = default);

    /*
checkFiles
delete
deleteOrphans
emptyLounge
exist
-> formats
        delete
        searchImage
rate
search
setInfo
setMd5sum
setPrivacyLevel
setRank
syncMetadata
upload
uploadAsync
uploadCompleted
*/
}