/*     
**      Newton Developer Technical Support Sample Code
**
**      ArchiveTransport, a Newton 2.x transport example
**
**      by Ryan Robertson and J. Christopher Bell, Newton Developer Technical Support
**         Using protoFSM (finite state machine) by Jim Schram
**
**      Copyright © 1994-7 by Newton, Inc.  All rights reserved.
**
**      You may incorporate this sample code into your applications without
**      restriction.  This sample code has been provided "AS IS" and the
**      responsibility for its operation is 100% yours.  You are not
**      permitted to modify and redistribute the source as "DTS Sample Code."
**      If you are going to re-distribute the source, we require that you
**      make it clear in the source that the code was descended from
**      Newton, Inc.-provided sample code, but that you've made changes.
*/

This sample shows the basics of sending and receiving via transports, with
its communication based on protoBasicEndpoint and protoFSM (finite state machine).

ArchiveTransport sends and receives frames (its dataTypes slot value is
['frame]). Any application conforming to the Newton 2.0 Routing API can
indicate that its formats can route data of type 'frame by registering a
protoFrameFormat object on a certain data class. Such applications will be able
to use ArchiveTransport, including all built-in applications plus the DTS
sample code "CustomRoute". See the CustomRoute sample and the Newton
Programmers Guide Routing chapter for more information.

During 'send', ArchiveTransport hides the I/O Box data in its private soup. To
'receive', ArchiveTransport retrieves all available items from its private
soup, and then submits them to the In Box.

For illustrative purposes, the transport uses To: and cc: entry fields similar
to an email transport, even though these fields ARE NOT USED in this transport.

The basics of a transport are in the SendRequest and ReceiveRequest methods.

In this case, we are trying to simulate the asychronous nature of
communications code (see the Communications chapter of the NPG 2.0 for more
info).  The communications code is based on ProtoFSM (finite state machine)
that was created by Jim Schram of Newton DTS.

WARNING: The communications code finite state machine is NOT discussed in this
sample. For information about how to write code based on the protoFSM proto,
see the April, 1996 (Volume II, Number 2) NTJ article titled "Finite-State
Machines: A Model for Newton Communications". Also see the DTS sample code
"Comms FSM" and "protoFSM" for the most recent version of this proto and more
information about how it works.

=== What to look for in this sample

Here is a road map of the important methods and slots to look at. The methods with
asterisks are overrided transport methods; the rest are specific to this implementation
of the transport.

In Endpoint
	Output - the actual "sending" to the temp soup
	Input - the "receiving" from the temp soup
	
In ConnectionFSM
	Connected State
		Output Data event
		Input Data event
		
In RoutingSlip.t
	*PrepareToSend
	
In Transport
	*CancelRequest
	*ReceiveRequest
	*SendRequest
	DisposeFSM
	GetArchiveSoup
	GoGoGadgetBarberPole
	
Also read the BeforeScript of each layout for more information about that file.

CHANGE HISTORY:

v4
*	Added a checkbox to control the auto-putaway behavior.  This preference is only available in Newton 2.1 OS and higher.  The code checks the version of the OS before adding the auto-putaway preference.
	
Ryan Robertson, Newton DTS