refuel.mixedup.dev/docs/ReMime.md

ReMime

ReMime is a simple IANA media types detector written in C#. It has it's own detectors that can be used to detect common files, and it will query the OS database if it exists.

Simplest Usage Example

The namespace for the library is ReMime.

Resolving Media Types

// Will resolve by file extensions.
MediaTypeResolver.TryResolve(pathString, out MediaType type);               // returns bool.
MediaTypeResolver.TryResolve(fileInfo, out MediaType type, open: false);    // returns MediaTypeResult

// Will resolve using content.
MediaTypeResolver.TryResolve(stream, out MediaType type);                   // returns bool.
MediaTypeResolver.TryResolve(byteSpan, out MediaType type);                 // returns bool.

// Will resolve using both file extensions and content.
MediaTypeResolver.TryResolve(pathString, stream, out MediaType type);       // returns MediaTypeResult.
MediaTypeResolver.TryResolve(pathString, byteSpan, out MediaType type);     // returns MediaTypeResult.

MediaTypeResolver.TryResolve(stream, out MediaType type);                   // returns bool.
MediaTypeResolver.TryResolve(byteSpan, out MediaType type);                 // returns bool.
MediaTypeResolver.TryResolve(fileInfo, out MediaType type, open: true);     // returns MediaTypeResult

MediaTypeResult Flags

Value	Explaination
None	Nothing matched if the value returned equals this.
Extension	Flag indicates the extension matched with the media type.
Content	Flag indicates the file content matched with the media type.

Adding Custom Resolvers

You will need to implement the interfaces IMediaTypeResolver or IMediaContentResolver. The former will only resolve file extensions, whilst the latter will resolve with both file extensions and its contents.

Then call MediaTypeResolver.AddResolver() with an instance of your custom resolver. You can choose a resolution priority, by default the priority is 9999. ReMime resolver priorities begin with 1000.

Adding New Media Types to ReMime Resolvers

ReMime media type resolvers are singletons under ReMime.ContentResolvers and ReMime.Platform. Currently the following resolvers are extensible:

• ReFuel.ContentResolvers.MagicContentResolver (implements IMagicValueResolver)
• ReFuel.ContentResolvers.RiffResolver (implements IMagicValueResolver)

Classes that implement IMagicValueResolver have AddMagicValue/AddMagicValues methods that make it easy to extend.

MagicValue

A MagicValue is a simple class that tries to match a specific string of bytes. It can accept standard FourCC 32-bit integers, or a string with a simple syntax.

The string syntax expects hexadecimal values by default. The hexadecimal values given must be byte aligned (no nibbles). Whitespace is ignored. You can start an ASCII sequence using the single quote ' character. The ASCII sequence accepts single character C style escape sequences like \'.

MagicValueMediaType

This is a simple record that the built-in resolvers use.

public record MagicValueMediaType(MediaType MediaType, MagicValue[] MagicValues, string[] Extensions);

Both arrays can be empty, as long as they are a non-null array. (See Array.Empty<T>())

Using a JSON File

ReMime includes a JSON serializer that makes it easy to configure the built-in resolvers. The JSON serializer will ignore comments.

[
    // List of media type entries.
    {
        "type": "image/png",    // The media type key.
        "magic": [ "89'PNG'" ], // List of magic value strings. (optional)
        "extensions": [ "png" ] // List of file extensions strings excluding the leading dot. (also optional)
    },
]

You may wish to include this database file as an embedded resource. Once you have the file open, you can call MagicValueDatabaseEntry.GetEntries(str). This will return a List<MagicValueMediaType> which can be consumed by the built-in resolvers using their AddMagicValues methods.