1mime(n) Mime mime(n)
2______________________________________________________________________________
6
8 mime - Manipulation of MIME body parts
9
11 package require Tcl
12 package require mime ?1.5.4?
14 ::mime::initialize ?-canonical type/subtype ?-param {key value}...?
16 ?-encoding value? ?-header {key value}...?? (-file name | -string value
17 | -part {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 | -part {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 -part 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]
143 (The -blocksize option, if present, specifies the maximum size
146 of each fragment passed to the callback.)
147 When the end of the body is reached, the callback is invoked as:
149 uplevel #0 $callback "end"
151 Alternatively, if an error occurs, the callback is invoked as:
154 uplevel #0 $callback [list "error" reason]
156 Regardless, the return value of the final invocation of the
159 callback is propagated upwards by ::mime::getbody.
160 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 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 ::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 ::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 ::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 Each serialized array contains the properties below. Note that
191 one or more of these properties may be empty.
192 address
194 local@domain
195 comment
197 822-style comment
198 domain the domain part (rhs)
200 error non-empty on a parse error
202 group this address begins a group
204 friendly
206 user-friendly rendering
207 local the local part (lhs)
209 memberP
211 this address belongs to a group
212 phrase the phrase part
214 proper 822-style address specification
216 route 822-style route specification (obsolete)
218 ::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 The list of properties and their ranges are:
225 hour 0 .. 23
227 lmonth January, February, ..., December
229 lweekday
231 Sunday, Monday, ... Saturday
232 mday 1 .. 31
234 min 0 .. 59
236 mon 1 .. 12
238 month Jan, Feb, ..., Dec
240 proper 822-style date-time specification
242 rclock elapsed seconds between then and now
244 sec 0 .. 59
246 wday 0 .. 6 (Sun .. Mon)
248 weekday
250 Sun, Mon, ..., Sat
251 yday 1 .. 366
253 year 1900 ...
255 zone -720 .. 720 (minutes east of GMT)
257 ::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 ::mime::reversemapencoding charset_type
265 This command maps MIME charset types onto tcl encoding names.
266 Those that are unknown return "".
267
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 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 See http://source‐
281 forge.net/tracker/?func=detail&aid=447037&group_id=12883&atid=112883
282 for additional information.
283
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
292 ftp, http, pop3, smtp
293
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
300mime 1.5.4 mime(n)