Convenience method for calling getContents() on {@see \IMessagePart::getStream()}.

The method wraps a call to {@see \IMessagePart::getBinaryContentStream()} and returns a resource handle for the returned Stream.

This is basically the same as calling {@see \IMessagePart::getContentStream()}, except no automatic charset conversion is done. Note that for non-text streams, this doesn't have an effect, as charset conversion is not performed in that case, and is useful only when:

• The charset defined is not correct, and the conversion produces errors; or
• You'd like to read the raw contents without conversion, for instance to save it to file or allow a user to download it as-is (in a download link for example).

The returned string is encoded to the passed $charset character encoding.

To get a stream without charset conversion if you know the part's content contains a binary stream, call {@see \self::getBinaryContentStream()} instead.

The library automatically handles decoding and charset conversion (to the target passed $charset) based on the part's transfer encoding as returned by {@see \IMessagePart::getContentTransferEncoding()} and the part's charset as returned by {@see \IMessagePart::getCharset()}. The returned stream is ready to be read from directly.

Note that the returned Stream is a shared object. If called multiple times with the same $charset, and the value of the part's Content-Transfer-Encoding header has not changed, the stream will be rewound. This would affect other existing variables referencing the stream, for example:

// assuming $part is a part containing the following
// string for its content: '12345678'
$stream = $part->getContentStream();
$someChars = $part->read(4);

$stream2 = $part->getContentStream();
$moreChars = $part->read(4);
echo ($someChars === $moreChars);    //1

In this case the Stream was rewound, and $stream's second call to read 4 bytes reads the same first 4.

If the part has not been modified and represents a parsed part, the original stream should be returned. Otherwise a stream representation of the part including its modifications should be returned. This insures that an unmodified, signed message could be passed on that way even after parsing and reading.

The returned stream is not guaranteed to be RFC822 (or greater) compliant for the following reasons:

• The original email or part, if not modified, is returned as-is and may not be compliant.
• Although certain parts may have been modified, an original unmodified header from the original email or part may not be compliant.
• A user may set headers in a non-compliant format.

If the part has not been modified and represents a parsed part, the original stream should be returned. Otherwise a stream representation of the part including its modifications should be returned. This insures that an unmodified, signed message could be passed on that way even after parsing and reading.

The returned stream is not guaranteed to be RFC822 (or greater) compliant for the following reasons:

• The original email or part, if not modified, is returned as-is and may not be compliant.
• Although certain parts may have been modified, an original unmodified header from the original email or part may not be compliant.
• A user may set headers in a non-compliant format.

If the part has not been modified and represents a parsed part, the original stream should be written to the file. Otherwise a stream representation of the part including its modifications should be written. This insures that an unmodified, signed message could be passed on this way even after parsing and reading.

The written stream is not guaranteed to be RFC822 (or greater) compliant for the following reasons:

• The original email or part, if not modified, is returned as-is and may not be compliant.
• Although certain parts may have been modified, an original unmodified header from the original email or part may not be compliant.
• A user may set headers in a non-compliant format.

If the passed $filenameResourceOrStream is a string, it's assumed to be a filename to write to.

When passing a resource or Psr7 Stream, the resource is not closed, nor rewound after being written to.

Note that charset conversion is not performed in this case, and the contents of the part are saved in their binary format as transmitted (but after any content-transfer decoding is performed). {@see \IMessagePart::getBinaryContentStream()} for a more detailed description of the stream.

If the passed parameter is a string, it's assumed to be a filename to write to. The file is opened in 'w+' mode, and closed before returning.

When passing a resource or Psr7 Stream, the resource is not closed, nor rewound.

If set, the returned value from {@see \IMessagePart::getCharset()} must be ignored during subsequent read operations and streams created out of this part's content.

Note that setting an override on an {@see \ZBateson\MailMimeParser\IMessage} and calling getTextStream, getTextContent, getHtmlStream or getHtmlContent will not be applied to those sub-parts, unless the text/html part is the IMessage itself. Instead, {@see \ZBateson\MailMimeParser\IMessage::getTextPart()} should be called, and setCharsetOverride called on the returned IMessagePart.