home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / mail / metamail / contrib / ServiceMail / doc / mesh / hacking.doc next >
Encoding:
Text File  |  1993-05-10  |  4.4 KB  |  102 lines
  1. Before building your own services, we recommend that you understand the
  2. examples in the src/services directory.  That way, you can start from
  3. one of those examples and modify it for your application.
  4.  
  5. The examples use the pair of functions "setfield" and "getfield" quite
  6. a bit.  They are not part of basic TCL; rather they are defined in the
  7. file src/mesh/init.tcl and preloaded into the TCL interpreter.  They
  8. provide a data structure that is most like LISP association lists, and
  9. they are like C structs in the sense that they provide keyworded
  10. sub-structure to certain variables.  Such variables are lists where
  11. the even-numbered elements (numbering from zero) are field names, and
  12. the odd-numberbed elements are field values.  An example structure is
  13. {TYPE text SUBTYPE plain FILE /tmp/abc}.   Setfield and getfield are
  14. used to add and query name/value pairs, respectively.  That is, the
  15. command [setfield vname NAME value] literally appends NAME and value
  16. to the list variable named "vname", and the command [getfield $vname NAME]
  17. returns the value corresponding to field NAME.  (As currently implemented,
  18. setfield does not remove any previous uses of the field NAME, but getfield
  19. will do the right thing and use the value nearest the end of the list.)
  20.  
  21. The mesh program invokes a service with three arguments:
  22.  
  23.   switches -- a list of parameters that appeared after the service name
  24.     on the Subject: line.
  25.  
  26.   envelope -- a name/value list that defines FROM, REPLYTO, MESSAGEID,
  27.     and SERVICE (including switches) from the incoming message.
  28.  
  29.   inputs -- a name/value list that describes the body of the incoming
  30.     message, including in what files to find the actual content; the
  31.     name/value list defines the TYPE, SUBTYPE, and PARAMS (as a recursive
  32.     name/value list) fields from the MIME Content-Type: line, and the
  33.     DESCRIPTION field from the MIME Content-Description: line (if there
  34.     was such a line in the header).  If the TYPE is "multipart", then
  35.     there will be one more field PARTS, which is a list of name/value
  36.     lists that each define a recursive MIME type as above.  Any TYPE
  37.     other than multipart will define a FILE field (which names a file
  38.     that contains the actual content), and an ID field (if a Content-Id:
  39.     was supplied).
  40.  
  41. Services will usually send out at least one mail message, even if only
  42. as an acknowledgement.  Mesh provides the builtin TCL procedure named
  43. "mailout" for this purpose.  Mailout takes two arguments:  the outgoing
  44. envelope and a description of the outgoing body.  The outgoing envelope
  45. is a name/value list defining the fields TO, INREPLYTO, SUBJECT, and
  46. CC (TO and SUBJECT are mandatory, the others aren't).  Since most
  47. outgoing envelopes will be a straightforward translation of the incoming
  48. envelope, there exists a function "turnaround" that creates an outgoing
  49. envelope from an incoming one.  That is, you will usually wanted to
  50. call mailout in the following way:
  51.  
  52.   mailout [turnaround $inenvelope] $outbody
  53.  
  54. The second argument is a description of the body of the outgoing message.
  55. Like the inputs argument described above, the outbody is a name/value
  56. list that defines the TYPE, SUBTYPE, PARAMS, DESCRIPTION, PARTS (in the
  57. case of multipart types) or FILE and ID (for other types) fields. However,
  58. there are two important differences.  First, there is an alternative
  59. field to FILE, called STRING, which literally defines the contents of
  60. the body (if both are specified, FILE overrides STRING). Second, some
  61. fields have defaults, as specified below:
  62.  
  63.   TYPE -- defaults to "text"
  64.  
  65.   SUBTYPE -- defaults to "plain"
  66.  
  67.   PARAMS -- if the TYPE is text, defaults to {charset us-ascii}
  68.  
  69.   STRING -- defaults to "Your message was processed."
  70.  
  71.   ID -- defaults to the value of FILE, if specified
  72.  
  73. Therefore, a service rarely needs to specify all fields.
  74.  
  75. Added in version 2.0:
  76.  
  77. The follwing fields are now extracted from the incoming message
  78. into the incoming envelope:
  79.  
  80.   DATE -- the Date: header line
  81.   
  82.   SPLITSIZE -- the X-Splitsize: header line
  83.  
  84.   TO -- the To: line
  85.  
  86. The following new fields are meaningful when set in the outgoing
  87. envelope:
  88.  
  89.   MESSAGEID -- goes out on the Message-id: line
  90.  
  91.   SPLITSIZE -- given to the outgoing mailer (presumably to
  92.     splitmail, which uses it as a fragmentation size)
  93.  
  94. The turnaround function copies SPLITSIZE from the incoming to
  95. the outgoing envelopes.
  96.  
  97. The following new fields are meaningful in an outgoing message 
  98. body (part):
  99.  
  100.   ENCODING -- overrides the automatic selection of a content-
  101.     transfer encoding
  102.