ImfOptions Class

Definition

Namespace: DataStandardizer.File.InternetMessage

Options to configure the behaviour of an Internet message reader or writer.

.NET:

public sealed record ImfOptions

.NET Standard:

public sealed class ImfOptions

Remarks

The default settings for all options ensure behaviour consistent with RFC 5322, RFC 6532, RFC 2045, RFC 2046 and RFC 4155, and with the layout that Apple Mail gives EMLX files, which has no published standard. Each accommodation for common non-compliant input is a separate option, off by default. A writer always writes what the standards allow, so the accommodations affect it only where noted.

Constructors

Constructor Notes
ImfOptions() Creates options with the default settings, which follow the standards.

Properties

Property Signature Notes
AcceptBareLineFeed bool AcceptBareLineFeed { get; init; } Gets a flag indicating if a bare line feed is accepted as a line break: at the end of a field, in a fold, and as the empty line that ends the header section. RFC 5322 §2.1 requires lines to end in CRLF, and §2.2 allows CR and LF in a field only as part of a fold. When false (the default), a bare line feed causes an ImfFileException. A bare carriage return is never accepted. With an ImfEntityReader, the same goes for the line breaks of a multipart delimiter (RFC 2046 §5.1.1) and of a quoted-printable body being decoded (RFC 2045 §6.7); when false, a delimiter with a bare line feed is content. A writer never adds a bare line feed, but with this option it accepts one in a raw field given to ImfHeaderWriter.WriteRawField or ImfEntitySource.AddRawField, which it copies as it is.
AllowBinaryTransferEncoding bool AllowBinaryTransferEncoding { get; init; } Gets a flag indicating if an ImfEntityWriter may give a body the binary transfer encoding, when it has not been told which to use. RFC 2045 §2.9 and §6.2 define the encoding, but a transport can carry it only if it supports RFC 3030 BINARYMIME, so when false (the default) such a body is encoded instead. This setting doesn’t relax a rule of the standard: it says what the destination can carry.
AllowCardinalityViolations bool AllowCardinalityViolations { get; init; } Gets a flag indicating if a header may have more than one of a field that RFC 5322 §3.6 allows at most once. The table in RFC 5322 §3.6 allows Date, From, Sender, Reply-To, To, Cc, Bcc, Message-ID, In-Reply-To, References and Subject at most once, so a message that has more MUST NOT be generated. When false (the default), an ImfWriter throws an ImfFileException for a second one. When true, it records an ImfDiagnostic instead. A reader doesn’t use this option: RFC 5322 §4 and §4.5 require a receiver to accept repeated fields, so it always records an ImfDiagnostic. The accessors of ImfMessage use the first, except that To, Cc and Bcc combine theirs, as §4.5 says.
AllowEightBitHeaders bool AllowEightBitHeaders { get; init; } Gets a flag indicating if a field body whose bytes are not valid UTF-8 is accepted. RFC 6532 §3.2 extends header field bodies to UTF-8 only. When false (the default), any other byte above 127, such as raw Latin-1 or Shift_JIS in an old message, causes an ImfFileException. When true, the field is read, its ImfHeaderFieldView.NeedsHeaderFallbackCharset is true, and ImfHeaderFieldView.GetValue decodes it with HeaderFallbackCharset. Field names are not affected: RFC 6532 leaves them as printable US-ASCII, so a byte above 127 in a name is always rejected.
AllowEightBitMboxContent bool AllowEightBitMboxContent { get; init; } Gets a flag indicating if a message of an mbox file may hold octets above 127. RFC 4155 Appendix A requires seven-bit characters, with eight-bit data converted to a seven-bit form. When false (the default), an octet above 127 causes an ImfFileException from an MboxReader or MboxWriter. When true, an ImfDiagnostic is recorded instead, once for each message. Many mailboxes kept on disk hold such messages.
AllowEightBitTransferEncoding bool AllowEightBitTransferEncoding { get; init; } Gets a flag indicating if an ImfEntityWriter may give a body the 8bit transfer encoding, when it has not been told which to use. RFC 2045 §2.8 and §6.2 define the encoding, but a transport can carry it only if it supports RFC 6152 8BITMIME, so when false (the default) such a body is encoded instead. This setting doesn’t relax a rule of the standard: it says what the destination can carry.
AllowInvalidBodyOctets bool AllowInvalidBodyOctets { get; init; } Gets a flag indicating if a body may hold an octet or a line break that its transfer encoding doesn’t allow. RFC 5322 §2.3 makes a body US-ASCII, and RFC 2045 §6.1 makes 7bit the default. §2.7 allows no octet above 127 and no NUL in 7bit data, §2.8 allows no NUL in 8bit data, and both allow CR and LF only as a CRLF. §6.4 limits a part to the encoding of the entity that holds it, and that goes for the header of a part or an embedded message too, so one with an octet above 127 needs an 8bit or binary label on the entity that holds it (RFC 6532 §3.7). The header of the message itself has nothing holding it, so RFC 6532 §3.2 lets it hold UTF-8. When false (the default), a reader or an ImfWriter throws an ImfFileException for such a body or header. When true, it records an ImfDiagnostic instead, once for each body and each header. A message with no MIME fields may always hold NUL and bare CR and LF, as RFC 5322 §4.1 requires a receiver to accept them. AcceptBareLineFeed accepts a bare line feed on its own.
AllowInvalidEmlxByteCount bool AllowInvalidEmlxByteCount { get; init; } Gets a flag indicating if an EMLX file may start with a byte count that is wrong. EMLX has no published standard. The layout that open-source readers agree on starts with the length of the message in bytes. When false (the default), a first line that isn’t a number, a count that passes the end of the file, and a count after which the bytes don’t start a property list each cause an ImfFileException. When true, an EmlxReader records an ImfDiagnostic instead, discards the first line, and takes the last <?xml, or failing that the last <plist, as the start of the property list. If it finds neither, the whole of the rest is the message. This is a best guess: in a file with no property list, a message that holds such text is cut short there. An EmlxWriter always writes the right count, so it doesn’t use this option.
AllowInvalidEmlxMetadata bool AllowInvalidEmlxMetadata { get; init; } Gets a flag indicating if an EMLX file may have a property list that is missing or not well formed. EMLX has no published standard. The layout that open-source readers agree on ends with an XML property list whose root is a dict. When false (the default), an EmlxReader or EmlxWriter throws an ImfFileException for a file with none, or with one that isn’t well formed. When true, it records an ImfDiagnostic instead. The reader gives an EmlxMetadata with no entries that keeps the bytes in EmlxMetadata.RawBytes, and the writer writes them back as they are.
AllowInvalidMboxContentLength bool AllowInvalidMboxContentLength { get; init; } Gets a flag indicating if an MboxReader accepts a Content-Length field that is missing or wrong, in the MboxVariant.Mboxcl and MboxVariant.Mboxcl2 variants. These variants find the end of a message from its Content-Length field. When false (the default), a field that is missing, that is not a single number, or that doesn’t lead to an empty line and then a separator line or the end of the file, causes an ImfFileException. When true, the field is not relied on: a message ends at the next separator line that follows an empty line, and an ImfDiagnostic is recorded if the field doesn’t give the length found. So a body of the MboxVariant.Mboxcl2 variant that holds an empty line and then what looks like a separator line is split there, even if its field was right.
AllowInvalidMboxSeparator bool AllowInvalidMboxSeparator { get; init; } Gets a flag indicating if a separator line of an mbox file may differ from the form that RFC 4155 Appendix A requires. RFC 4155 Appendix A requires an addr-spec and a UTC date and time in the form of ctime. When false (the default), an MboxReader throws an ImfFileException for a first line in any other form, and takes any later line in another form as part of the message, as the standard prescribes no way to quote one, with an ImfDiagnostic. An MboxWriter throws for an MboxEnvelope that was read in another form. When true, a line is a separator line if it has a sender and a date and time, with the day not padded, no seconds, a time zone before or after the year, or more white space, as Thunderbird and Gmail write, and an ImfDiagnostic is recorded. MboxEnvelope.Sender or MboxEnvelope.Date is null if it can’t be understood.
AllowInvalidRelatedStructure bool AllowInvalidRelatedStructure { get; init; } Gets a flag indicating if an MhtmlDocument, MhtmlReader or MhtmlWriter accepts a multipart/related entity that breaks the rules of its structure. RFC 2387 §3.1 requires a type parameter that gives the media type of the root part, and §3.2 has the start parameter give the Content-ID of that part, or otherwise the first part be the root, so there has to be one. RFC 2557 §7 requires each part to have a different Content-ID, and a Content-Location that resolves to a different URL. RFC 2045 §7 requires a Content-ID to be unique outside a multipart/related entity too, so two parts outside one with the same Content-ID count here. When false (the default), breaking one of these causes an ImfFileException. When true, it records an ImfDiagnostic instead, the first part is the root if start names none, the entity is its own root if it has no parts, and the first of the parts with the same label is the one that is found. Word saves web pages with no type parameter. ImfReader and ImfWriter don’t check these rules, and so don’t use this option.
AllowInvalidTextOctets bool AllowInvalidTextOctets { get; init; } Gets a flag indicating if ImfEntity.GetText accepts octets that are not valid in the character set of the text. RFC 2046 §4.1.2 has the charset parameter say what character set the text is in, with US-ASCII as the default, so other octets are not text of that type. When false (the default), they cause an ImfFileException. When true, each is read as U+FFFD, which helps with old messages that send 8-bit text and name no character set.
AllowInvalidValues bool AllowInvalidValues { get; init; } Gets a flag indicating if a date-time with a day of the week that doesn’t match its date is accepted. RFC 5322 §3.3 requires the day of the week, if there is one, to be the day implied by the date. When false (the default), ImfDateTime.Parse(string, ImfOptions) throws a FormatException for one that isn’t. When true, the date decides: ImfDateTime.DayOfWeek is the day implied by the date, and that is the day that gets written. The other rules of §3.3 are always enforced, because a value that breaks them, such as 30 February, is not a date. The same goes for the dates of an ImfContentDisposition. ImfMimeFields.ParseContentLanguage(string, ImfOptions) rejects a language tag that isn’t well-formed (RFC 3282 §2). When true, it leaves that tag out of the list. An ImfReader or ImfWriter throws an ImfFileException if the body of a field that RFC 5322 §3.6 defines breaks its grammar, or a Sender or Resent-Sender group has more than one mailbox (RFC 6854 §2.1). When true, it records an ImfDiagnostic instead, the field stays as it is, and the accessor for it gives null, unless the value is only a day of the week that doesn’t match. The same goes for an MhtmlDocument and a Content-Location field that breaks RFC 2557 §4.1 or §4.4.1.
AllowLongLines bool AllowLongLines { get; init; } Gets a flag indicating if a line longer than 998 octets is accepted. RFC 5322 §2.1.1 limits each line to 998 octets, not counting the CRLF, and RFC 2045 §6.7 and §6.8 limit a line of a quoted-printable or base64 body to 76. A binary body has no lines (RFC 2045 §2.9). When false (the default), a longer line causes an ImfFileException. The limit is on each physical line, so a folded field may be longer once unfolded. When true, a line of a header is still limited by MaxHeaderSectionLength, and a line of a body records an ImfDiagnostic, once for each body. RFC 4155 Appendix A applies the 998 octets to each line in an mbox file, so the quote that MboxWriter adds and MboxReader takes off counts towards them, and this option accepts a line that it takes past them, with an ImfDiagnostic.
AllowMalformedEncodedWords bool AllowMalformedEncodedWords { get; init; } Gets a flag indicating if RFC 2047 encoded words that don’t follow the rules are decoded. When false (the default), a word that breaks a rule of RFC 2047 §2, §4, §5 or §6.3 stays as ordinary text (RFC 2047 §6.1 and §6.2). When true, each of the accommodations of MimeEncodedWordParseOptions applies: a word longer than the 75 characters of §2 (MimeEncodedWordParseOptions.AllowLongWords), a word not separated from the text next to it, which §5 requires (MimeEncodedWordParseOptions.AllowEmbeddedWords), a character set that CharsetResolver can’t resolve, which §6.2 lets a reader show as it can (MimeEncodedWordParseOptions.AllowUnknownCharsets), lower-case hexadecimal digits, which §4.2 doesn’t allow (MimeEncodedWordParseOptions.AllowLowercaseHexDigits), octets that aren’t valid in the character set, which §6.3 calls incorrectly formed (MimeEncodedWordParseOptions.AllowInvalidOctets), and a character split between words, which §5 doesn’t allow (MimeEncodedWordParseOptions.AllowSplitCharacters).
AllowMalformedParameters bool AllowMalformedParameters { get; init; } Gets a flag indicating if the parameters of a Content-Type or Content-Disposition field are accepted when they don’t follow the rules.

When false (the default), a parameter that breaks a rule below makes the field invalid. When true, each of the accommodations of MimeMediaTypeParseOptions for RFC 2231 applies: sections that break the numbering of §3 (MimeMediaTypeParseOptions.AllowNonstandardSections), an extended value that breaks the grammar of §7 (MimeMediaTypeParseOptions.AllowNonstandardExtendedValues), a character set that CharsetResolver can’t resolve, or no character set for octets above 127, which §4 doesn’t allow (MimeMediaTypeParseOptions.AllowUnknownCharsets), and octets that aren’t valid in the character set (MimeMediaTypeParseOptions.AllowInvalidOctets).

The other accommodations are for ImfMimeFields.ParseContentType(string, ImfOptions) and ImfContentDisposition.Parse(string, ImfOptions). RFC 2047 §5 doesn’t allow an encoded word in a parameter. When true, one is accepted, and it is decoded in the filename of a Content-Disposition field and the name of a Content-Type field, and stays as written in any other parameter. A semicolon may end a Content-Type field, which RFC 2045 §5.1 doesn’t allow. A date or size in a Content-Disposition field that breaks RFC 2183 §2 stays as a parameter, and its property is null.

An ImfEntityReader uses only the accommodations for RFC 2231. It doesn’t look at other parameters than those it needs to find the parts of a message. An ImfEntityWriter uses them only to read a Content-Type field added to an entity, which it copies as it is, and never to write a field of its own.
AllowMboxCarriageReturnLineFeed bool AllowMboxCarriageReturnLineFeed { get; init; } Gets a flag indicating if an mbox file may have a carriage return and a line feed as a line break. RFC 4155 Appendix A requires a single line feed, and doesn’t allow a carriage return and a line feed. When false (the default), an MboxReader throws an ImfFileException for a first separator line that ends in them, or a line of a message that does, and an MboxWriter writing line feeds does the same for a line of a message that ends in them. When true, an ImfDiagnostic is recorded instead. A reader then reads a file whose first separator line ends in them with that line break throughout, and in any other file the carriage return is part of its line. An MboxWriter writes this line break only when MboxLineBreak.CarriageReturnLineFeed is given to it, whatever this option says.
AllowMissingBoundaryTerminator bool AllowMissingBoundaryTerminator { get; init; } Gets a flag indicating if a multipart entity with no close delimiter is accepted. RFC 2046 §5.1.1 ends every multipart body with a close delimiter. When false (the default), an ImfEntityReader throws an ImfFileException if the data ends, or a delimiter of an enclosing multipart entity is found, first. When true, the multipart entity ends there. One with no delimiter at all then has no parts, and its whole body is its preamble.
AllowMissingMboxBlankLine bool AllowMissingMboxBlankLine { get; init; } Gets a flag indicating if an MboxReader accepts a message that isn’t ended by an empty line. RFC 4155 Appendix A ends each message with an empty line. When false (the default), a separator line or the end of the file that doesn’t follow one causes an ImfFileException. When true, the message ends there, and an ImfDiagnostic is recorded.
AllowMissingMboxSeparator bool AllowMissingMboxSeparator { get; init; } Gets a flag indicating if an MboxReader accepts a file that doesn’t start with a separator line. RFC 4155 Appendix A has a separator line immediately before each message. When false (the default), a file with any other first line causes an ImfFileException. When true, everything before the first separator line is skipped, and an ImfDiagnostic is recorded.
AllowMissingMimeVersion bool AllowMissingMimeVersion { get; init; } Gets a flag indicating if a header may have a MIME field with no MIME-Version field. RFC 2045 §4 requires the field at the top level of a message that follows MIME. When false (the default), a reader of whole messages or an ImfWriter throws an ImfFileException for a message without one. When true, it records an ImfDiagnostic instead. An embedded message needs one only if it claims to follow MIME, so one without it only ever records an ImfDiagnostic.
AllowMissingRequiredFields bool AllowMissingRequiredFields { get; init; } Gets a flag indicating if a header may lack a field that RFC 5322 or RFC 2046 requires.

RFC 5322 §3.6 requires Date and From. §3.6.2 and RFC 6854 §2.1 require Sender when From has more than one mailbox, and §3.6.6 applies the same rules to Resent-Date, Resent-From and Resent-Sender in each block of resent fields. When false (the default), an ImfWriter or MhtmlWriter throws an ImfFileException for a message without one. When true, it records an ImfDiagnostic instead. A reader doesn’t need this option for these, and always records an ImfDiagnostic: RFC 5322 §4 says that a receiver MUST accept the obsolete syntax, and the obs-fields of §4.5 has no minimum for any field.

RFC 2046 §5.2.1 requires one of From, Subject or Date in an embedded message. When false (the default), a reader or writer throws an ImfFileException for an embedded message with none of them. When true, it records an ImfDiagnostic instead.
CharsetResolver IMimeCharsetResolver CharsetResolver { get; init; } Gets the resolver for character sets: HeaderFallbackCharset, those named in the extended parameters of a Content-Type or Content-Disposition field (RFC 2231 §4), and those of RFC 2047 encoded words. The default is MimeCharsetResolver.Default. An ImfEntityReader always needs it. An ImfHeaderReader needs it when AllowEightBitHeaders is true, and for ImfHeaderFieldView.GetDecodedValue.
DecodeTransferEncoding bool DecodeTransferEncoding { get; init; } Gets a flag indicating if an ImfEntityReader decodes bodies as it reads them. When false (the default), body chunks are the raw bytes of the message. When true, a body with a Content-Transfer-Encoding of quoted-printable or base64 is decoded (RFC 2045 §6.7 and §6.8), and one with an extension mechanism is left as it is, with an ImfDiagnostic. Data that is not valid in its encoding causes an ImfFileException.
HeaderEncoding ImfHeaderEncoding HeaderEncoding { get; init; } Gets how a writer writes header text that is not US-ASCII. The default is ImfHeaderEncoding.EncodedWords (RFC 2047). ImfHeaderWriter.WriteTextField and ImfEntitySource.AddTextField write text that is not US-ASCII as encoded words, as ImfHeaderText.FormatUnstructured describes. A field body is written as it is given, so with that default it is refused if it is not US-ASCII. With ImfHeaderEncoding.Utf8, valid UTF-8 is written as it is (RFC 6532).
HeaderFallbackCharset MimeCharset HeaderFallbackCharset { get; init; } Gets the character set that decodes a field body that is not valid UTF-8, when AllowEightBitHeaders is true. The default is ISO-8859-1, which can decode any bytes, and gives the same result on every runtime. A reader’s constructor throws ArgumentException if CharsetResolver can’t resolve the character set. It is used only when AllowEightBitHeaders is true.
MaxEmlxMetadataLength int MaxEmlxMetadataLength { get; init; } Gets the maximum length, in octets, of the property list of an EMLX file. EMLX has no published standard, so this limit is the package’s own, and guards against hostile input. The default is DefaultMaxEmlxMetadataLength, and the value must be at least 1. One more octet causes an ImfFileException from an EmlxReader or EmlxWriter.
MaxEntitySize int MaxEntitySize { get; init; } Gets the maximum size, in octets, of the body that an ImfReader holds in memory, and of the content given to ImfEntity.SetContent. RFC 5322 sets no limit. This one guards against hostile input. The default is DefaultMaxEntitySize, and the value must be at least 1. One more octet causes an ImfFileException, or an ArgumentException from ImfEntity.SetContent. A part of a message that was read is within the body, so it can’t pass the limit, and decoding it can only make it shorter. The readers and writers that don’t hold a whole body in memory don’t use it.
MaxHeaderFieldCount int MaxHeaderFieldCount { get; init; } Gets the maximum number of fields in a header section. RFC 5322 sets no limit. This one guards against hostile input. The default is DefaultMaxHeaderFieldCount, and the value must be at least 1. One more field causes an ImfFileException.
MaxHeaderSectionLength int MaxHeaderSectionLength { get; init; } Gets the maximum length, in octets, of a header section, counting its line breaks and the empty line that ends it. RFC 5322 sets no limit. This one guards against hostile input, as a reader holds a whole field in memory. The default is DefaultMaxHeaderSectionLength, and the value must be at least 1. One more octet causes an ImfFileException.
MaxMessageCount int MaxMessageCount { get; init; } Gets the maximum number of messages that an MboxReader reads from a file. RFC 4155 sets no limit. This one guards against hostile input. The default is DefaultMaxMessageCount, and the value must be at least 1. One more message causes an ImfFileException. The other limits apply to each message.
MaxNestingDepth int MaxNestingDepth { get; init; } Gets the maximum depth of the entities of a message, in which the message itself is at depth 0. RFC 2046 sets no limit. This one guards against hostile input. Each part of a multipart entity, and each embedded message, is one level deeper than the entity that holds it. The default is DefaultMaxNestingDepth, and the value must be at least 1. An entity one level deeper causes an ImfFileException. It also limits how deeply the values of the property list of an EMLX file nest, and deeper values make the property list one that isn’t well formed, as AllowInvalidEmlxMetadata describes.
MaxPartCount int MaxPartCount { get; init; } Gets the maximum number of entities in a message, not counting the message itself. RFC 2046 sets no limit. This one guards against hostile input. Every part of a multipart entity and every embedded message counts, at any depth. The default is DefaultMaxPartCount, and the value must be at least 1. One more entity causes an ImfFileException.

Fields

Field Signature Notes
DefaultMaxEmlxMetadataLength const int DefaultMaxEmlxMetadataLength = 1048576 The default value of MaxEmlxMetadataLength, which is 1 MiB.
DefaultMaxEntitySize const int DefaultMaxEntitySize = 268435456 The default value of MaxEntitySize, which is 256 MiB.
DefaultMaxHeaderFieldCount const int DefaultMaxHeaderFieldCount = 1000 The default value of MaxHeaderFieldCount.
DefaultMaxHeaderSectionLength const int DefaultMaxHeaderSectionLength = 1048576 The default value of MaxHeaderSectionLength, which is 1 MiB.
DefaultMaxMessageCount const int DefaultMaxMessageCount = 1000000 The default value of MaxMessageCount.
DefaultMaxNestingDepth const int DefaultMaxNestingDepth = 100 The default value of MaxNestingDepth.
DefaultMaxPartCount const int DefaultMaxPartCount = 10000 The default value of MaxPartCount.

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. This type is a record on net10.0, so with expressions work there, and its properties are init-only. On the .NET Standard targets it is a plain class, and its properties have set accessors. 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.