aboutsummaryrefslogtreecommitdiff
path: root/doc/mime.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/mime.html')
-rw-r--r--doc/mime.html476
1 files changed, 0 insertions, 476 deletions
diff --git a/doc/mime.html b/doc/mime.html
deleted file mode 100644
index ae136fd..0000000
--- a/doc/mime.html
+++ /dev/null
@@ -1,476 +0,0 @@
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="index.html">home</a> &middot;
28<a href="index.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>
42The <tt>mime</tt> namespace offers filters that apply and remove common
43content transfer encodings, such as Base64 and Quoted-Printable.
44It also provides functions to break text into lines and change
45the end-of-line convention.
46MIME is described mainly in
47<a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>,
48<a href="http://www.ietf.org/rfc/rfc2046.txt">2046</a>,
49<a href="http://www.ietf.org/rfc/rfc2047.txt">2047</a>,
50<a href="http://www.ietf.org/rfc/rfc2047.txt">2048</a>, and
51<a href="http://www.ietf.org/rfc/rfc2048.txt">2049</a>.
52</p>
53
54<p>
55All functionality provided by the MIME module
56follows the ideas presented in
57<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
58LTN012, Filters sources and sinks</a>.
59</p>
60
61<p>
62To obtain the <tt>mime</tt> namespace, run:
63</p>
64
65<pre class=example>
66-- loads the MIME module and everything it requires
67local 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">
78mime.<b>normalize(</b>[marker]<b>)</b>
79</p>
80
81<p class=description>
82Converts 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
87end-of-line marker defined by the MIME standard.
88</p>
89
90<p class=return>
91The function returns a filter that performs the conversion.
92</p>
93
94<p class=note>
95Note: There is no perfect solution to this problem. Different end-of-line
96markers are an evil that will probably plague developers forever.
97This function, however, will work perfectly for text created with any of
98the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF),
99or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
100markers, the function will still work well, although it doesn't
101guarantee that the number of empty lines will be correct.
102</p>
103
104<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
105
106<p class=name id="decode">
107mime.<b>decode(</b>"base64"<b>)</b><br>
108mime.<b>decode(</b>"quoted-printable"<b>)</b>
109</p>
110
111<p class=description>
112Returns a filter that decodes data from a given transfer content
113encoding.
114</p>
115
116<!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
117
118<p class=name id="encode">
119mime.<b>encode(</b>"base64"<b>)</b><br>
120mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b>
121</p>
122
123<p class=description>
124Returns a filter that encodes data according to a given transfer content
125encoding.
126</p>
127
128<p class=parameters>
129In the Quoted-Printable case, the user can specify whether the data is
130textual 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>
135Although both transfer content encodings specify a limit for the line
136length, the encoding filters do <em>not</em> break text into lines (for
137added flexibility).
138Below is a filter that converts binary data to the Base64 transfer content
139encoding and breaks it into lines of the correct size.
140</p>
141
142<pre class=example>
143base64 = ltn12.filter.chain(
144 mime.encode("base64"),
145 mime.wrap("base64")
146)
147</pre>
148
149<p class=note>
150Note: Text data <em>has</em> to be converted to canonic form
151<em>before</em> being encoded.
152</p>
153
154<pre class=example>
155base64 = 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">
165mime.<b>stuff()</b><br>
166</p>
167
168<p class=description>
169Creates and returns a filter that performs stuffing of SMTP messages.
170</p>
171
172<p class=note>
173Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function
174uses this filter automatically. You don't need to chain it with your
175source, or apply it to your message body.
176</p>
177
178<!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
179
180<p class=name id="wrap">
181mime.<b>wrap(</b>"text" [, length]<b>)</b><br>
182mime.<b>wrap(</b>"base64"<b>)</b><br>
183mime.<b>wrap(</b>"quoted-printable"<b>)</b>
184</p>
185
186<p class=description>
187Returns a filter that breaks data into lines.
188</p>
189
190<p class=parameters>
191The "<tt>text</tt>" line-wrap filter simply breaks text into lines by
192inserting CRLF end-of-line markers at appropriate positions.
193<tt>Length</tt> defaults 76.
194The "<tt>base64</tt>" line-wrap filter works just like the default
195"<tt>text</tt>" line-wrap filter with default length.
196The function can also wrap "<tt>quoted-printable</tt>" lines, taking care
197not to break lines in the middle of an escaped character. In that case, the
198line length is fixed at 76.
199</p>
200
201<p class=note>
202For 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>
206qp = ltn12.filter.chain(
207 mime.normalize(),
208 mime.encode("quoted-printable"),
209 mime.wrap("quoted-printable")
210)
211</pre>
212
213<p class=note>
214Note: To break into lines with a different end-of-line convention, apply
215a 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">
225A, B = mime.<b>b64(</b>C [, D]<b>)</b>
226</p>
227
228<p class=description>
229Low-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>
235that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
236<tt>C..D</tt>, <em>before</em> encoding.
237If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
238the encoding of the remaining bytes of <tt>C</tt>.
239</p>
240
241<p class=note>
242Note: The simplest use of this function is to encode a string into it's
243Base64 transfer content encoding. Notice the extra parenthesis around the
244call to <tt>mime.b64</tt>, to discard the second return value.
245</p>
246
247<pre class=example>
248print((mime.b64("diego:password")))
249--&gt; ZGllZ286cGFzc3dvcmQ=
250</pre>
251
252<!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253<p class=name id="dot">
254A, n = mime.<b>dot(</b>m [, B]<b>)</b>
255</p>
256
257<p class=description>
258Low-level filter to perform SMTP stuffing and enable transmission of
259messages 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
264number 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
269an implicit CRLF. Therefore, to stuff a message correctly, the
270first <tt>m</tt> should have the value 2.
271</p>
272
273<pre class=example>
274print((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>
279Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function
280uses this filter automatically. You don't need to
281apply it again.
282</p>
283
284<!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
285
286<p class=name id="eol">
287A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b>
288</p>
289
290<p class=description>
291Low-level filter to perform end-of-line marker translation.
292For each chunk, the function needs to know if the last character of the
293previous chunk could be part of an end-of-line marker or not. This is the
294context the function receives besides the chunk. An updated version of
295the 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
300ASCII value of the last character of the previous chunk, if it was a
301candidate for line break, or 0 otherwise.
302<tt>B</tt> is the same as <tt>C</tt>, but for the current
303chunk. <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
308unix = mime.eol(0, dos, "\n")
309</pre>
310
311<!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
312
313<p class=name id="qp">
314A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b>
315</p>
316
317<p class=description>
318Low-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>
324that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
325<tt>C..D</tt>, <em>before</em> encoding.
326If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
327the encoding of the remaining bytes of <tt>C</tt>.
328Throughout encoding, occurrences of CRLF are replaced by the
329<tt>marker</tt>, which itself defaults to CRLF.
330</p>
331
332<p class=note>
333Note: The simplest use of this function is to encode a string into it's
334Quoted-Printable transfer content encoding.
335Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
336</p>
337
338<pre class=example>
339print((mime.qp("maçã")))
340--&gt; ma=E7=E3=
341</pre>
342
343<!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
344
345<p class=name id="qpwrp">
346A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b>
347</p>
348
349<p class=description>
350Low-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
357line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
358left in the last line of <tt>A</tt>.
359</p>
360
361<p class=note>
362Note: Besides breaking text into lines, this function makes sure the line
363breaks don't fall in the middle of an escaped character combination. Also,
364this function only breaks lines that are bigger than <tt>length</tt> bytes.
365</p>
366
367<!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
368
369<p class=name id="unb64">
370A, B = mime.<b>unb64(</b>C [, D]<b>)</b>
371</p>
372
373<p class=description>
374Low-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>
380that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
381<tt>C..D</tt>, <em>before</em> decoding.
382If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string
383and <tt>B</tt> returns whatever couldn't be decoded.
384</p>
385
386<p class=note>
387Note: The simplest use of this function is to decode a string from it's
388Base64 transfer content encoding.
389Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
390</p>
391
392<pre class=example>
393print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
394--&gt; diego:password
395</pre>
396
397<!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
398
399<p class=name id="unqp">
400A, B = mime.<b>unqp(</b>C [, D]<b>)</b>
401</p>
402
403<p class=description>
404Low-level filter to remove the Quoted-Printable transfer content encoding
405from 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>
411that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
412<tt>C..D</tt>, <em>before</em> decoding.
413If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with
414the encoding of the remaining bytes of <tt>C</tt>.
415</p>
416
417<p class=note>
418Note: The simplest use of this function is to decode a string from it's
419Quoted-Printable transfer content encoding.
420Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
421</p>
422
423<pre class=example>
424print((mime.qp("ma=E7=E3=")))
425--&gt; maçã
426</pre>
427
428<!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
429
430<p class=name id="wrp">
431A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b>
432</p>
433
434<p class=description>
435Low-level filter to break text into lines with CRLF marker.
436Text 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
443line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
444left in the last line of <tt>A</tt>.
445</p>
446
447<p class=note>
448Note: This function only breaks lines that are bigger than
449<tt>length</tt> bytes. The resulting line length does not include the CRLF
450marker.
451</p>
452
453
454<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
455
456<div class=footer>
457<hr>
458<center>
459<p class=bar>
460<a href="index.html">home</a> &middot;
461<a href="index.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>
468Last modified by Diego Nehab on <br>
469Thu Apr 20 00:25:44 EDT 2006
470</small>
471</p>
472</center>
473</div>
474
475</body>
476</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-04 22:35:21 +0000