1mime(n) Mime mime(n)
2______________________________________________________________________________
6
8 mime - Manipulation of MIME body parts
9
11 package require Tcl 8.5
12 package require mime ?1.6.3?
14 ::mime::initialize ?-canonical type/subtype ?-param {key value}...?
16 ?-encoding value? ?-header {key value}...?? (-file name | -string value
17 | -parts {token1 ... tokenN})
18 ::mime::finalize token ?-subordinates all | dynamic | none?
20 ::mime::getproperty token ?property | -names?
22 ::mime::getheader token ?key | -names?
24 ::mime::setheader token key value ?-mode write | append | delete?
26 ::mime::getbody token ?-decode? ?-command callback ?-blocksize octets??
28 ::mime::copymessage token channel
30 ::mime::buildmessage token
32 ::mime::parseaddress string
34 ::mime::parsedatetime (string | -now) property
36 ::mime::mapencoding encoding_name
38 ::mime::reversemapencoding charset_type
40______________________________________________________________________________
42
44 The mime library package provides the commands to create and manipulate
45 MIME body parts.
46 ::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 • 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 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 Also, -encoding, if present, specifies the Content-Trans‐
62 fer-Encoding when copying the body.
63 • 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 ::mime::finalize token ?-subordinates all | dynamic | none?
70 Destroys the MIME part represented by token. It returns an empty
71 string.
72 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 ::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 The possible properties are:
87 content
89 The type/subtype describing the content
90 encoding
92 The "Content-Transfer-Encoding"
93 params A list of "Content-Type" parameters
95 parts A list of tokens for the part's subordinates. This prop‐
97 erty is present only if the MIME part has subordinates.
98 size The approximate size of the content (unencoded)
100 ::mime::getheader token ?key | -names?
102 Returns the header of a MIME part as a dictionary with possibly-
103 redundant keys.
104 If key is provided, then a list of values of matching names,
106 without regard to case, is returned.
107 If -names is provided, a list of all keys is returned.
109 ::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 The value for -mode is one of:
120 write The key/value is either created or overwritten (the de‐
122 fault).
123 append A new value is appended for the key (creating it as nec‐
125 essary).
126 delete All values associated with the key are removed (the value
128 parameter is ignored).
129 ::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 If the -command option is present, then it is repeatedly invoked
135 with a fragment of the body as this:
136 uplevel #0 $callback [list "data" $fragment]
139 (The -blocksize option, if present, specifies the maximum size of each
142 fragment passed to the callback.)
143 When the end of the body is reached, the callback is invoked as:
145 uplevel #0 $callback "end"
148 Alternatively, if an error occurs, the callback is invoked as:
151 uplevel #0 $callback [list "error" reason]
154 Regardless, the return value of the final invocation of the callback is
157 propagated upwards by ::mime::getbody.
158 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 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 ::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 ::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 ::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 Each serialized array contains the properties below. Note that
187 one or more of these properties may be empty.
188 address
190 local@domain
191 comment
193 822-style comment
194 domain the domain part (rhs)
196 error non-empty on a parse error
198 group this address begins a group
200 friendly
202 user-friendly rendering
203 local the local part (lhs)
205 memberP
207 this address belongs to a group
208 phrase the phrase part
210 proper 822-style address specification
212 route 822-style route specification (obsolete)
214 ::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 The list of properties and their ranges are:
220 hour 0 .. 23
222 lmonth January, February, ..., December
224 lweekday
226 Sunday, Monday, ... Saturday
227 mday 1 .. 31
229 min 0 .. 59
231 mon 1 .. 12
233 month Jan, Feb, ..., Dec
235 proper 822-style date-time specification
237 rclock elapsed seconds between then and now
239 sec 0 .. 59
241 wday 0 .. 6 (Sun .. Mon)
243 weekday
245 Sun, Mon, ..., Sat
246 yday 1 .. 366
248 year 1900 ...
250 zone -720 .. 720 (minutes east of GMT)
252 ::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 ::mime::reversemapencoding charset_type
259 Maps MIME charset types onto tcl encoding names. Those that are
260 unknown return "".
261
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 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 See Ticket 447037 [/tktview?name=447037] for additional informa‐
275 tion.
276
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 When proposing code changes, please provide unified diffs, i.e the out‐
285 put of diff -u.
286 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
293 ftp, http, pop3, smtp
294
296 email, internet, mail, mime, net, rfc 2045, rfc 2046, rfc 2049, rfc
297 821, rfc 822, smtp
298
300 Text processing
301
303 Copyright (c) 1999-2000 Marshall T. Rose
304tcllib 1.6.3 mime(n)