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?
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 This command creates a MIME part and returns a token represent‐
51 ing it.
52 · 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 -parts option.
56 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 Also, -encoding, if present, specifies the Content-Trans‐
63 fer-Encoding when copying the body.
64 · 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 ::mime::finalize token ?-subordinates all | dynamic | none?
71 This command destroys the MIME part represented by token. It
72 returns an empty string.
73 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 ::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 The possible properties are:
88 content
90 The type/subtype describing the content
91 encoding
93 The "Content-Transfer-Encoding"
94 params A list of "Content-Type" parameters
96 parts A list of tokens for the part's subordinates. This prop‐
98 erty is present only if the MIME part has subordinates.
99 size The approximate size of the content (unencoded)
101 ::mime::getheader token ?key | -names?
103 This command returns the header of a MIME part, as a list of
104 strings.
105 A header consists of zero or more key/value pairs. Each value is
107 a list containing one or more strings.
108 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 ::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 The value for -mode is one of:
125 write The key/value is either created or overwritten (the
127 default).
128 append A new value is appended for the key (creating it as nec‐
130 essary).
131 delete All values associated with the key are removed (the value
133 parameter is ignored).
134 ::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 If the -command option is present, then it is repeatedly invoked
140 with a fragment of the body as this:
141 uplevel #0 $callback [list "data" $fragment]
144 (The -blocksize option, if present, specifies the maximum size of each
147 fragment passed to the callback.)
148 When the end of the body is reached, the callback is invoked as:
150 uplevel #0 $callback "end"
153 Alternatively, if an error occurs, the callback is invoked as:
156 uplevel #0 $callback [list "error" reason]
159 Regardless, the return value of the final invocation of the callback is
162 propagated upwards by ::mime::getbody.
163 If the -command option is absent, then the return value of ::mime::get‐
165 body is a string containing the MIME part's entire body.
166 If the option -decode is absent the return value computed above is
168 returned as is. This means that it will be in the charset specified for
169 the token and not the usual utf-8. If the option -decode is present
170 however the command will use the charset information associated with
171 the token to convert the string from its encoding into utf-8 before
172 returning it.
173 ::mime::copymessage token channel
175 This command copies the MIME represented by token part to the
176 specified channel. The command operates synchronously, and uses
177 fileevent to allow asynchronous operations to proceed indepen‐
178 dently. It returns an empty string.
179 ::mime::buildmessage token
181 This command returns the MIME part represented by token as a
182 string. It is similar to ::mime::copymessage, only it returns
183 the data as a return string instead of writing to a channel.
184 ::mime::parseaddress string
186 This command takes a string containing one or more 822-style
187 address specifications and returns a list of serialized arrays,
188 one element for each address specified in the argument. If the
189 string contains more than one address they will be separated by
190 commas.
191 Each serialized array contains the properties below. Note that
193 one or more of these properties may be empty.
194 address
196 local@domain
197 comment
199 822-style comment
200 domain the domain part (rhs)
202 error non-empty on a parse error
204 group this address begins a group
206 friendly
208 user-friendly rendering
209 local the local part (lhs)
211 memberP
213 this address belongs to a group
214 phrase the phrase part
216 proper 822-style address specification
218 route 822-style route specification (obsolete)
220 ::mime::parsedatetime (string | -now) property
222 This command takes a string containing an 822-style date-time
223 specification and returns the specified property as a serialized
224 array.
225 The list of properties and their ranges are:
227 hour 0 .. 23
229 lmonth January, February, ..., December
231 lweekday
233 Sunday, Monday, ... Saturday
234 mday 1 .. 31
236 min 0 .. 59
238 mon 1 .. 12
240 month Jan, Feb, ..., Dec
242 proper 822-style date-time specification
244 rclock elapsed seconds between then and now
246 sec 0 .. 59
248 wday 0 .. 6 (Sun .. Mon)
250 weekday
252 Sun, Mon, ..., Sat
253 yday 1 .. 366
255 year 1900 ...
257 zone -720 .. 720 (minutes east of GMT)
259 ::mime::mapencoding encoding_name
261 This commansd maps tcl encodings onto the proper names for their
262 MIME charset type. This is only done for encodings whose
263 charset types were known. The remaining encodings return "" for
264 now.
265 ::mime::reversemapencoding charset_type
267 This command maps MIME charset types onto tcl encoding names.
268 Those that are unknown return "".
269
271 Tcllib Bug #447037
272 This problem affects only people which are using Tcl and Mime on
273 a 64-bit system. The currently recommended fix for this problem
274 is to upgrade to Tcl version 8.4. This version has extended 64
275 bit support and the bug does not appear anymore.
276 The problem could have been generally solved by requiring the
278 use of Tcl 8.4 for this package. We decided against this solu‐
279 tion as it would force a large number of unaffected users to
280 upgrade their Tcl interpreter for no reason.
281 See Ticket 447037 [/tktview?name=447037] for additional informa‐
283 tion.
284
286 This document, and the package it describes, will undoubtedly contain
287 bugs and other problems. Please report such in the category mime of
288 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
289 also report any ideas for enhancements you may have for either package
290 and/or documentation.
291 When proposing code changes, please provide unified diffs, i.e the out‐
293 put of diff -u.
294 Note further that attachments are strongly preferred over inlined
296 patches. Attachments can be made by going to the Edit form of the
297 ticket immediately after its creation, and then using the left-most
298 button in the secondary navigation bar.
299
301 ftp, http, pop3, smtp
302
304 email, internet, mail, mime, net, rfc 2045, rfc 2046, rfc 2049, rfc
305 821, rfc 822, smtp
306
308 Text processing
309
311 Copyright (c) 1999-2000 Marshall T. Rose
312tcllib 1.6 mime(n)