# Changeset 2656

Ignore:
Timestamp:
Feb 11, 2011, 1:02:48 PM (11 years ago)
Message:

Caesar:

• Removed unnecessary private variables
• Removed OnPropertyChanged calls on input parameters -> currently leads to non-updated quickviews, which is an Editor flaw (Editor should refresh quickview when passing parameters into plugin)
• Updated code comments from Howto

Plugin Howto:

• Updated code snippets from Caesar plugin
• Removed full Caesar example in appendix (totally out-of-sync with actual source code, it's better to grab the current version online from trunk)
• Removed obsolete x64 note
• Removed self-adulation from abstract
• Added wiki reference to abstract
• Increased version to 0.7
Location:
trunk
Files:
2 deleted
6 edited

Unmodified
Removed
• ## trunk/CrypPlugins/Caesar/Caesar.cs

 r1636 \author{S.\ Przybylski, A.\ Wacker, M.\ Wander, F.\ Enkler and P.\ Vacek} \email{\{przybylski$|$wacker$|$wander$|$enkler$|$vacek\}@cryptool.org} \version{0.6} \version{0.7} \date{\today} \begin{abstract} CrypTool 2 is the modern successor of the well-known e-learning platform for cryptography and cryptanalysis \htmladdnormallink{CrypTool 1}{http://www.cryptool.org/}, which is used worldwide for educational purposes at schools and universities as well as in companies and agencies. CrypTool~2 is the successor of the well-known e-learning platform for cryptography and cryptanalysis CrypTool\footnote{\url{http://www.cryptool.org/}}, which is used for educational purposes at schools and universities as well as in companies and agencies. As of January 2010, CrypTool~2 consists of over 7000 lines of C\# code in the core application and over 250,000 lines of C\# code in about 100 plugins. Since the first launch of CrypTool 1 in 1999 the art of software development has changed dramatically. The CrypTool 2 team began working in 2008 to develop a completely new e-learning application, embracing the newest trends in both didactics and software architecture to delight the end-user with an entirely new experience.\\ To reach these goals, CrypTool 2 is built using the following: CrypTool~2 is built using the following technologies and development tools: \begin{itemize} \item .NET (a modern software framework from Microsoft with solutions to common programming problems) \item C\# (a modern object-oriented programming language, comparable to Java) \item WPF (a modern purely vector-based graphical subsystem for rendering user interfaces in Windows-based applications) \item Visual Studio 2010 (a development environment) \item WPF (a modern vector-based graphical subsystem for rendering user interfaces in Windows-based applications) \item Visual Studio 2010 (a development environment) \item Subversion (a source code and documentation version management system) \item trac (a lightweight web-based software project management system) \end{itemize} This document is intended for plugin developers who want to contribute new visual or mathematical functionality to CrypTool 2. As of January 2010, the program consists of over 7000 lines of C\# code in the core application and over 250,000 lines of C\# code in about 100 plugins. For further information, please visit the CrypTool 2 website at \htmladdnormallink{http://www.cryptool2.vs.uni-due.de}{http://www.cryptool2.vs.uni-due.de}. This document is intended for plugin developers who want to contribute a new plugin to CrypTool~2 which implements a cryptographic algorithm or similar functionality. Please note that CrypTool~2 is an alive project in development. Certain information may be outdated or missing. If you want to stay up-to-date, we recommend checking out the CrypTool~2 development wiki\footnote{\url{https://www.cryptool.org/trac/CrypTool2/wiki}} and website\footnote{\url{http://cryptool2.vs.uni-due.de/}}. \end{abstract} \include{part1} \include{part2} \begin{appendix} \include{appendix} \end{appendix} \end{document}
 r1636 \label{CompilingTheSourcesVS} By this point you should have checked out a copy of the entire CrypTool~2 repository. Compiling is pretty easy; just go to the \texttt{trunk\textbackslash} directory and open the \textbf{\textit{CrypTool 2.0.sln}} Visual Studio solution. The Visual Studio IDE should open with all the working plugin components nicely arranged. If you are now starting Visual Studio for the first time, you will have to choose your settings. Just select either \textit{most common} or \textit{C\#} --- you can change this at any time later. On the right side is the project explorer, where you can see all the subprojects included in the solution. Look for the project \textbf{\textit{CrypStartup}} there and make sure it is selected as startup project (right-click on it and select \textit{Set as StartUp Project} from the context menu). Next, go to the menu bar and make sure the target platform is set correctly (Figure~\ref{fig:vs_menubar_x86}). If your operating system is a 32 bit installation, you have to select \textbf{x86}. If you have a 64 bit operating system, you may use one of both, x64 or x86. If in doubt, select x86. Then click \textit{Build $\rightarrow$ Build Solution} in the menubar to start the build process. \begin{figure}[htbp] \centering \includegraphics{figures/vs_menubar_x86.png} \caption{Selecting x86 as target platform.} \label{fig:vs_menubar_x86} \end{figure} \clearpage By this point you should have checked out a copy of the entire CrypTool~2 repository. Compiling is pretty easy; just go to the \texttt{trunk\textbackslash} directory and open the \textbf{\textit{CrypTool 2.0.sln}} Visual Studio solution. The Visual Studio IDE should open with all the working plugin components nicely arranged. If you are now starting Visual Studio for the first time, you will have to choose your settings. Just select either \textit{most common} or \textit{C\#} --- you can change this at any time later. On the right side is the project explorer, where you can see all the subprojects included in the solution. Look for the project \textbf{\textit{CrypStartup}} there and make sure it is selected as startup project (right-click on it and select \textit{Set as StartUp Project} from the context menu). Then click \textit{Build $\rightarrow$ Build Solution} in the menubar to start the build process. You may have to wait a while for the program to compile. Once it is finished, select \textit{Debug $\rightarrow$ Start Debugging}. CrypTool 2 should now start for the first time with your own compiled code. Presumably you have not changed anything yet, but you now have your own build of all the components (with the exception of \textit{CrypWin} and \textit{AnotherEditor}, since they are available only as binaries). If the program does not compile or start correctly, please consult our \href{https://www.cryptool.org/trac/CrypTool2/wiki/FAQ}{FAQ} and let us know if you found a bug.
 r2320 \item \textit{Cryptool.PluginBase.Editor} --- contains interfaces for editors that can be implemented in CrypTool 2, such as the default editor. \item \textit{Cryptool.PluginBase.Generator} --- contains interfaces for generators, including the random input generator. \item \textit{Cryptool.PluginBase.IO} --- contains interfaces for input, output and the \textit{CryptoolStream}. \item \textit{Cryptool.PluginBase.IO} --- contains interfaces for input, output and the \textit{ICryptoolStream}. \item \textit{Cryptool.PluginBase.Miscellaneous} --- contains assorted helper classes, including \textit{GuiLogMessage} and \textit{PropertyChanged}. \item \textit{Cryptool.PluginBase.Resources} --- used only by CrypWin and the editor; not necessary for plugin development. \item \textit{Cryptool.PluginBase} --- to implement \textit{ISettings} in the CaesarSettings class. \item \textit{Cryptool.PluginBase.Cryptography} --- to implement \textit{IEncryption} in the Caesar class. \item \textit{Cryptool.PluginBase.IO} --- to use CryptoolStream for data input and output. \item \textit{Cryptool.PluginBase.IO} --- to use ICryptoolStream for data input and output. \item \textit{Cryptool.PluginBase.Miscellaneous} --- to use the CrypTool event handler. \end{itemize} \label{sec:DefiningThePrivateVariablesOfTheSettingsInTheCaesarClass} The next step is to define some private variables that are needed for the settings, input, and output data. In our example, this will look like the following: \begin{lstlisting} #region Private variables private CaesarSettings settings; private string inputString; private string outputString; private enum CaesarMode { encrypt, decrypt }; private List listCryptoolStreamsOut = new List(); The next step is to define some private class elements. In our example, this will look like the following: \begin{lstlisting} #region Private elements private CaesarSettings settings; // required to implement the IPlugin interface properly private enum CaesarMode { encrypt, decrypt }; // nested enum, used to select either encryption or decryption #endregion \end{lstlisting} \ \\ % ugly but functional If your algorithm deals with long strings of code, it is recommended to use the \textit{CryptoolStream} data type. This was designed for input and output between plugins and to handle large amounts of data. To use the native CrypTool stream type, include the namespace \textit{Cryptool.PluginBase.IO} with a \texttt{using} statement as explained in Section \ref{sec:ImportingCrypPluginBaseNamespaces}. Our example makes use of the following private variables: \begin{itemize} \item \texttt{CaesarSettings settings} --- required to implement the IPlugin interface properly. \item \texttt{string inputString} --- string from which to read the input data. \item \texttt{string outputString} --- string to which to save the output data. \item \texttt{enum CaesarMode} --- used to select either encryption or decryption. \item \texttt{List$<$CryptoolStream$>$ listCryptoolStreamsOut} --- a list of all streams created by the plugin, which helps to perform a clean dispose. \end{itemize} \ \\ If your algorithm deals with potentially large data amounts, it is recommended to use the \textit{ICryptoolStream} data type. More information about how to use the \textit{ICryptoolStream} can be found in the CrypTool 2 wiki: \url{https://www.cryptool.org/trac/CrypTool2/wiki/ICryptoolStreamUsage}. You will need to include the namespace \textit{Cryptool.PluginBase.IO} with a \texttt{using} statement as explained in Section \ref{sec:ImportingCrypPluginBaseNamespaces}. \subsection{Adding controls to the CaesarSettings class} public string InputString { get { return this.inputString; } set { if (value != inputString) { this.inputString = value; OnPropertyChanged("InputString"); } } get; set; } \end{lstlisting} public string OutputString { get { return this.outputString; } set { outputString = value; OnPropertyChanged("OutputString"); } get; set; } \end{lstlisting} \begin{lstlisting} [PropertyInfo(Direction.OutputData, "CryptoolStream output", "The raw CryptoolStream data after processing with the Caesar cipher", "", false, false, QuickWatchFormat.Text, null)] public CryptoolStream OutputData { get { if (outputString != null) public ICryptoolStream OutputData { get { CryptoolStream cs = new CryptoolStream(); listCryptoolStreamsOut.Add(cs); cs.OpenRead(Encoding.Default.GetBytes(outputString.ToCharArray())); return cs; if (OutputString != null) { return new CStreamWriter(Encoding.Default.GetBytes(OutputString)); } return null; } else { return null; } } set { } } set { if (value != settings.ShiftKey) { settings.ShiftKey = value; } } } { case 0: GuiLogMessage("Encrypting", NotificationLevel.Debug); ProcessCaesar(CaesarMode.encrypt); break; case 1: GuiLogMessage("Decrypting", NotificationLevel.Debug); ProcessCaesar(CaesarMode.decrypt); break; \end{lstlisting} It is important to make sure that all changes to the output properties will be announced to the CrypTool 2 environment. In our example this happens by calling the set method of \textit{OutputData}, which in turn calls \textit{OnPropertyChanged} to indicate that both output properties \textit{OutputData} and \textit{OutputDataStream} have changed. Instead of calling the property's set method you could instead call \textit{OnPropertyChanged} directly within the \textit{Execute()} method. It is important to make sure that all changes to the output properties will be announced to the CrypTool 2 environment. Therefore we call \textit{OnPropertyChanged} on both changed output properties \textit{OutputString} and \textit{OutputData}. \subsection{Sending messages to the CrypTool 2 core} \label{sec:SendingMessagesToTheCrypTool2Core} The CrypTool 2 API provides three methods to send messages from the plugin to the CrypTool 2 core. \textit{GuiLogMessage} is used to send messages to the CrypTool 2 status bar. This method is a nice mechanism to inform the user as to what your plugin is currently doing. \textit{OnPropertyChanged} is used to inform the core application of changes to any data output properties. This is necessary for a correct plugin execution. \textit{ProgressChanged} is used to visualize the progress of the algorithm as a bar. The CrypTool 2 API provides three methods to send messages from the plugin to the CrypTool 2 core. \textit{GuiLogMessage} is used to send messages to the CrypTool 2 status bar. This method is a mechanism to inform the user as to what your plugin is currently doing. \textit{OnPropertyChanged} is used to inform the core application of changes to any data output properties. This is necessary for a correct plugin execution. \textit{ProgressChanged} is used to visualize the progress of the algorithm as a bar. \begin{figure}[h] \end{itemize} \subsection{Performing a clean dispose} \label{sec:PerformingACleanDispose} Be sure you have closed and cleaned all your streams after execution before CrypTool 2 decides to dispose the plugin instance. There has been some misunderstanding about the meaning of \textit{Dispose()}. Dispose will be called ultimately before object destruction. After disposal, the object will be in an undefined state. \begin{lstlisting} public void Dispose() { foreach(CryptoolStream stream in listCryptoolStreamsOut) { stream.Close(); } listCryptoolStreamsOut.Clear(); } \end{lstlisting} \section{Drawing the workflow of your plugin} \label{DrawingTheWorkfloweOfYourPlugin}