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.2?
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              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 -parts option.
56
57                     In  addition, both the -param and -header options may oc‐
58                     cur zero or more times to specify Content-Type parameters
59                     (e.g., charset) and header keyword/values (e.g., Content-
60                     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 re‐
72              turns 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  dy‐
76              namic,   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; in‐
111              stead, 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, ac‐
116              cordingly  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  de‐
127                     fault).
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
143                uplevel #0 $callback [list "data" $fragment]
144
145
146       (The  -blocksize option, if present, specifies the maximum size of each
147       fragment passed to the callback.)
148
149       When the end of the body is reached, the callback is invoked as:
150
151
152                  uplevel #0 $callback "end"
153
154
155       Alternatively, if an error occurs, the callback is invoked as:
156
157
158                  uplevel #0 $callback [list "error" reason]
159
160
161       Regardless, the return value of the final invocation of the callback is
162       propagated upwards by ::mime::getbody.
163
164       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
167       If the option -decode is absent the return value computed above is  re‐
168       turned  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 re‐
172       turning it.
173
174       ::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
180       ::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
185       ::mime::parseaddress string
186              This command takes a string containing one or more 822-style ad‐
187              dress  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
192              Each serialized array contains the properties below.  Note  that
193              one or more of these properties may be empty.
194
195              address
196                     local@domain
197
198              comment
199                     822-style comment
200
201              domain the domain part (rhs)
202
203              error  non-empty on a parse error
204
205              group  this address begins a group
206
207              friendly
208                     user-friendly rendering
209
210              local  the local part (lhs)
211
212              memberP
213                     this address belongs to a group
214
215              phrase the phrase part
216
217              proper 822-style address specification
218
219              route  822-style route specification (obsolete)
220
221       ::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
226              The list of properties and their ranges are:
227
228              hour   0 .. 23
229
230              lmonth January, February, ..., December
231
232              lweekday
233                     Sunday, Monday, ... Saturday
234
235              mday   1 .. 31
236
237              min    0 .. 59
238
239              mon    1 .. 12
240
241              month  Jan, Feb, ..., Dec
242
243              proper 822-style date-time specification
244
245              rclock elapsed seconds between then and now
246
247              sec    0 .. 59
248
249              wday   0 .. 6 (Sun .. Mon)
250
251              weekday
252                     Sun, Mon, ..., Sat
253
254              yday   1 .. 366
255
256              year   1900 ...
257
258              zone   -720 .. 720 (minutes east of GMT)
259
260       ::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
266       ::mime::reversemapencoding charset_type
267              This command maps MIME charset types onto  tcl  encoding  names.
268              Those that are unknown return "".
269

KNOWN BUGS

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
277              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 up‐
280              grade their Tcl interpreter for no reason.
281
282              See Ticket 447037 [/tktview?name=447037] for additional informa‐
283              tion.
284

BUGS, IDEAS, FEEDBACK

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
292       When proposing code changes, please provide unified diffs, i.e the out‐
293       put of diff -u.
294
295       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

SEE ALSO

301       ftp, http, pop3, smtp
302

KEYWORDS

304       email, internet, mail, mime, net, rfc 2045, rfc  2046,  rfc  2049,  rfc
305       821, rfc 822, smtp
306

CATEGORY

308       Text processing
309
311       Copyright (c) 1999-2000 Marshall T. Rose
312
313
314
315
316tcllib                               1.6.2                             mime(n)
Impressum