wiki:ICryptoolStreamUsage

Version 3 (modified by Matthäus Wander, 12 years ago) (diff)

finished usage

CStream is a replacement for the now obsolete CryptoolStream class. With CStream a plugin can pass data as byte stream to other plugins.

Features:

  • Supports 0..n concurrent readers on one CStream
  • Clean separation between writer and reader -- reading plugins can't disturb the writing plugin or other reading instances
  • Does not forget data -- new readers can be created at any time and support random seeking
  • Uses internal byte array as underlying buffer and switches automagically to a temporary file, if data exceeds a certain size
  • Supports the .NET Dispose pattern, but does not require you to use it -- the garbage collector will clean up for you
  • Supports chunked streaming -- receivers can read and process data even if the sender has not finished writing

How to use CStreamWriter

source:/trunk/Documentation/Developer/CStream/CStreamWriter.png

  • Create an output property (e.g. called "OutputStream") with type CStream
  • In Execute() create a new CStreamWriter
  • Get the CStreamWriter.CStream property and set it as your OutputStream property
  • Announce the OutputStream update with OnPropertyChanged("OutputStream")
  • Pass data to the stream via CStreamWriter.Write()
  • Call CStreamWriter.Close() when finished
  • Best practice is to not care about disposal of a writer.
public class PluginA
{
	public CStream OutputStream
	{
		get;
		private set;
	}
	
	public void Execute()
	{
		CStreamWriter writer = new CStreamWriter();
		OutputStream = writer.CStream;
		OnPropertyChanged("OutputStream");
		
		while(condition)
		{
			byte[] data = GenerateData();
			writer.Write(data);
		}
		
		writer.Close();
	}
}

How to use CStreamReader

source:/trunk/Documentation/Developer/CStream/CStreamReader.png

  • Create an input property (e.g. called "InputStream") with type CStream
  • In Execute() call CreateReader() on that CStream to get a new CStreamReader
  • Retrieve data with CStreamReader.Read() in a loop
  • End loop when read attempt returns 0 bytes
  • Best practice is to Dispose() the CStreamReader afterwards.
public class PluginB
{
	public CStream InputStream
	{
		get;
		set;
	}
	
	public void Execute()
	{
		// The "using" keywords asserts that CStreamReader.Dispose() will be called
		using (CStreamReader reader = InputStream.CreateReader())
		{
			int bytesRead;
			byte[] buffer = new byte[ANY_SIZE];
			
			while ((bytesRead = reader.Read(buffer)) > 0)
			{
				// Note: buffer can contain less data than buffer.Length, therefore consider bytesRead
				processData(buffer, bytesRead);
			}
		}
	}
}