ImfHeaderWriter Class

Definition

Namespace: DataStandardizer.File.InternetMessage

Represents a writer that provides fast, non-cached, forward-only output of the fields of one header section of an Internet message (RFC 5322 §2.2).

.NET Standard 1.1:

public sealed class ImfHeaderWriter : IDisposable

.NET and .NET Standard 2.0 and later:

public sealed class ImfHeaderWriter : IDisposable, IAsyncDisposable

Remarks

Line breaks. Every line ends in CRLF, whatever the platform.

Folding. A field given by name and body is folded at spaces and tabs already in the body, aiming for lines of 78 characters and never passing 998 octets (RFC 5322 §2.1.1 and §2.2.3, RFC 6532 §3.4). No white space is added or removed, except that one space is written after the colon if the body has none, so unfolding gives the same body back. A ImfHeaderFieldKind.Structured field is not folded inside a quoted string or domain literal. A field that can’t be folded within 998 octets is refused, and a line may pass 78 characters when it has nowhere to fold.

Encoded words. WriteTextField writes text as an unstructured field, with what has to be encoded as RFC 2047 encoded words unless ImfOptions.HeaderEncoding is ImfHeaderEncoding.Utf8. Each word is folded whole, so a line holds at most 76 characters of encoded words. WriteField(string, string, ImfHeaderFieldKind) writes a field body as it is given: get a body with encoded words from ImfAddress.ToString, ImfAddressList.ToString(ImfHeaderEncoding), ImfPhraseList.ToString(ImfHeaderEncoding) or ImfHeaderText.FormatComment.

Refusals. A field name must be printable US-ASCII with no colon (RFC 5322 §3.6.8). A body must be given unfolded, with no control characters. It must be US-ASCII, unless ImfOptions.HeaderEncoding is ImfHeaderEncoding.Utf8 and it is valid UTF-8 (RFC 6532). A field that is refused throws ImfFileException before any of it is written, so writing can continue with the next field.

Raw passthrough. A field written from an ImfHeaderFieldView is copied byte for byte, including its folding and line breaks, whichever options it was read under, so that signatures over it stay valid. So are bytes given to WriteRawField, once they have been checked to be one whole field.

Nothing is held back from the stream, so a body can be written straight to it after WriteEndOfHeader.

Only one operation may be in progress at a time. Synchronous and asynchronous calls may follow one another, but a call made while another is in progress throws InvalidOperationException. After a write to the stream fails or is canceled, the writer cannot continue. A write is canceled only when the token passed to it is canceled, whatever token the OperationCanceledException carries, or if it carries none. An OperationCanceledException while that token isn’t canceled, such as one from the stream or the progress callback, is handled as any other exception is.

A file-path constructor opens the file with FileOptions.Asynchronous, so the asynchronous methods do no synchronous I/O. To write a file only synchronously, without the small cost that option adds on Windows, pass a FileStream opened without it to a Stream constructor.

Constructors

Constructor Notes
ImfHeaderWriter(Stream messageStream) Creates a writer of a header section to a stream. Throws ArgumentNullException: messageStream is null. Throws ArgumentException: messageStream does not support writing.
ImfHeaderWriter(Stream messageStream, ImfOptions options) Creates a writer of a header section to a stream. Throws ArgumentNullException: messageStream or options is null. Throws ArgumentException: messageStream does not support writing.
ImfHeaderWriter(string messageFilePath) (netstandard2.0+/.NET) Creates a writer of a header section to a file. An existing file is overwritten. messageFilePath: The path of the file. The file is opened for asynchronous writing, and is closed when the writer is disposed. Throws ArgumentNullException: messageFilePath is null.
ImfHeaderWriter(string messageFilePath, ImfOptions options) (netstandard2.0+/.NET) Creates a writer of a header section to a file. An existing file is overwritten. messageFilePath: The path of the file. The file is opened for asynchronous writing, and is closed when the writer is disposed. Throws ArgumentNullException: messageFilePath or options is null.

Properties

Property Signature Notes
BytePosition long BytePosition { get; } Gets the number of bytes written so far. Throws ObjectDisposedException: The writer has been disposed.
FieldsWritten long FieldsWritten { get; } Gets the number of fields written so far. Throws ObjectDisposedException: The writer has been disposed.

Methods

Synchronous

Method Returns Notes
Dispose() void Releases the writer’s buffer, and closes the file it opened itself. A caller-supplied stream is left open. May be called more than once. If an operation is in progress, it completes with ObjectDisposedException, and the buffer and file are released once it has finished with them.
Flush() void Flushes the stream, whether the writer opened it or it was supplied by the caller. Throws ObjectDisposedException: The writer has been disposed. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue.
WriteEndOfHeader() void Writes the empty line that ends the header section (RFC 5322 §2.1). No more fields can be written after it. Throws ObjectDisposedException: The writer has been disposed. Throws InvalidOperationException: Another operation is in progress. -or- The section has already ended. -or- An earlier write failed or was canceled, so the writer cannot continue.
WriteField(ImfHeaderFieldView field) void Writes a field that a reader has just read, byte for byte. Throws ObjectDisposedException: The writer has been disposed, or the reader of the field has. Throws InvalidOperationException: Another operation is in progress. -or- The section has ended. -or- The reader has moved on from the field, or the view was not obtained from a reader. -or- An earlier write failed or was canceled, so the writer cannot continue.
WriteField(string name, string value, ImfHeaderFieldKind kind) void Writes a field, folded as its kind allows. value: The unfolded field body. One space is written before it if it doesn’t start with a space or tab, and isn’t empty. Throws ObjectDisposedException: The writer has been disposed. Throws ArgumentNullException: name or value is null. Throws ArgumentOutOfRangeException: kind is not an ImfHeaderFieldKind member. Throws ImfFileException: The field can’t be written. Nothing has been written. Throws InvalidOperationException: Another operation is in progress. -or- The section has ended. -or- An earlier write failed or was canceled, so the writer cannot continue.
WriteField(ReadOnlySpan<byte> name, ReadOnlySpan<byte> value, ImfHeaderFieldKind kind) void Writes a field, folded as its kind allows. value: The unfolded field body. One space is written before it if it doesn’t start with a space or tab, and isn’t empty. Throws ObjectDisposedException: The writer has been disposed. Throws ArgumentOutOfRangeException: kind is not an ImfHeaderFieldKind member. Throws ImfFileException: The field can’t be written. Nothing has been written. Throws InvalidOperationException: Another operation is in progress. -or- The section has ended. -or- An earlier write failed or was canceled, so the writer cannot continue.
WriteFields(ImfHeaderReader reader, IProgress<ImfWriteProgress>? progress = null) void Copies the rest of the fields of a reader, byte for byte. The empty line that ends the section is not written. The whole call is one operation, so progress may not call the writer. progress: Receives the progress after each field has been handed to the stream, synchronously on the writing thread; or null. An exception from IProgress.Report ends the call; the field it was reporting has been written. Progress runs its handler later, so writing doesn’t wait for the handler, and an exception from the handler doesn’t end the call. Throws ObjectDisposedException: The writer has been disposed, either before this call or during it, or the reader has. Throws ArgumentNullException: reader is null. Throws ImfFileException: The reader found a field it can’t read. The fields before it have been written. Throws InvalidOperationException: Another operation is in progress on the writer or the reader. -or- The section has ended. -or- An earlier write failed or was canceled, so the writer cannot continue.
WriteRawField(ReadOnlySpan<byte> rawField) void Writes the raw bytes of a field byte for byte, including its folding and its final line break, after checking that they are one whole field. The check is of the structure only: a field name and a colon, line breaks that are CRLF (or LF, with ImfOptions.AcceptBareLineFeed), a space or tab after every line break but the last, and a line break at the end. A body that a reader accepted under its options, such as one with a long line or bytes that are not UTF-8, is copied as it is. Throws ObjectDisposedException: The writer has been disposed. Throws ImfFileException: The bytes are not one whole field. Nothing has been written. Throws InvalidOperationException: Another operation is in progress. -or- The section has ended. -or- An earlier write failed or was canceled, so the writer cannot continue.
WriteTextField(string name, string text) void Writes text as an unstructured field, such as Subject: encoded as ImfHeaderText.FormatUnstructured describes, and folded between words. text: The text. One space is written before it if it doesn’t start with a space or tab, and isn’t empty. Throws ObjectDisposedException: The writer has been disposed. Throws ArgumentNullException: name or text is null. Throws ImfFileException: The field can’t be written, as the text holds a control character other than tab or an unpaired surrogate. Nothing has been written. Throws InvalidOperationException: Another operation is in progress. -or- The section has ended. -or- An earlier write failed or was canceled, so the writer cannot continue.

Asynchronous (netstandard2.0+/.NET)

Method Returns Notes
DisposeAsync() ValueTask Releases the writer’s buffer, and closes the file it opened itself, asynchronously. A caller-supplied stream is left open. May be called more than once, and shares its state with Dispose. If an operation is in progress, it completes with ObjectDisposedException, and the buffer and file are released once it has finished with them. Returns: A task that completes once any operation in progress has finished, and the file has been closed.
FlushAsync(CancellationToken cancellationToken = default) Task Flushes the stream asynchronously, whether the writer opened it or it was supplied by the caller. Returns: A task that completes once the stream has been flushed. cancellationToken: The token to monitor for cancellation requests. The flush is canceled only if this token is canceled, and the writer then cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the flush is in progress. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue. Throws OperationCanceledException: By the task: cancellationToken was canceled before the call, or the operation failed with an OperationCanceledException, whatever token it carries, while cancellationToken was canceled. The task is canceled. An OperationCanceledException while cancellationToken isn’t canceled faults the task, as any other exception does.
WriteEndOfHeaderAsync(CancellationToken cancellationToken = default) ValueTask Writes the empty line that ends the header section (RFC 5322 §2.1), asynchronously. No more fields can be written after it. Returns: A task that completes once the line has been handed to the stream. cancellationToken: The token to monitor for cancellation requests. The write is canceled only if this token is canceled, and the writer then cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the write is in progress. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue. -or- By the task: the section has already ended. Throws OperationCanceledException: By the task: cancellationToken was canceled before the call, or the operation failed with an OperationCanceledException, whatever token it carries, while cancellationToken was canceled. The task is canceled. An OperationCanceledException while cancellationToken isn’t canceled faults the task, as any other exception does.
WriteFieldAsync(ImfHeaderFieldView field, CancellationToken cancellationToken = default) ValueTask Writes a field that a reader has just read, byte for byte, asynchronously. The field must stay current until the task completes, so don’t read from the reader until then. Returns: A task that completes once the field has been handed to the stream. cancellationToken: The token to monitor for cancellation requests. The write is canceled only if this token is canceled, and the writer then cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the write is in progress. By the task: the reader of the field has been disposed. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue. -or- By the task: the section has ended, or the reader has moved on from the field, or the view was not obtained from a reader. Throws OperationCanceledException: By the task: cancellationToken was canceled before the call, or the operation failed with an OperationCanceledException, whatever token it carries, while cancellationToken was canceled. The task is canceled. An OperationCanceledException while cancellationToken isn’t canceled faults the task, as any other exception does.
WriteFieldAsync(string name, string value, ImfHeaderFieldKind kind, CancellationToken cancellationToken = default) ValueTask Writes a field asynchronously, folded as its kind allows. Returns: A task that completes once the field has been handed to the stream. value: The unfolded field body. One space is written before it if it doesn’t start with a space or tab, and isn’t empty. cancellationToken: The token to monitor for cancellation requests. The write is canceled only if this token is canceled, and the writer then cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the write is in progress. Throws ArgumentNullException: name or value is null. Throws ArgumentOutOfRangeException: kind is not an ImfHeaderFieldKind member. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue. -or- By the task: the section has ended. Throws ImfFileException: By the task: the field can’t be written. Nothing has been written. Throws OperationCanceledException: By the task: cancellationToken was canceled before the call, or the operation failed with an OperationCanceledException, whatever token it carries, while cancellationToken was canceled. The task is canceled. An OperationCanceledException while cancellationToken isn’t canceled faults the task, as any other exception does.
WriteFieldAsync(ReadOnlyMemory<byte> name, ReadOnlyMemory<byte> value, ImfHeaderFieldKind kind, CancellationToken cancellationToken = default) ValueTask Writes a field asynchronously, folded as its kind allows. Returns: A task that completes once the field has been handed to the stream. value: The unfolded field body. One space is written before it if it doesn’t start with a space or tab, and isn’t empty. cancellationToken: The token to monitor for cancellation requests. The write is canceled only if this token is canceled, and the writer then cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the write is in progress. Throws ArgumentOutOfRangeException: kind is not an ImfHeaderFieldKind member. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue. -or- By the task: the section has ended. Throws ImfFileException: By the task: the field can’t be written. Nothing has been written. Throws OperationCanceledException: By the task: cancellationToken was canceled before the call, or the operation failed with an OperationCanceledException, whatever token it carries, while cancellationToken was canceled. The task is canceled. An OperationCanceledException while cancellationToken isn’t canceled faults the task, as any other exception does.
WriteFieldsAsync(ImfHeaderReader reader, IProgress<ImfWriteProgress>? progress = null, CancellationToken cancellationToken = default) Task Copies the rest of the fields of a reader, byte for byte, asynchronously. The empty line that ends the section is not written. The whole call is one operation, so progress may not call the writer. Returns: A task that completes once every field has been handed to the stream. progress: Receives the progress after each field has been handed to the stream, synchronously on the writing thread; or null. An exception from IProgress.Report ends the call; the field it was reporting has been written. Progress runs its handler later, so writing doesn’t wait for the handler, and an exception from the handler doesn’t end the call. cancellationToken: The token to monitor for cancellation requests. The write is canceled only if this token is canceled, and the writer then cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the write is in progress. By the task: the reader has been disposed. Throws ArgumentNullException: reader is null. Throws InvalidOperationException: Another operation is in progress on the writer. -or- An earlier write failed or was canceled, so the writer cannot continue. -or- By the task: the section has ended, or another read is in progress on the reader. Throws ImfFileException: By the task: the reader found a field it can’t read. The fields before it have been written. Throws OperationCanceledException: By the task: cancellationToken was canceled before the call, or the operation failed with an OperationCanceledException, whatever token it carries, while cancellationToken was canceled. The task is canceled. An OperationCanceledException while cancellationToken isn’t canceled faults the task, as any other exception does.
WriteRawFieldAsync(ReadOnlyMemory<byte> rawField, CancellationToken cancellationToken = default) ValueTask Writes the raw bytes of a field byte for byte, asynchronously, after checking that they are one whole field. The check is the one WriteRawField describes. Returns: A task that completes once the field has been handed to the stream. cancellationToken: The token to monitor for cancellation requests. The write is canceled only if this token is canceled, and the writer then cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the write is in progress. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue. -or- By the task: the section has ended. Throws ImfFileException: By the task: the bytes are not one whole field. Nothing has been written. Throws OperationCanceledException: By the task: cancellationToken was canceled before the call, or the operation failed with an OperationCanceledException, whatever token it carries, while cancellationToken was canceled. The task is canceled. An OperationCanceledException while cancellationToken isn’t canceled faults the task, as any other exception does.
WriteTextFieldAsync(string name, string text, CancellationToken cancellationToken = default) ValueTask Writes text as an unstructured field, such as Subject, asynchronously: encoded as ImfHeaderText.FormatUnstructured describes, and folded between words. Returns: A task that completes once the field has been handed to the stream. text: The text. One space is written before it if it doesn’t start with a space or tab, and isn’t empty. cancellationToken: The token to monitor for cancellation requests. The write is canceled only if this token is canceled, and the writer then cannot continue. Throws ObjectDisposedException: The writer has been disposed. Thrown by this call, or by the task if the writer is disposed while the write is in progress. Throws ArgumentNullException: name or text is null. Throws InvalidOperationException: Another operation is in progress. -or- An earlier write failed or was canceled, so the writer cannot continue. -or- By the task: the section has ended. Throws ImfFileException: By the task: the field can’t be written, as the text holds a control character other than tab or an unpaired surrogate. Nothing has been written. Throws OperationCanceledException: By the task: cancellationToken was canceled before the call, or the operation failed with an OperationCanceledException, whatever token it carries, while cancellationToken was canceled. The task is canceled. An OperationCanceledException while cancellationToken isn’t canceled faults the task, as any other exception does.

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. The string file-path constructors, the asynchronous methods, and IAsyncDisposable are available on netstandard2.0, netstandard2.1, and net10.0 only; on netstandard1.1, construct it from a Stream and work synchronously. 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.