89 lines
4.1 KiB
Markdown
89 lines
4.1 KiB
Markdown
|
# 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
|
||
|
|
```cs
|
||
|
|
// 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.
|
||
|
|
```cs
|
||
|
|
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.
|
||
|
|
|
||
|
|
```jsonc
|
||
|
|
[
|
||
|
|
// 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.
|