Byte-exact round trips
What you read and don’t change is written back byte for byte. A DKIM or S/MIME signature covers particular bytes, so a tool that reformats a message it only meant to pass along breaks the signature. Here, a change rewrites only what changed.
What is kept
| What | How it is kept |
|---|---|
| A field that was read | ImfHeaderField.RawBytes holds its name, any white space before the colon, its folds and its line break. A writer copies them, obsolete syntax included, whatever options it was read under. |
| A body that hasn’t changed | ImfMessage.RawBody holds the bytes after the empty line that ends the header. A writer copies them. |
| The empty line that ends the header | Its line break is kept, and so is its absence, if the data ended first and there is still no body. |
| A part that hasn’t changed, in a message where another has | The bytes of the part are copied, and so are the delimiter lines of a multipart entity whose parts are all still there. |
| An mbox separator line | MboxEnvelope.RawLine holds it. |
| EMLX metadata that hasn’t changed | EmlxMetadata.RawBytes holds it, and the first line of the file is kept if the count is still right. |
What a change rewrites
Each of these rewrites that thing and leaves the rest alone:
- Setting an accessor, such as
ImfMessage.Subject, replaces that field where it is, or adds it after the other fields if there is none. It is written in the modern form, with CRLF line breaks. - Changing
ImfHeaderFieldCollection, withAdd,Insert,ReplaceorRemoveAll, changes those fields and no others. - Calling
ImfEntity.SetContentorSetTextgives that entity new content, for which the writer chooses a transfer encoding. - Changing an
EmlxMetadatawrites the whole property list again, as Apple’s tools lay it out, with the keys that weren’t changed still in order.
One thing changes without being asked: a multipart entity that was read with no close delimiter, under ImfOptions.AllowMissingBoundaryTerminator, gets one if it is written again after a change.
Line breaks in other file formats
RFC 5322 §2.1 requires CRLF line breaks in a message. RFC 4155 Appendix A requires LF in an mbox file, and an EMLX file uses LF too. So moving a message between these files changes every line break:
| From | To | Result |
|---|---|---|
| An mbox file with LF | MboxWriter with LF | Byte for byte, apart from what the variant adds. |
| An EMLX file | EmlxWriter | Byte for byte. |
| An mbox or EMLX file | ImfWriter | Every line break becomes CRLF. |
| An EML file | MboxWriter or EmlxWriter | Every line break becomes LF. |
That changes the bytes, so check what your verifier expects of a file that has been moved in this way. A message with a binary entity, or one with an extension transfer encoding, can’t change in this way, because a line break in it may not be one, so the writer throws ImfFileException.
The mbox variants differ in what reads back. See Read, filter and rewrite an mbox file.
Keeping bytes at the lower layers
The field and entity layers copy bytes in the same way:
ImfHeaderWriter.WriteField(view)andWriteFields(reader)copy fields that a reader has just read.WriteRawFieldcopies the bytes you give it, once it has checked that they are one whole field.ImfEntitySource.FromRawdescribes an entity by its raw bytes. With anImfEntityReader, those are the range of the data that theEntityEndevent covers.AddFieldandAddRawFielddo the same for a field of an entity that is otherwise written from parts.
Signatures aren’t checked
The package keeps the bytes that a signature covers, and doesn’t read the signature. It neither creates nor verifies DKIM or S/MIME signatures. A change to a field or body that a signature covers still makes the signature fail, however carefully the rest is copied.