ImfContentDisposition Class

Definition

Namespace: DataStandardizer.File.InternetMessage

The value of a Content-Disposition header field (RFC 2183), such as attachment; filename=genome.jpeg.

Syntax

public sealed class ImfContentDisposition : IEquatable<ImfContentDisposition>

Remarks

The type and the parameter names are compared case-insensitively, parameter values case-sensitively, and the order of the parameters doesn’t matter. Parameters in the forms of RFC 2231 are joined and decoded when read, and each is written as ImfMimeFields.FormatContentType writes one.

A file name comes from whoever sent the message, so treat it with care. RFC 2183 §2.3 says not to respect any directory path in it, and §5 warns against a name that overwrites a file or gets a program run. It isn’t checked here.

Constructors

Constructor Notes
ImfContentDisposition(string type) Initializes a new disposition with no parameters. type: The disposition type, such as attachment, which must follow the RFC 6838 §4.2 naming rules. Throws ArgumentNullException: type is null. Throws ArgumentException: type is not a valid name.
ImfContentDisposition(string type, IEnumerable<MimeParameter> parameters) Initializes a new disposition. type: The disposition type, such as attachment, which must follow the RFC 6838 §4.2 naming rules. Throws ArgumentNullException: type or parameters is null. Throws ArgumentException: type is not a valid name, or parameters holds a parameter that is not initialised, more than one parameter with the same name, or a date or size that isn’t valid (RFC 2183 §2).

Properties

Property Signature Notes
CreationDate ImfDateTime? CreationDate { get; } Gets the date the file was created (RFC 2183 §2.4), or null if there is none, or it isn’t valid and ImfOptions.AllowMalformedParameters kept it.
FileName string? FileName { get; } Gets the suggested file name (RFC 2183 §2.3), or null if there is none. See the remarks on this type before using it.
IsAttachment bool IsAttachment { get; } Gets whether to treat the entity as an attachment: its type is anything other than inline, as RFC 2183 §2.8 says of a type that isn’t recognised.
IsInline bool IsInline { get; } Gets whether the type is inline, compared case-insensitively.
ModificationDate ImfDateTime? ModificationDate { get; } Gets the date the file was last modified (RFC 2183 §2.5), or null if there is none, or it isn’t valid and ImfOptions.AllowMalformedParameters kept it.
Parameters IReadOnlyList<MimeParameter> Parameters { get; } Gets all the parameters, in the order they are written, including those that have properties here.
ReadDate ImfDateTime? ReadDate { get; } Gets the date the file was last read (RFC 2183 §2.6), or null if there is none, or it isn’t valid and ImfOptions.AllowMalformedParameters kept it.
Size long? Size { get; } Gets the approximate size of the file in octets (RFC 2183 §2.7), or null if there is none, or it isn’t valid and ImfOptions.AllowMalformedParameters kept it.
Type string Type { get; } Gets the disposition type, as written, such as attachment.

Fields

Field Signature Notes
Attachment static readonly ImfContentDisposition Attachment The attachment disposition (RFC 2183 §2.2), with no parameters.
Inline static readonly ImfContentDisposition Inline The inline disposition (RFC 2183 §2.1), with no parameters.

Methods

Method Returns Notes
Equals(ImfContentDisposition? other) bool Indicates whether this disposition equals another: the types and parameter names are the same, compared case-insensitively, and so are the parameter values, compared case-sensitively, in any order.
static Parse(string value) ImfContentDisposition Parses the body of a Content-Disposition field. Returns: The disposition. value: The field body, which may be folded and have comments, such as attachment; filename=genome.jpeg. Throws ArgumentNullException: value is null. Throws FormatException: The value is not valid, as TryParse(ReadOnlySpan<byte>, ImfOptions, out ImfContentDisposition) describes.
static Parse(ReadOnlySpan<byte> value) ImfContentDisposition Parses the body of a Content-Disposition field. Returns: The disposition. value: The field body as UTF-8, which may be folded and have comments, such as attachment; filename=genome.jpeg. Throws FormatException: The value is not valid, as TryParse(ReadOnlySpan<byte>, ImfOptions, out ImfContentDisposition) describes.
static Parse(string value, ImfOptions options) ImfContentDisposition Parses the body of a Content-Disposition field. Returns: The disposition. value: The field body, which may be folded and have comments, such as attachment; filename=genome.jpeg. options: The options, of which this uses ImfOptions.AllowInvalidValues, ImfOptions.AllowMalformedParameters and ImfOptions.CharsetResolver. Throws ArgumentNullException: value or options is null. Throws ArgumentException: options has no ImfOptions.CharsetResolver, or a ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved. Throws FormatException: The value is not valid, as TryParse(ReadOnlySpan<byte>, ImfOptions, out ImfContentDisposition) describes.
static Parse(ReadOnlySpan<byte> value, ImfOptions options) ImfContentDisposition Parses the body of a Content-Disposition field. Returns: The disposition. value: The field body, which may be folded and have comments, such as attachment; filename=genome.jpeg. Bytes that aren’t valid UTF-8 are decoded with ImfOptions.HeaderFallbackCharset, if ImfOptions.AllowEightBitHeaders is true. options: The options, of which this uses ImfOptions.AllowEightBitHeaders, ImfOptions.AllowInvalidValues, ImfOptions.AllowMalformedParameters, ImfOptions.CharsetResolver and ImfOptions.HeaderFallbackCharset. Throws ArgumentNullException: options is null. Throws ArgumentException: options has no ImfOptions.CharsetResolver, or a ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved. Throws FormatException: The value is not valid, as TryParse(ReadOnlySpan<byte>, ImfOptions, out ImfContentDisposition) describes.
ToString() string Writes the disposition as the body of a Content-Disposition field, such as attachment; filename=genome.jpeg. A parameter is written as a token or a quoted-string. One that isn’t US-ASCII, or that has a language, is written as an extended value, and one too long for a line of 78 characters is split into sections (RFC 2231), as RFC 2183 §2 requires. Returns: The field body, unfolded, with a space at each place it can be folded, for ImfHeaderFieldKind.Structured.
static TryParse(string? value, out ImfContentDisposition? result) bool Parses the body of a Content-Disposition field. Returns: true if the value is valid, as TryParse(ReadOnlySpan<byte>, ImfOptions, out ImfContentDisposition) describes; otherwise false, including for null. value: The field body, which may be folded and have comments, such as attachment; filename=genome.jpeg.
static TryParse(ReadOnlySpan<byte> value, out ImfContentDisposition? result) bool Parses the body of a Content-Disposition field. Returns: true if the value is valid, as TryParse(ReadOnlySpan<byte>, ImfOptions, out ImfContentDisposition) describes; otherwise false. value: The field body as UTF-8, which may be folded and have comments, such as attachment; filename=genome.jpeg.
static TryParse(string? value, ImfOptions options, out ImfContentDisposition? result) bool Parses the body of a Content-Disposition field. Returns: true if the value is valid, as TryParse(ReadOnlySpan<byte>, ImfOptions, out ImfContentDisposition) describes; otherwise false, including for null. value: The field body, which may be folded and have comments, such as attachment; filename=genome.jpeg. options: The options, of which this uses ImfOptions.AllowInvalidValues, ImfOptions.AllowMalformedParameters and ImfOptions.CharsetResolver. Throws ArgumentNullException: options is null. Throws ArgumentException: options has no ImfOptions.CharsetResolver, or a ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved.
static TryParse(ReadOnlySpan<byte> value, ImfOptions options, out ImfContentDisposition? result) bool Parses the body of a Content-Disposition field.

One semicolon may end the value. The grammar of RFC 2183 §2 has no place for it, but the example in its §3 has one. A date has to be a date-time with a numeric zone (RFC 2183 §2), in the modern or obsolete syntax, and ImfOptions.AllowInvalidValues applies to its day of the week as it does in ImfDateTime. A size has to be digits, and one too large for a Int64 is not valid. A parameter value with raw non-ASCII text is rejected, as RFC 2183 §2 requires the form of RFC 2231 for one.

A value breaks RFC 2231 if its sections or extended value aren’t valid, or a character set can’t be resolved, and it breaks RFC 2047 §5 if a parameter holds an encoded word, which is never allowed there. Those, and a date or size that isn’t valid, are rejected unless ImfOptions.AllowMalformedParameters is true, which describes what is then accepted. Returns: true if the value is valid; otherwise false. value: The field body, which may be folded and have comments, such as attachment; filename=genome.jpeg. Bytes that aren’t valid UTF-8 are decoded with ImfOptions.HeaderFallbackCharset, if ImfOptions.AllowEightBitHeaders is true. options: The options, of which this uses ImfOptions.AllowEightBitHeaders, ImfOptions.AllowInvalidValues, ImfOptions.AllowMalformedParameters, ImfOptions.CharsetResolver and ImfOptions.HeaderFallbackCharset. Throws ArgumentNullException: options is null. Throws ArgumentException: options has no ImfOptions.CharsetResolver, or a ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved.
WithCreationDate(ImfDateTime date) ImfContentDisposition Gets a copy of this disposition with the given creation date. Returns: The modified copy. Throws ArgumentException: date was made with default.
WithFileName(string fileName) ImfContentDisposition Gets a copy of this disposition with the given file name. Returns: The modified copy. fileName: The file name, without any directory path (RFC 2183 §2.3). It must not contain an unpaired surrogate. Throws ArgumentNullException: fileName is null. Throws ArgumentException: fileName contains an unpaired surrogate.
WithModificationDate(ImfDateTime date) ImfContentDisposition Gets a copy of this disposition with the given modification date. Returns: The modified copy. Throws ArgumentException: date was made with default.
WithParameter(MimeParameter parameter) ImfContentDisposition Gets a copy of this disposition with a parameter added, or with the value of the parameter of the same name replaced, which keeps its position. Returns: The modified copy. Throws ArgumentException: parameter is not initialised, or is a date or size that isn’t valid (RFC 2183 §2).
WithReadDate(ImfDateTime date) ImfContentDisposition Gets a copy of this disposition with the given read date. Returns: The modified copy. Throws ArgumentException: date was made with default.
WithSize(long size) ImfContentDisposition Gets a copy of this disposition with the given size. Returns: The modified copy. Throws ArgumentOutOfRangeException: size is negative.

Operators

Operator Returns Notes
operator !=(ImfContentDisposition? left, ImfContentDisposition? right) bool Indicates whether two dispositions differ.
operator ==(ImfContentDisposition? left, ImfContentDisposition? right) bool Indicates whether two dispositions are equal.

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. The nullable reference annotations apply to the netstandard2.1 and net10.0 builds.

See also


This site uses Just the Docs, a documentation theme for Jekyll.