/*   
**      Newton Developer Technical Support Sample Code
**
**      MinMail, a Newton 2.x transport example
**
**      by J. Christopher Bell and Ryan Robertson, Newton Developer Technical Support
**
**      Copyright © 1996-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 & receiving with a text mail transport.

MinMail sends and receives text only. In other words, the dataTypes slot is
['text]. It does not send attachments in addition to text.

During 'send', MinMail hides the I/O Box data in a private soup.
To 'receive', MinMail 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 in the
routing slip, but these fields are NOT used when "sending" with this
transport.

** WHERE THE TRANSPORT CODE IS

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

Most REAL transports process only one item at a time, using :ItemRequest() to
get the next item. Most REAL transports will also use communication endpoints
to send the items one at a time. Most REAL transports will use
protoStatusTemplate to show the status of "sending". Most REAL transports send
each item asynchronously (letting the user continue working). This example
merely sends all the items quickly, and receives them quickly, with no user
interface.

See the "ArchiveTransport" sample (version 2 or higher) for a more realistic
example of how most transports will handle endpoints and status dialogs.

Most of the work is done in the SendRequest and ReceiveRequest methods.
However, there is important code in NewItem (to handle "from" information) and
the routing slip PrepareToSend (to set up the item to send). 

** WHERE THE ITEMTOTEXT CODE IS

An important thing to note about text transports is that the transport store the
text in a frame with the structure {class: 'text, text: "the string..."}. 
Transports should NOT create strings and just put them in the body slot (and 
definitely NOT the item.text slot like the 1.x eWorld transport did).
The most reliable way of getting text into this format is to use ItemToText. 

The ItemToText function (in the Newton 2.x platform file as kItemToTextFunc) is
called in four different functions/methods in this sample. Using ItemToText in
ALL FOUR PLACES is required to ensure that items are properly converted to
text when used with application overviews and when used with the Send
function.


ItemToText

returns: nil, 'ink, 'error, or an error number
if the return value is nil, it completed successfully (or the item was
already converted) if the return value is 'ink, it completed
successfully, but the item.title and/or item.text slots now contain rich
strings rather than plain text. It is up to the transport to convert ink
appropriately. if exceptions occur during text export, the error will be
returned as a return value or the value 'error if the error number could
not be determined.

arguments:
  item: the iobox item
target: the target, if available. If the item came from a transport
     :itemRequest() call, pass item.body here. It is used by the format
textscript
  transportSym: the transport symbol (no transport group symbols)
  isTextOnly: *THIS MUST BE SET TO TRUE* in this version of the function. 
              This will change later.
  noDefaultInkConvert: 
   if true, does not convert rich strings and instead returns the 'ink
   return value so that the transport can present a user interface for
   conversion. if nil, converts ink words to some default (currently
   "-ink", but that could change) text
   
Use this function in your transport in all of these situations:
  * routingslip.PrepareToSend (but *not* if IsTargetCursor(item.body))
  * transport:VerifyRoutingInfo(...) -- see the test transport for details.
  * SendRequest - related "sending" methods 
  * Any other time you need to export text, like a 'show text' button in the routing slip

This is called from the platform file using the syntax "call kItemToTextFunc with (...)"   

CHANGE HISTORY:

v3
*	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.

Note that this sample only supports the 'text dataType. As of the first Newton 2.1
devices, auto-putaway will only happen if the item has an appSymbol slot. For text-only
items, there will not be an item.appSymbol slot because the sending application does
not necessarily support putting away text. It *could* use RegAppClasses to say that
it can Put Away items of class 'text, but this is not currently used by the IOBox's
AutoPutaway algorithm (future OSes might use this differently). This sample shows how
to make this checkbox, but probably you would only want to offer this checkbox in 
your transport if you also support the 'frame dataType.