Mercurial > luasocket

comparison doc/mime.html @ 0:4b915342e2a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LuaSocket 2.0.2 + CMake build description.
author Eric Wing <ewing . public |-at-| gmail . com>
date Tue, 26 Aug 2008 18:40:01 -0700
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4b915342e2a8
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3 <html>
4
5 <head>
6 <meta name="description" content="LuaSocket: MIME support">
7 <meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support">
8 <title>LuaSocket: MIME module</title>
9 <link rel="stylesheet" href="reference.css" type="text/css">
10 </head>
11
12 <body>
13
14 <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15
16 <div class=header>
17 <hr>
18 <center>
19 <table summary="LuaSocket logo">
20 <tr><td align=center><a href="http://www.lua.org">
21 <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
22 </a></td></tr>
23 <tr><td align=center valign=top>Network support for the Lua language
24 </td></tr>
25 </table>
26 <p class=bar>
27 <a href="home.html">home</a> &middot;
28 <a href="home.html#download">download</a> &middot;
29 <a href="installation.html">installation</a> &middot;
30 <a href="introduction.html">introduction</a> &middot;
31 <a href="reference.html">reference</a>
32 </p>
33 </center>
34 <hr>
35 </div>
36
37 <!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39 <h2 id=mime>MIME</h2>
40
41 <p>
42 The <tt>mime</tt> namespace offers filters that apply and remove common
43 content transfer encodings, such as Base64 and Quoted-Printable.
44 It also provides functions to break text into lines and change
45 the end-of-line convention.
46 MIME is described mainly in
47 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2045.txt">RFC 2045</a>,
48 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2046.txt">2046</a>,
49 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2047.txt">2047</a>,
50 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2047.txt">2048</a>, and
51 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2048.txt">2049</a>.
52 </p>
53
54 <p>
55 All functionality provided by the MIME module
56 follows the ideas presented in
57 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
58 LTN012, Filters sources and sinks</a>.
59 </p>
60
61 <p>
62 To obtain the <tt>mime</tt> namespace, run:
63 </p>
64
65 <pre class=example>
66 -- loads the MIME module and everything it requires
67 local mime = require("mime")
68 </pre>
69
70
71 <!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
72
73 <h3 id=high>High-level filters</h3>
74
75 <!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
76
77 <p class=name id="normalize">
78 mime.<b>normalize(</b>[marker]<b>)</b>
79 </p>
80
81 <p class=description>
82 Converts most common end-of-line markers to a specific given marker.
83 </p>
84
85 <p class=parameters>
86 <tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic
87 end-of-line marker defined by the MIME standard.
88 </p>
89
90 <p class=return>
91 The function returns a filter that performs the conversion.
92 </p>
93
94 <p class=note>
95 Note: There is no perfect solution to this problem. Different end-of-line
96 markers are an evil that will probably plague developers forever.
97 This function, however, will work perfectly for text created with any of
98 the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF),
99 or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
100 markers, the function will still work well, although it doesn't
101 guarantee that the number of empty lines will be correct.
102 </p>
103
104 <!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
105
106 <p class=name id="decode">
107 mime.<b>decode(</b>"base64"<b>)</b><br>
108 mime.<b>decode(</b>"quoted-printable"<b>)</b>
109 </p>
110
111 <p class=description>
112 Returns a filter that decodes data from a given transfer content
113 encoding.
114 </p>
115
116 <!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
117
118 <p class=name id="encode">
119 mime.<b>encode(</b>"base64"<b>)</b><br>
120 mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b>
121 </p>
122
123 <p class=description>
124 Returns a filter that encodes data according to a given transfer content
125 encoding.
126 </p>
127
128 <p class=parameters>
129 In the Quoted-Printable case, the user can specify whether the data is
130 textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or
131 "<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>".
132 </p>
133
134 <p class=note>
135 Although both transfer content encodings specify a limit for the line
136 length, the encoding filters do <em>not</em> break text into lines (for
137 added flexibility).
138 Below is a filter that converts binary data to the Base64 transfer content
139 encoding and breaks it into lines of the correct size.
140 </p>
141
142 <pre class=example>
143 base64 = ltn12.filter.chain(
144 mime.encode("base64"),
145 mime.wrap("base64")
146 )
147 </pre>
148
149 <p class=note>
150 Note: Text data <em>has</em> to be converted to canonic form
151 <em>before</em> being encoded.
152 </p>
153
154 <pre class=example>
155 base64 = ltn12.filter.chain(
156 mime.normalize(),
157 mime.encode("base64"),
158 mime.wrap("base64")
159 )
160 </pre>
161
162 <!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
163
164 <p class=name id="stuff">
165 mime.<b>stuff()</b><br>
166 </p>
167
168 <p class=description>
169 Creates and returns a filter that performs stuffing of SMTP messages.
170 </p>
171
172 <p class=note>
173 Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function
174 uses this filter automatically. You don't need to chain it with your
175 source, or apply it to your message body.
176 </p>
177
178 <!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
179
180 <p class=name id="wrap">
181 mime.<b>wrap(</b>"text" [, length]<b>)</b><br>
182 mime.<b>wrap(</b>"base64"<b>)</b><br>
183 mime.<b>wrap(</b>"quoted-printable"<b>)</b>
184 </p>
185
186 <p class=description>
187 Returns a filter that breaks data into lines.
188 </p>
189
190 <p class=parameters>
191 The "<tt>text</tt>" line-wrap filter simply breaks text into lines by
192 inserting CRLF end-of-line markers at appropriate positions.
193 <tt>Length</tt> defaults 76.
194 The "<tt>base64</tt>" line-wrap filter works just like the default
195 "<tt>text</tt>" line-wrap filter with default length.
196 The function can also wrap "<tt>quoted-printable</tt>" lines, taking care
197 not to break lines in the middle of an escaped character. In that case, the
198 line length is fixed at 76.
199 </p>
200
201 <p class=note>
202 For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
203 </p>
204
205 <pre class=example>
206 qp = ltn12.filter.chain(
207 mime.normalize(),
208 mime.encode("quoted-printable"),
209 mime.wrap("quoted-printable")
210 )
211 </pre>
212
213 <p class=note>
214 Note: To break into lines with a different end-of-line convention, apply
215 a normalization filter after the line break filter.
216 </p>
217
218 <!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
219
220 <h3 id=low>Low-level filters</h3>
221
222 <!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
223
224 <p class=name id="b64">
225 A, B = mime.<b>b64(</b>C [, D]<b>)</b>
226 </p>
227
228 <p class=description>
229 Low-level filter to perform Base64 encoding.
230 </p>
231
232 <p class=description>
233 <tt>A</tt> is the encoded version of the largest prefix of
234 <tt>C..D</tt>
235 that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
236 <tt>C..D</tt>, <em>before</em> encoding.
237 If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
238 the encoding of the remaining bytes of <tt>C</tt>.
239 </p>
240
241 <p class=note>
242 Note: The simplest use of this function is to encode a string into it's
243 Base64 transfer content encoding. Notice the extra parenthesis around the
244 call to <tt>mime.b64</tt>, to discard the second return value.
245 </p>
246
247 <pre class=example>
248 print((mime.b64("diego:password")))
249 --&gt; ZGllZ286cGFzc3dvcmQ=
250 </pre>
251
252 <!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253 <p class=name id="dot">
254 A, n = mime.<b>dot(</b>m [, B]<b>)</b>
255 </p>
256
257 <p class=description>
258 Low-level filter to perform SMTP stuffing and enable transmission of
259 messages containing the sequence "CRLF.CRLF".
260 </p>
261
262 <p class=parameters>
263 <tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the
264 number of characters from the sequence CRLF seen in the end of <tt>B</tt>.
265 '<tt>m</tt>' should tell the same, but for the previous chunk.
266 </p>
267
268 <p class=note>Note: The message body is defined to begin with
269 an implicit CRLF. Therefore, to stuff a message correctly, the
270 first <tt>m</tt> should have the value 2.
271 </p>
272
273 <pre class=example>
274 print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n")))
275 --&gt; ..\nStuffing the message.\n..\n..
276 </pre>
277
278 <p class=note>
279 Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function
280 uses this filter automatically. You don't need to
281 apply it again.
282 </p>
283
284 <!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
285
286 <p class=name id="eol">
287 A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b>
288 </p>
289
290 <p class=description>
291 Low-level filter to perform end-of-line marker translation.
292 For each chunk, the function needs to know if the last character of the
293 previous chunk could be part of an end-of-line marker or not. This is the
294 context the function receives besides the chunk. An updated version of
295 the context is returned after each new chunk.
296 </p>
297
298 <p class=parameters>
299 <tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the
300 ASCII value of the last character of the previous chunk, if it was a
301 candidate for line break, or 0 otherwise.
302 <tt>B</tt> is the same as <tt>C</tt>, but for the current
303 chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF.
304 </p>
305
306 <pre class=example>
307 -- translates the end-of-line marker to UNIX
308 unix = mime.eol(0, dos, "\n")
309 </pre>
310
311 <!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
312
313 <p class=name id="qp">
314 A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b>
315 </p>
316
317 <p class=description>
318 Low-level filter to perform Quoted-Printable encoding.
319 </p>
320
321 <p class=parameters>
322 <tt>A</tt> is the encoded version of the largest prefix of
323 <tt>C..D</tt>
324 that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
325 <tt>C..D</tt>, <em>before</em> encoding.
326 If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
327 the encoding of the remaining bytes of <tt>C</tt>.
328 Throughout encoding, occurrences of CRLF are replaced by the
329 <tt>marker</tt>, which itself defaults to CRLF.
330 </p>
331
332 <p class=note>
333 Note: The simplest use of this function is to encode a string into it's
334 Quoted-Printable transfer content encoding.
335 Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
336 </p>
337
338 <pre class=example>
339 print((mime.qp("maçã")))
340 --&gt; ma=E7=E3=
341 </pre>
342
343 <!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
344
345 <p class=name id="qpwrp">
346 A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b>
347 </p>
348
349 <p class=description>
350 Low-level filter to break Quoted-Printable text into lines.
351 </p>
352
353 <p class=parameters>
354 <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
355 <tt>length</tt> bytes (defaults to 76).
356 '<tt>n</tt>' should tell how many bytes are left for the first
357 line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
358 left in the last line of <tt>A</tt>.
359 </p>
360
361 <p class=note>
362 Note: Besides breaking text into lines, this function makes sure the line
363 breaks don't fall in the middle of an escaped character combination. Also,
364 this function only breaks lines that are bigger than <tt>length</tt> bytes.
365 </p>
366
367 <!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
368
369 <p class=name id="unb64">
370 A, B = mime.<b>unb64(</b>C [, D]<b>)</b>
371 </p>
372
373 <p class=description>
374 Low-level filter to perform Base64 decoding.
375 </p>
376
377 <p class=parameters>
378 <tt>A</tt> is the decoded version of the largest prefix of
379 <tt>C..D</tt>
380 that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
381 <tt>C..D</tt>, <em>before</em> decoding.
382 If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string
383 and <tt>B</tt> returns whatever couldn't be decoded.
384 </p>
385
386 <p class=note>
387 Note: The simplest use of this function is to decode a string from it's
388 Base64 transfer content encoding.
389 Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
390 </p>
391
392 <pre class=example>
393 print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
394 --&gt; diego:password
395 </pre>
396
397 <!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
398
399 <p class=name id="unqp">
400 A, B = mime.<b>unqp(</b>C [, D]<b>)</b>
401 </p>
402
403 <p class=description>
404 Low-level filter to remove the Quoted-Printable transfer content encoding
405 from data.
406 </p>
407
408 <p class=parameters>
409 <tt>A</tt> is the decoded version of the largest prefix of
410 <tt>C..D</tt>
411 that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
412 <tt>C..D</tt>, <em>before</em> decoding.
413 If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with
414 the encoding of the remaining bytes of <tt>C</tt>.
415 </p>
416
417 <p class=note>
418 Note: The simplest use of this function is to decode a string from it's
419 Quoted-Printable transfer content encoding.
420 Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
421 </p>
422
423 <pre class=example>
424 print((mime.qp("ma=E7=E3=")))
425 --&gt; maçã
426 </pre>
427
428 <!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
429
430 <p class=name id="wrp">
431 A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b>
432 </p>
433
434 <p class=description>
435 Low-level filter to break text into lines with CRLF marker.
436 Text is assumed to be in the <a href=#normalize><tt>normalize</tt></a> form.
437 </p>
438
439 <p class=parameters>
440 <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
441 <tt>length</tt> bytes (defaults to 76).
442 '<tt>n</tt>' should tell how many bytes are left for the first
443 line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
444 left in the last line of <tt>A</tt>.
445 </p>
446
447 <p class=note>
448 Note: This function only breaks lines that are bigger than
449 <tt>length</tt> bytes. The resulting line length does not include the CRLF
450 marker.
451 </p>
452
453
454 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
455
456 <div class=footer>
457 <hr>
458 <center>
459 <p class=bar>
460 <a href="home.html">home</a> &middot;
461 <a href="home.html#down">download</a> &middot;
462 <a href="installation.html">installation</a> &middot;
463 <a href="introduction.html">introduction</a> &middot;
464 <a href="reference.html">reference</a>
465 </p>
466 <p>
467 <small>
468 Last modified by Diego Nehab on <br>
469 Thu Apr 20 00:25:44 EDT 2006
470 </small>
471 </p>
472 </center>
473 </div>
474
475 </body>
476 </html>