1mime(n)                              Mime                              mime(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       mime - Manipulation of MIME body parts
9

SYNOPSIS

11       package require Tcl
12
13       package require mime  ?1.5.4?
14
15       ::mime::initialize  ?-canonical  type/subtype  ?-param  {key value}...?
16       ?-encoding value? ?-header {key value}...?? (-file name | -string value
17       | -part {token1 ... tokenN})
18
19       ::mime::finalize token ?-subordinates all | dynamic | none?
20
21       ::mime::getproperty token ?property | -names?
22
23       ::mime::getheader token ?key | -names?
24
25       ::mime::setheader token key value ?-mode write | append | delete?
26
27       ::mime::getbody token ?-decode? ?-command callback ?-blocksize octets??
28
29       ::mime::copymessage token channel
30
31       ::mime::buildmessage token
32
33       ::mime::parseaddress string
34
35       ::mime::parsedatetime (string | -now) property
36
37       ::mime::mapencoding encoding_name
38
39       ::mime::reversemapencoding charset_type
40
41_________________________________________________________________
42

DESCRIPTION

44       The mime library package provides the commands to create and manipulate
45       MIME body parts.
46
47       ::mime::initialize ?-canonical  type/subtype  ?-param  {key  value}...?
48       ?-encoding value? ?-header {key value}...?? (-file name | -string value
49       | -part {token1 ... tokenN})
50              This command creates a MIME part and returns a token  represent‐
51              ing it.
52
53              ·      If  the -canonical option is present, then the body is in
54                     canonical (raw) form and is found  by  consulting  either
55                     the -file, -string, or -part option.
56
57                     In  addition,  both  the  -param  and -header options may
58                     occur zero or more times to specify Content-Type  parame‐
59                     ters  (e.g.,  charset)  and  header keyword/values (e.g.,
60                     Content-Disposition), respectively.
61
62                     Also, -encoding, if present, specifies the Content-Trans‐
63                     fer-Encoding when copying the body.
64
65              ·      If  the  -canonical  option is not present, then the MIME
66                     part contained in either the -file or the -string  option
67                     is  parsed, dynamically generating subordinates as appro‐
68                     priate.
69
70       ::mime::finalize token ?-subordinates all | dynamic | none?
71              This command destroys the MIME part  represented  by  token.  It
72              returns an empty string.
73
74              If  the -subordinates option is present, it specifies which sub‐
75              ordinates  should  also  be  destroyed.  The  default  value  is
76              dynamic,  destroying  all  subordinates  which  were  created by
77              ::mime::initialize together with the containing body part.
78
79       ::mime::getproperty token ?property | -names?
80              This command returns a string or a list  of  strings  containing
81              the  properties  of  a MIME part. If the command is invoked with
82              the name of a specific property, then the corresponding value is
83              returned; instead, if -names is specified, a list of all proper‐
84              ties is returned; otherwise, a serialized  array  of  properties
85              and values is returned.
86
87              The possible properties are:
88
89              content
90                     The type/subtype describing the content
91
92              encoding
93                     The "Content-Transfer-Encoding"
94
95              params A list of "Content-Type" parameters
96
97              parts  A list of tokens for the part's subordinates.  This prop‐
98                     erty is present only if the MIME part has subordinates.
99
100              size   The approximate size of the content (unencoded)
101
102       ::mime::getheader token ?key | -names?
103              This command returns the header of a MIME part,  as  a  list  of
104              strings.
105
106              A header consists of zero or more key/value pairs. Each value is
107              a list containing one or more strings.
108
109              If this command is invoked with the name of a specific key, then
110              a  list  containing  the  corresponding  value(s)  is  returned;
111              instead, if -names is specified, a list of all keys is returned;
112              otherwise,  a  serialized  array of keys and values is returned.
113              Note that when a key is specified (e.g.,  "Subject"),  the  list
114              returned usually contains exactly one string; however, some keys
115              (e.g., "Received") often occur more than  once  in  the  header,
116              accordingly  the  list  returned  usually contains more than one
117              string.
118
119       ::mime::setheader token key value ?-mode write | append | delete?
120              This command writes, appends to, or deletes the value associated
121              with  a key in the header. It returns a list of strings contain‐
122              ing the previous value associated with the key.
123
124              The value for -mode is one of:
125
126              write  The key/value  is  either  created  or  overwritten  (the
127                     default).
128
129              append A  new value is appended for the key (creating it as nec‐
130                     essary).
131
132              delete All values associated with the key are removed (the value
133                     parameter is ignored).
134
135       ::mime::getbody token ?-decode? ?-command callback ?-blocksize octets??
136              This  command  returns  a string containing the body of the leaf
137              MIME part represented by token in canonical form.
138
139              If the -command option is present, then it is repeatedly invoked
140              with a fragment of the body as this:
141
142                uplevel #0 $callback [list "data" $fragment]
143
144
145              (The  -blocksize  option, if present, specifies the maximum size
146              of each fragment passed to the callback.)
147
148              When the end of the body is reached, the callback is invoked as:
149
150                  uplevel #0 $callback "end"
151
152
153              Alternatively, if an error occurs, the callback is invoked as:
154
155                  uplevel #0 $callback [list "error" reason]
156
157
158              Regardless, the return value of  the  final  invocation  of  the
159              callback is propagated upwards by ::mime::getbody.
160
161              If  the  -command  option  is  absent,  then the return value of
162              ::mime::getbody is a string containing the  MIME  part's  entire
163              body.
164
165              If  the option -decode is absent the return value computed above
166              is returned as is. This means that it will  be  in  the  charset
167              specified  for the token and not the usual utf-8.  If the option
168              -decode is present however the  command  will  use  the  charset
169              information associated with the token to convert the string from
170              its encoding into utf-8 before returning it.
171
172       ::mime::copymessage token channel
173              This command copies the MIME represented by token  part  to  the
174              specified  channel. The command operates synchronously, and uses
175              fileevent to allow asynchronous operations to  proceed  indepen‐
176              dently. It returns an empty string.
177
178       ::mime::buildmessage token
179              This  command  returns  the  MIME part represented by token as a
180              string.  It is similar to ::mime::copymessage, only  it  returns
181              the data as a return string instead of writing to a channel.
182
183       ::mime::parseaddress string
184              This  command  takes  a  string containing one or more 822-style
185              address specifications and returns a list of serialized  arrays,
186              one  element  for each address specified in the argument. If the
187              string contains more than one address they will be separated  by
188              commas.
189
190              Each  serialized  array contains the properties below. Note that
191              one or more of these properties may be empty.
192
193              address
194                     local@domain
195
196              comment
197                     822-style comment
198
199              domain the domain part (rhs)
200
201              error  non-empty on a parse error
202
203              group  this address begins a group
204
205              friendly
206                     user-friendly rendering
207
208              local  the local part (lhs)
209
210              memberP
211                     this address belongs to a group
212
213              phrase the phrase part
214
215              proper 822-style address specification
216
217              route  822-style route specification (obsolete)
218
219       ::mime::parsedatetime (string | -now) property
220              This command takes a string containing  an  822-style  date-time
221              specification and returns the specified property as a serialized
222              array.
223
224              The list of properties and their ranges are:
225
226              hour   0 .. 23
227
228              lmonth January, February, ..., December
229
230              lweekday
231                     Sunday, Monday, ... Saturday
232
233              mday   1 .. 31
234
235              min    0 .. 59
236
237              mon    1 .. 12
238
239              month  Jan, Feb, ..., Dec
240
241              proper 822-style date-time specification
242
243              rclock elapsed seconds between then and now
244
245              sec    0 .. 59
246
247              wday   0 .. 6 (Sun .. Mon)
248
249              weekday
250                     Sun, Mon, ..., Sat
251
252              yday   1 .. 366
253
254              year   1900 ...
255
256              zone   -720 .. 720 (minutes east of GMT)
257
258       ::mime::mapencoding encoding_name
259              This commansd maps tcl encodings onto the proper names for their
260              MIME  charset  type.   This  is  only  done  for encodings whose
261              charset types were known.  The remaining encodings return "" for
262              now.
263
264       ::mime::reversemapencoding charset_type
265              This  command  maps  MIME charset types onto tcl encoding names.
266              Those that are unknown return "".
267

KNOWN BUGS

269       SourceForge Tcllib Bug #447037
270              This problem affects only people which are using Tcl and Mime on
271              a  64-bit system. The currently recommended fix for this problem
272              is to upgrade to Tcl version 8.4. This version has  extended  64
273              bit support and the bug does not appear anymore.
274
275              The  problem  could  have been generally solved by requiring the
276              use of Tcl 8.4 for this package. We decided against  this  solu‐
277              tion  as  it  would  force a large number of unaffected users to
278              upgrade their Tcl interpreter for no reason.
279
280              See                                               http://source
281              forge.net/tracker/?func=detail&aid=447037&group_id=12883&atid=112883
282              for additional information.
283

BUGS, IDEAS, FEEDBACK

285       This document, and the package it describes, will  undoubtedly  contain
286       bugs  and  other  problems.  Please report such in the category mime of
287       the         Tcllib         SF         Trackers          [http://source
288       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
289       enhancements you may have for either package and/or documentation.
290

SEE ALSO

292       ftp, http, pop3, smtp
293

KEYWORDS

295       email, internet, mail, mime, net, rfc 2045, rfc  2046,  rfc  2049,  rfc
296       821, rfc 822, smtp
297
299       Copyright (c) 1999-2000 Marshall T. Rose
300
301
302
303
304mime                                 1.5.4                             mime(n)
Impressum