PowerTCP Mail for .NET provides unprecedented stream support for an Internal mail component. Messages themselves are encapsulated by a Stream object (the MessageStream object) as are the various "parts" of a message (such as attachments and text) represented by Stream objects. For example, a MIME attachment is encapsulated by a MimeAttachmentStream object This design gives complete flexibility in representing and moving data, as well as tight integration with the .NET Framework.
Why use the PowerTCP MessageStream object?
The MessageStream object was designed to encapsulate mail messages. The various entities that comprise a mail message (such as headers, attachments, etc) are represented as collections in the MessageStream object. For example, to get a particular header, you can simply access the Header collection. Encoded parts (such as attachments) are automatically decoded on the fly. It is anticipated that most implementations will use the MessageStream object.
Why use other types of Streams?
There may be situations when you need an unaltered representation of a message. For example, you may have an automated process that gets entire messages and saves them to a file for archival purposes. You could employ a .NET Framework FileStream, which would be filled with the unaltered byte representation of the message, and save it to a file. If at some future point you wanted to retrieve and use this message, you could simply "load" it into a MessageStream and use it at that time. As another example, you may have a mail client into which you would like to integrate the ability to show the message source. You could retrieve the message into a MemoryStream and display the message source that way.
Comparison
The following table directly compares the usage and implementation differences of using a MessageStream and that of another type of Stream.
| Using a MessageStream | Using any other type of .NET stream | |
|---|---|---|
| Who creates the Stream object? | The Pop component (typically). | The user (which is then passed into PopMessage.Get). |
| How is encoded data handled? | It is decoded on the fly. | It is not decoded. |
| Message.Message returns. | The MessageStream object representing the message. | null |
| Message.Stream returns. | A Stream object containing message data (which can be cast into a MessageStream object). | A Stream object containing message data (which can be cast into the type of stream originally created by the user). |
| Extra formatting characters (such as the termination sequence <CRLF>.<CRLF>). | Removed. | Removed. |
Example 1: Getting a message into a PowerTCP MessageStream
This first example demonstrates getting a message into a MessageStream object then doing something meaningful with it (in this example, the "Subject" is displayed).
| C# |  Copy Code |
|---|---|
pop1.AutoLogout = false; pop1.AutoGet = MessageSection.None; pop1.Login("mail.test.com", "test", "pass"); // Get a message using the MessageStream object. pop1.Messages[0].Get(); // Now you can use the MessageStream object within your application, like displaying the // "Subject" as in this example. Debug.WriteLine(pop1.Messages[0].Message.Subject); | |
| Visual Basic | Copy Code |
|---|---|
Pop1.AutoLogout = False Pop1.AutoGet = MessageSection.None Pop1.Login("mail.test.com", "test", "pass") ' Get a message using the MessageStream object. Pop1.Messages(0).Get() ' Now you can use the MessageStream object within your application, like displaying the ' "Subject" as in this example. Debug.WriteLine(Pop1.Messages(0).Message.Subject) | |
Example 2: Getting a message into a .NET Framework FileStream
This example demonstrates getting a message into a FileStream object.
| C# | Copy Code |
|---|---|
pop1.AutoClose = false; pop1.AutoGet = MessageSection.None; pop1.Login("mail.test.com", "test", "pass"); // Create the FileStream to be filled. FileStream fstream = new FileStream("C:\\Test\\message.txt", FileMode.Create); // Get a message, passing your FileStream in. pop1.Messages[0].Get(fstream); // Message text should be in specified file. Close the POP connection. pop1.Logout(); | |
| Visual Basic | Copy Code |
|---|---|
Pop1.AutoClose = False Pop1.AutoGet = MessageSection.None Pop1.Login("mail.test.com", "test", "pass") ' Create the FileStream to be filled. Dim fstream As New FileStream("C:\Temp\message.txt", FileMode.CreateNew) ' Get a message, passing your FileStream in. Pop1.Messages(0).Get(fstream) ' Message text should be in specified file. Close the POP connection. Pop1.Logout() | |
In what other ways can Streams be used?
Although the above examples illustrate using Streams to contain the data from a message, Streams can be used other ways as well when using PowerTCP Mail for .NET. For example, attachments contained in a message will typically be decoded and saved (using MimeAttachmentStream.Save). However, perhaps you do not require the attachment to be saved to a disk and you simply want to use the attachment in memory. This can easily be done by setting Pop.UseMemoryStreams to true and attachments will be represented by MemoryStreams, not saved to a file. For a detailed explanation of how to do this, see the topic "Decoding Attachments As Streams".