From 2f964dfe995d6e2bdcaefb544b179fe345adb321 Mon Sep 17 00:00:00 2001 From: "H. Utku Maden" Date: Sun, 25 Aug 2024 20:29:47 +0300 Subject: [PATCH] Documentation pass. --- ReMime/ContentResolvers/MagicValue.cs | 9 ++++ ReMime/IMediaContentResolver.cs | 3 ++ ReMime/IMediaTypeResolver.cs | 3 ++ ReMime/MediaTypeResolver.cs | 65 ++++++++++++++++++++++- ReMime/MediaTypeResult.cs | 3 ++ ReMime/Platform/UnixMediaTypeResolver.cs | 3 ++ ReMime/Platform/Win32MediaTypeResolver.cs | 3 ++ 7 files changed, 88 insertions(+), 1 deletion(-) diff --git a/ReMime/ContentResolvers/MagicValue.cs b/ReMime/ContentResolvers/MagicValue.cs index f18ecfb..bfe9f47 100644 --- a/ReMime/ContentResolvers/MagicValue.cs +++ b/ReMime/ContentResolvers/MagicValue.cs @@ -3,6 +3,10 @@ using System.Text; namespace ReMime.ContentResolvers { + /// + /// A magic value to identify file types. + /// + /// The byte arary that makes up the magic value. public record struct MagicValue(byte[] Value) { public MagicValue(int value) : this(BitConverter.GetBytes(value)) { } @@ -11,6 +15,11 @@ namespace ReMime.ContentResolvers : this((encoding ?? Encoding.ASCII).GetBytes(value)) { } public MagicValue(ReadOnlySpan bytes) : this(bytes.ToArray()) { } + /// + /// Check if matches this magic value. + /// + /// + /// public bool Matches(ReadOnlySpan haystack) { for (int i = 0; i < haystack.Length && i < Value.Length; i++) diff --git a/ReMime/IMediaContentResolver.cs b/ReMime/IMediaContentResolver.cs index 927ce2b..3ee982a 100644 --- a/ReMime/IMediaContentResolver.cs +++ b/ReMime/IMediaContentResolver.cs @@ -4,6 +4,9 @@ using System.IO; namespace ReMime { + /// + /// Interface for all media type resolvers that inspect content. + /// public interface IMediaContentResolver : IMediaTypeResolver { /// diff --git a/ReMime/IMediaTypeResolver.cs b/ReMime/IMediaTypeResolver.cs index 6942739..fcfa2a8 100644 --- a/ReMime/IMediaTypeResolver.cs +++ b/ReMime/IMediaTypeResolver.cs @@ -3,6 +3,9 @@ using System.Collections.Generic; namespace ReMime { + /// + /// Interface for all media type resolvers. + /// public interface IMediaTypeResolver { /// diff --git a/ReMime/MediaTypeResolver.cs b/ReMime/MediaTypeResolver.cs index 1b2a208..3c4d907 100644 --- a/ReMime/MediaTypeResolver.cs +++ b/ReMime/MediaTypeResolver.cs @@ -8,13 +8,22 @@ using ReMime.Platform; namespace ReMime { + /// + /// Resolve media types from file names and file contents. + /// public static class MediaTypeResolver { private static readonly SortedList s_resolvers = new SortedList(); private static IReadOnlyList? s_mediaTypes = null; + /// + /// Enumeration of currently available media type resolvers. + /// public static IEnumerable Resolvers => s_resolvers.Values; + /// + /// Enumeration of detectable media types. + /// public static IEnumerable KnownTypes { get @@ -58,11 +67,23 @@ namespace ReMime } } + /// + /// Add a media type resolver. + /// + /// The resolver instance to add. + /// The resolver priority. Less is more prescedent. public static void AddResolver(IMediaTypeResolver resolver, int priority = 9999) { s_resolvers.Add(priority, resolver); } + /// + /// Try to resolve the media type from a path. + /// + /// The path string. + /// The result media type. + /// True if there was a matching media type. + /// Issues with string. See . public static bool TryResolve(ReadOnlySpan path, out MediaType mediaType) { path = Path.GetFileName(path); @@ -98,11 +119,18 @@ namespace ReMime return false; } + /// + /// Try to resolve the media type from a stream. + /// + /// The stream to inspect. + /// The result media type. + /// True if the type was resolved. + /// The is unseekable. public static bool TryResolve(Stream stream, out MediaType mediaType) { if (!stream.CanSeek) { - throw new Exception("This stream is not seekable, cannot resolve unseekable streams."); + throw new ArgumentException("This stream is not seekable, cannot resolve unseekable streams.", nameof(stream)); } foreach (IMediaTypeResolver resolver in Resolvers) @@ -123,6 +151,12 @@ namespace ReMime return false; } + /// + /// Try to resolve the media type from a span. + /// + /// A span of bytes from the start of the media. + /// The result media type. + /// True if the type was resolved. public static bool TryResolve(ReadOnlySpan bytes, out MediaType mediaType) { foreach (IMediaTypeResolver resolver in Resolvers) @@ -142,6 +176,17 @@ namespace ReMime return false; } + /// + /// Try to resolve the media type. + /// + /// The path string. + /// A span of bytes from the start of the media. + /// The result media type. + /// if none matched. + /// + /// The is unseekable, or issues with string. + /// See + /// public static MediaTypeResult TryResolve(ReadOnlySpan path, ReadOnlySpan bytes, out MediaType mediaType) { if (TryResolve(bytes, out mediaType)) @@ -163,6 +208,17 @@ namespace ReMime } } + /// + /// Try to resolve the media type. + /// + /// The path string. + /// The stream to inspect. + /// The result media type. + /// if none matched. + /// + /// The is unseekable, or issues with string. + /// See + /// public static MediaTypeResult TryResolve(ReadOnlySpan path, Stream stream, out MediaType mediaType) { if (TryResolve(stream, out mediaType)) @@ -184,6 +240,13 @@ namespace ReMime } } + /// + /// Try to resolve the media type. + /// + /// The FileInfo object to the file. + /// The result media type. + /// True to open the file and inspect the contents as well. + /// if none matched. public static MediaTypeResult TryResolve(FileInfo fileInfo, out MediaType mediaType, bool open = true) { if (open) diff --git a/ReMime/MediaTypeResult.cs b/ReMime/MediaTypeResult.cs index 839c41a..8e6e0fc 100644 --- a/ReMime/MediaTypeResult.cs +++ b/ReMime/MediaTypeResult.cs @@ -2,6 +2,9 @@ using System; namespace ReMime { + /// + /// The result of a combined media type query. + /// [Flags] public enum MediaTypeResult { diff --git a/ReMime/Platform/UnixMediaTypeResolver.cs b/ReMime/Platform/UnixMediaTypeResolver.cs index 9b8c8f9..d50f7fb 100644 --- a/ReMime/Platform/UnixMediaTypeResolver.cs +++ b/ReMime/Platform/UnixMediaTypeResolver.cs @@ -5,6 +5,9 @@ using System.IO; namespace ReMime.Platform { + /// + /// Media type resolver for *nix systems that have a "/etc/mime.types" file. + /// public class UnixMediaTypeResolver : IMediaTypeResolver { private readonly Dictionary _extensionsMap = new Dictionary(); diff --git a/ReMime/Platform/Win32MediaTypeResolver.cs b/ReMime/Platform/Win32MediaTypeResolver.cs index adf2ad6..9cd0bfb 100644 --- a/ReMime/Platform/Win32MediaTypeResolver.cs +++ b/ReMime/Platform/Win32MediaTypeResolver.cs @@ -5,6 +5,9 @@ using Microsoft.Win32; namespace ReMime.Platform { + /// + /// Media type resolver for Windows systems. + /// public class Win32MediaTypeResolver : IMediaTypeResolver { private readonly Dictionary _extensionsMap = new Dictionary();