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

NAME

8       mime - Manipulation of MIME body parts
9

SYNOPSIS

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

KNOWN BUGS

263       Tcllib Bug #447037
264              This problem affects only people which are using Tcl and Mime on
265              a 64-bit system. The currently recommended fix for this  problem
266              is  to  upgrade to Tcl version 8.4. This version has extended 64
267              bit support and the bug does not appear anymore.
268
269              The problem could have been generally solved  by  requiring  the
270              use  of  Tcl 8.4 for this package. We decided against this solu‐
271              tion as it would force a large number of unaffected users to up‐
272              grade their Tcl interpreter for no reason.
273
274              See Ticket 447037 [/tktview?name=447037] for additional informa‐
275              tion.
276

BUGS, IDEAS, FEEDBACK

278       This document, and the package it describes, will  undoubtedly  contain
279       bugs  and  other  problems.  Please report such in the category mime of
280       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
281       also  report any ideas for enhancements you may have for either package
282       and/or documentation.
283
284       When proposing code changes, please provide unified diffs, i.e the out‐
285       put of diff -u.
286
287       Note  further  that  attachments  are  strongly  preferred over inlined
288       patches. Attachments can be made by going  to  the  Edit  form  of  the
289       ticket  immediately  after  its  creation, and then using the left-most
290       button in the secondary navigation bar.
291

SEE ALSO

293       ftp, http, pop3, smtp
294

KEYWORDS

296       email, internet, mail, mime, net, rfc 2045, rfc  2046,  rfc  2049,  rfc
297       821, rfc 822, smtp
298

CATEGORY

300       Text processing
301
303       Copyright (c) 1999-2000 Marshall T. Rose
304
305
306
307
308tcllib                               1.6.3                             mime(n)
Impressum