[Anet-checkins] CVS: Documentation/design/latex anet.bib,1.1,1.2 anetdesign.tex,1.2,1.3

[Christopher J. <cwj...@us...>]

Update of /cvsroot/anet/Documentation/design/latex
In directory usw-pr-cvs1:/tmp/cvs-serv31460

Modified Files:
	anet.bib anetdesign.tex 
Log Message:
added third section, fixed formating a bit

Index: anet.bib
===================================================================
RCS file: /cvsroot/anet/Documentation/design/latex/anet.bib,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** anet.bib	2001/12/29 00:40:29	1.1
--- anet.bib	2002/01/02 20:40:36	1.2
***************
*** 19,23 ****
  
  
! @Misc{macmem,
    OPTkey =       {},
    OPTauthor =    {},
--- 19,23 ----
  
  
! @Misc{applemem,
    OPTkey =       {},
    OPTauthor =    {},
***************
*** 42,44 ****
--- 42,99 ----
  }
  
+ 
+ @Misc{uscip,
+   OPTkey =       {},
+   OPTauthor =    {},
+   title =     {University of Southern California, ``Internet Protocol''},
+   howpublished = {\url"http://www.ietf.org/rfc/rfc0791.txt"},
+   OPTmonth =     {},
+   OPTyear =      {},
+   OPTnote =      {},
+   OPTannote =    {}
+ }
+ 
+ @Misc{applehyp,
+   OPTkey =       {},
+   OPTauthor =    {},
+   title =     {Apple: HyperCard},
+   howpublished = {\url"http://www.apple.com/hypercard/"},
+   OPTmonth =     {},
+   OPTyear =      {},
+   OPTnote =      {},
+   OPTannote =    {}
+ }
+ 
+ @Misc{fsftar,
+   OPTkey =       {},
+   OPTauthor =    {},
+   title =     {Free Software Foundation: ``tar''},
+   howpublished = {\url"http://www.gnu.org/software/tar/tar.html"},
+   OPTmonth =     {},
+   OPTyear =      {},
+   OPTnote =      {},
+   OPTannote =    {}
+ }
+ 
+ @Misc{nwgmime,
+   OPTkey =       {},
+   OPTauthor =    {},
+   title =     {Networking Working Group: ``Multipurpose Internet Mail Extensions''},
+   howpublished = {\url"http://www.ietf.org/rfc/rfc2045.txt,rfc2046.txt,rfc2047.txt, rfc2048.txt, rfc2049.txt"},
+   OPTmonth =     {},
+   OPTyear =      {},
+   OPTnote =      {},
+   OPTannote =    {}
+ }
+ 
+ @Misc{nwgmimec,
+   OPTkey =       {},
+   OPTauthor =    {},
+   title =     {Network Working Group: ``MIME Content Type for BinHex Encoded Files''},
+   howpublished = {\url"http://www.ietf.org/rfc/rfc1741.txt"},
+   OPTmonth =     {},
+   OPTyear =      {},
+   OPTnote =      {},
+   OPTannote =    {}
+ }
  

Index: anetdesign.tex
===================================================================
RCS file: /cvsroot/anet/Documentation/design/latex/anetdesign.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** anetdesign.tex	2002/01/01 18:46:10	1.2
--- anetdesign.tex	2002/01/02 20:40:36	1.3
***************
*** 21,25 ****
  %=====================================================================%
  
! \documentclass[letterpaper]{article}
  \usepackage{latexsym}   % Use special symbols.
  \usepackage{makeidx}    % Make an index.
--- 21,25 ----
  %=====================================================================%
  
! \documentclass[letterpaper,titlepage]{article}
  \usepackage{latexsym}   % Use special symbols.
  \usepackage{makeidx}    % Make an index.
***************
*** 57,61 ****
  \newcommand{\la}{\mathopen{<}} \newcommand{\ra}{\mathopen{>}}
  
! %environment used for the DTD's
  \newsavebox{\fmbox}
  \newenvironment{fmpage}[1]
--- 57,67 ----
  \newcommand{\la}{\mathopen{<}} \newcommand{\ra}{\mathopen{>}}
  
! % trying to add the part command
! %\newcounter{partnum}
! %\newcommand{\part}[1]{\clearpage\thispagestyle{empty}%
! %\refstepcounter{partnum}\addcontentsline{toc}{partnum}{#1}%
! %\Huge{Part}}
! 
! % environment used for the DTD's
  \newsavebox{\fmbox}
  \newenvironment{fmpage}[1]
***************
*** 85,89 ****
  \begin{document}
  \maketitle
- \clearpage
  \pagenumbering{roman}
  \tableofcontents
--- 91,94 ----
***************
*** 97,100 ****
--- 102,106 ----
  \clearpage
  \pagenumbering{arabic}
+ \part{High Level Design} \label{part:hld}
  This is the High-Level Design for ANet.  It presents a non-technical
  view of the different components of ANet, how they work, how they
***************
*** 200,205 ****
  system:
  \begin{description}
!        \item[Files]: create, open, read, write, close and delete.
!        \item[Directories]: create, read, delete
  \end{description}
  Once opened, files and directories are identified by an ID.  The files
--- 206,211 ----
  system:
  \begin{description}
! \item[Files]: create, open, read, write, close and delete.
! \item[Directories]: create, read, delete
  \end{description}
  Once opened, files and directories are identified by an ID.  The files
***************
*** 207,213 ****
  of paths:
  \begin{description}
!        \item[UNIX] \verb|/directory/directory/.../file.| \\Up one directory: ..
!        \item[MacOS] \verb|Disk:folder:folder:...:file.| \\Up one directory: ::
!        \item[Win32] \verb|Disk:\directory\directory\...\file.ext.|\\Up one directory: ..
  \end{description}
  
--- 213,219 ----
  of paths:
  \begin{description}
! \item[UNIX] \verb|/directory/directory/.../file.| \\Up one directory: ..
! \item[MacOS] \verb|Disk:folder:folder:...:file.| \\Up one directory: ::
! \item[Win32] \verb|Disk:\directory\directory\...\file.ext.|\\Up one directory: ..
  \end{description}
  
***************
*** 215,229 ****
  that ANet will support, with the following restrictions:
  \begin{description}
!        \item Win32 systems assume that there is a file extension.  If
  none is given, a generic one will be added when the file is created.
  The generic file extension for ANet can be changed in the
  configuration files.
!        \item The ``Disk'' part of the Win32 paths will be ignored on
  UNIX systems, except Mac OS X.
!        \item On Mac OS 9, the file type and creator will be based on
  the file name extension.  If the extension is missing, a generic
  type/creator pair will be given to the file when created.  The default
  pair can be changed in the configuration file.
!        \item Files and directories will be created with the default
  access privileges, which can be changed in the configuration file.
  \end{description}
--- 221,235 ----
  that ANet will support, with the following restrictions:
  \begin{description}
! \item Win32 systems assume that there is a file extension.  If
  none is given, a generic one will be added when the file is created.
  The generic file extension for ANet can be changed in the
  configuration files.
! \item The ``Disk'' part of the Win32 paths will be ignored on
  UNIX systems, except Mac OS X.
! \item On Mac OS 9, the file type and creator will be based on
  the file name extension.  If the extension is missing, a generic
  type/creator pair will be given to the file when created.  The default
  pair can be changed in the configuration file.
! \item Files and directories will be created with the default
  access privileges, which can be changed in the configuration file.
  \end{description}
***************
*** 361,368 ****
  themselves, entire clients. Downwards \xs{sec:rtw}, they receive
  commands\footnote{This what inspired by HyperTalk, the programming
! language of HyperCard\cite{applehyp}. Here's an example: ask "What is your name?"
! if the result is "Benad" then answer "Wow! I have the same name!"
! Here, "ask" and "answer" are commands, while "the result" is a
! function and "is" is an operator. This is not a joke!  } from the
  clients and they transfer them downwards in the daemon. Upwards
  \xs{sec:rtw}, they receive relevent data from the rest of the daemon
--- 367,374 ----
  themselves, entire clients. Downwards \xs{sec:rtw}, they receive
  commands\footnote{This what inspired by HyperTalk, the programming
! language of HyperCard\cite{applehyp}. Here's an example: ask ``What is
! your name?''  if the result is "Benad" then answer ``Wow! I have the
! same name!''  Here, ``ask'' and ``answer'' are commands, while ``the result''
! is a function and ``is'' is an operator. This is not a joke!  } from the
  clients and they transfer them downwards in the daemon. Upwards
  \xs{sec:rtw}, they receive relevent data from the rest of the daemon
***************
*** 403,407 ****
  
  \begin{description}
! \item[Register/Unregister service] Given some service number, it
  registers that service for its calling module instance. You can also
  unregister some service you don't want to use anymore. If you pass a
--- 409,414 ----
  
  \begin{description}
! \item[Register/Unregister service]
! Given some service number, it
  registers that service for its calling module instance. You can also
  unregister some service you don't want to use anymore. If you pass a
***************
*** 411,425 ****
  command will be ignored except the next ``unregister all services''
  command.
! \item[Send packet] Sends an ANet packet, query[3] or static data[4],
  to the ANet network. The cluster group[5] where the packet will be
  sent has to be specified. Use the "Get Config" command (read below) to
  know which cluster groups you can use. The format of the "internal
  ANet packet" will be described in "Cluster Group Modules"[5].
! \item[Get Status] Will make the ANet daemon return a packet describing
  its current status. The contents of this packet will be implementation
  specific and outside the scope of the high-level design, though it
  will contain enough relevant information to let the user know what's
  going on in the daemon.
! \item[Get Status - Start/Stop polling] From the time the daemon gets
  the "Start Polling" command to the time it gets the "Stop Polling"
  command, the daemon will regularly send status packets the the client
--- 418,438 ----
  command will be ignored except the next ``unregister all services''
  command.
! 
! \item[Send packet]
! Sends an ANet packet, query[3] or static data[4],
  to the ANet network. The cluster group[5] where the packet will be
  sent has to be specified. Use the "Get Config" command (read below) to
  know which cluster groups you can use. The format of the "internal
  ANet packet" will be described in "Cluster Group Modules"[5].
! 
! \item[Get Status]
! Will make the ANet daemon return a packet describing
  its current status. The contents of this packet will be implementation
  specific and outside the scope of the high-level design, though it
  will contain enough relevant information to let the user know what's
  going on in the daemon.
! 
! \item[Get Status -- Start/Stop polling]
! From the time the daemon gets
  the "Start Polling" command to the time it gets the "Stop Polling"
  command, the daemon will regularly send status packets the the client
***************
*** 429,438 ****
  status packets, though if that value is too small, the command will be
  ignored.
! \item[Get Static Data] Given a primary and/or the secondary key, this
  will make ANet return all the static packets currectly stored locally
  that matches the key (or keys).
! \item[Change/Delete Static Data] Those commands will allow the module
  to change or delete some static packets currently stored locally.
! \item[Open TWDTC] Given the protocol, the ``unique address'' and the
  "subnet" of the other node, ANet will try to establish a Two-Way Data
  Transfer [3] Channel (TWDTC) to the other node through the network. If
--- 442,457 ----
  status packets, though if that value is too small, the command will be
  ignored.
! 
! \item[Get Static Data]
! Given a primary and/or the secondary key, this
  will make ANet return all the static packets currectly stored locally
  that matches the key (or keys).
! 
! \item[Change/Delete Static Data]
! Those commands will allow the module
  to change or delete some static packets currently stored locally.
! 
! \item[Open TWDTC]
! Given the protocol, the ``unique address'' and the
  "subnet" of the other node, ANet will try to establish a Two-Way Data
  Transfer [3] Channel (TWDTC) to the other node through the network. If
***************
*** 442,456 ****
  know what's going on.  ANet will return a packet containing an ID that
  can be used to identify the TWDTC with the other TWDTC commands.
! \item[Read/Write TWDTC] Read or write some data in the TWDTC. This is
  similar to reading or writing data in a TCP socket.
! \item[Close TWDTC] Given an open TWDTC ID\footnote{If you know what
  "TWDTC ID" means, then you're ready to be a developer for ANet!},
  closes the identified channel.
! \item[Get Config] Returns the readeable tags in the configuration
  files \xs{sec:rtw}. Each tag in the configuration files can have
  access rights, that is read, write or both. If specified, it affects
  the tag, and recursively overwriting the access rights of the tags it
  contain. Otherwise, they remain to their default value.
! \item[Change Config] Allows the client connection module to change
  tags in the configuration file, it it has the right to do so. The
  change can be saved to the hard disk, instead of being temporary, if
--- 461,483 ----
  know what's going on.  ANet will return a packet containing an ID that
  can be used to identify the TWDTC with the other TWDTC commands.
! 
! \item[Read/Write TWDTC]
! Read or write some data in the TWDTC. This is
  similar to reading or writing data in a TCP socket.
! 
! \item[Close TWDTC]
! Given an open TWDTC ID\footnote{If you know what
  "TWDTC ID" means, then you're ready to be a developer for ANet!},
  closes the identified channel.
! 
! \item[Get Config]
! Returns the readeable tags in the configuration
  files \xs{sec:rtw}. Each tag in the configuration files can have
  access rights, that is read, write or both. If specified, it affects
  the tag, and recursively overwriting the access rights of the tags it
  contain. Otherwise, they remain to their default value.
! 
! \item[Change Config]
! Allows the client connection module to change
  tags in the configuration file, it it has the right to do so. The
  change can be saved to the hard disk, instead of being temporary, if
***************
*** 482,489 ****
  \end{figure}
  
! % References
! 
! % About the references...
! 
  % [1] Benad: "Run-Time Wrapper". Local link.
  % [2] University of Southern California , "Internet Protocol". External link. Cached.
--- 509,513 ----
  \end{figure}
  
! % maybe add a glossary
  % [1] Benad: "Run-Time Wrapper". Local link.
  % [2] University of Southern California , "Internet Protocol". External link. Cached.
***************
*** 496,501 ****
  
  \section{Data Transformation Modules} \label{sec:dtm}
! Transform some data.
  
  \section{Client SDK} \label{sec:csdk}
  Group of libraries to simplify the process of building clients for
--- 520,598 ----
  
  \section{Data Transformation Modules} \label{sec:dtm}
! The data transformation modules are use to change data in various
! ways, such as encryption and compression.
  
+ \subsection{Design}
+ The goal of the Data Transformation modules is to change some data
+ into another form. Their most common use is compression and
+ decompression, but they can also be used for encryption, or for any
+ other function that has an inverse function\footnote{Actually, it
+ could be used for things like tar\cite{fsftar}, MIME\cite{nwgmime},
+ binhex\cite{nwgmimec}, or anything you can think of. Also, the input
+ data for a transformation function could point to something outside
+ the deamon, for example a database or the hard disk. So, it could be
+ used to generate, if this is what you need.}.
+ 
+ The data can be identified by a ``format'' tag. This 4-bytes value
+ identifies the kind of data once it has been transformed. The "NULL"
+ value identifies data that has not been transformed yet. The
+ transformation function for each format use the input data as if it
+ was untransformed data. Thus, the format tag has to be stored with the
+ data before it is transformed to another kind of data\footnote{That
+ is, you should store the previous format tag in a place that you can
+ retrieve it once the data will be decoded back. Obviously, that's not
+ needed if you assume that you're working with untransformed data.}.
+ 
+ One instance is created for each Data Transform Module. Its
+ initialization function should return a list of what format tags it
+ supports, with both the actual, 4-byte tag and a Human-readable
+ string, to make it easier to make the configuration file. It is
+ assumed that for each supported format tag, both "transform to" and
+ ``transform from'' functions are supported. Only one function is needed
+ for each module, as the function will be passed the format tag, the
+ "transformation direction" and a memory tag \xs{sec:rtw} that points to the
+ data.
+ 
+ Since some transformation functions might need to have additionnal
+ ``contextual'' information, such as compression level or encryption
+ settings, they can accept a fourth argument, which is a memory tag
+ that refers to the additional information.
+ 
+ The run-time wrapper will allow all modules to call any data
+ transformation function. If you need any kind of security system, it
+ has to be implemented within the data transformation module.
+ 
+ \subsection{Implementation Notes}
+ I think that relying on Inter-Module Communication for calling Data
+ Transformation functions would be too complex. The run-time wrapper
+ could have a single ``TrasformData'' function, to which you give all the
+ needed data, without having to care to which module it relates to.  If
+ two different modules can support the same format tag, than the one
+ that will be used is undefined. So, if the data format could be
+ implemented into various versions, it is recommended to store the
+ version in the format tag itself\footnote{Please try to make your
+ module ``fowards-compatible''. If you always use the same format tag
+ accross versions, then it will be impossible to install two different
+ versions of your module at the same time, which might be needed if
+ your module is not backwards-compatible or if the latest version
+ introduces new bug (don't worry, it always happen).}. Note that both
+ the tag itself and its corresponding Human-readable string should be
+ unique.
+ 
+ \subsection{DTD}
+ See the complete DTD for more information.
+ \begin{figure}[!h]
+ \begin{fmpage}{\textwidth}
+ \begin{verbatim}
+ <!-- Data Transformation Module. Data Transformation Modules will be used
+ in ascending order of "order" for output (to the network), in descending
+ order for input (from the network). -->
+ <!ELEMENT DataTransform EMPTY>
+ <!ATTLIST DataTransform %moduleName; %args; %security; %security; order CDATA "-1">
+ \end{verbatim}
+ \end{fmpage}
+ \caption{The Data Transformation Module DTD} \label{fig:dtmdtd}
+ \end{figure}
+ 
  \section{Client SDK} \label{sec:csdk}
  Group of libraries to simplify the process of building clients for
***************
*** 529,532 ****
--- 626,631 ----
  This is the DTD file for the ANet configuration files.
  
+ \clearpage
+ \part{Low Level Design}
  \clearpage
  \pagenumbering{roman}