aboutsummaryrefslogtreecommitdiff
path: root/docs/mime.html
diff options
context:
space:
mode:
authorCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
committerCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
commit5c4fc93d5f4137bf4c22ddf1a048c907a4a26727 (patch)
treea9a68e1f6a9c3bfe2b64fa1c3a4098865b7d3b5d /docs/mime.html
parentccef3bc4e2aa6ee5b997a80aabb58f4ff0b0e98f (diff)
parent43a97b7f0053313b43906371dbdc226271e6c8ab (diff)
downloadluasocket-hjelmeland-patch-1.tar.gz
luasocket-hjelmeland-patch-1.tar.bz2
luasocket-hjelmeland-patch-1.zip
Merge branch 'master' into hjelmeland-patch-1hjelmeland-patch-1
Diffstat (limited to 'docs/mime.html')
-rw-r--r--docs/mime.html477
1 files changed, 477 insertions, 0 deletions
diff --git a/docs/mime.html b/docs/mime.html
new file mode 100644
index 0000000..ff4d8e8
--- /dev/null
+++ b/docs/mime.html
@@ -0,0 +1,477 @@
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
76<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
77
78<p class="name" id="decode">
79mime.<b>decode(</b>"base64"<b>)</b><br>
80mime.<b>decode(</b>"quoted-printable"<b>)</b>
81</p>
82
83<p class="description">
84Returns a filter that decodes data from a given transfer content
85encoding.
86</p>
87
88<!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
89
90<p class="name" id="encode">
91mime.<b>encode(</b>"base64"<b>)</b><br>
92mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b>
93</p>
94
95<p class="description">
96Returns a filter that encodes data according to a given transfer content
97encoding.
98</p>
99
100<p class="parameters">
101In the Quoted-Printable case, the user can specify whether the data is
102textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or
103"<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>".
104</p>
105
106<p class="note">
107Although both transfer content encodings specify a limit for the line
108length, the encoding filters do <em>not</em> break text into lines (for
109added flexibility).
110Below is a filter that converts binary data to the Base64 transfer content
111encoding and breaks it into lines of the correct size.
112</p>
113
114<pre class="example">
115base64 = ltn12.filter.chain(
116 mime.encode("base64"),
117 mime.wrap("base64")
118)
119</pre>
120
121<p class="note">
122Note: Text data <em>has</em> to be converted to canonic form
123<em>before</em> being encoded.
124</p>
125
126<pre class="example">
127base64 = ltn12.filter.chain(
128 mime.normalize(),
129 mime.encode("base64"),
130 mime.wrap("base64")
131)
132</pre>
133
134<!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
135
136<p class="name" id="normalize">
137mime.<b>normalize(</b>[marker]<b>)</b>
138</p>
139
140<p class="description">
141Converts most common end-of-line markers to a specific given marker.
142</p>
143
144<p class="parameters">
145<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic
146end-of-line marker defined by the MIME standard.
147</p>
148
149<p class="return">
150The function returns a filter that performs the conversion.
151</p>
152
153<p class="note">
154Note: There is no perfect solution to this problem. Different end-of-line
155markers are an evil that will probably plague developers forever.
156This function, however, will work perfectly for text created with any of
157the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF),
158or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
159markers, the function will still work well, although it doesn't
160guarantee that the number of empty lines will be correct.
161</p>
162
163<!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
164
165<p class="name" id="stuff">
166mime.<b>stuff()</b><br>
167</p>
168
169<p class="description">
170Creates and returns a filter that performs stuffing of SMTP messages.
171</p>
172
173<p class="note">
174Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function
175uses this filter automatically. You don't need to chain it with your
176source, or apply it to your message body.
177</p>
178
179<!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
180
181<p class="name" id="wrap">
182mime.<b>wrap(</b>"text" [, length]<b>)</b><br>
183mime.<b>wrap(</b>"base64"<b>)</b><br>
184mime.<b>wrap(</b>"quoted-printable"<b>)</b>
185</p>
186
187<p class="description">
188Returns a filter that breaks data into lines.
189</p>
190
191<p class="parameters">
192The "<tt>text</tt>" line-wrap filter simply breaks text into lines by
193inserting CRLF end-of-line markers at appropriate positions.
194<tt>Length</tt> defaults 76.
195The "<tt>base64</tt>" line-wrap filter works just like the default
196"<tt>text</tt>" line-wrap filter with default length.
197The function can also wrap "<tt>quoted-printable</tt>" lines, taking care
198not to break lines in the middle of an escaped character. In that case, the
199line length is fixed at 76.
200</p>
201
202<p class="note">
203For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
204</p>
205
206<pre class="example">
207qp = ltn12.filter.chain(
208 mime.normalize(),
209 mime.encode("quoted-printable"),
210 mime.wrap("quoted-printable")
211)
212</pre>
213
214<p class="note">
215Note: To break into lines with a different end-of-line convention, apply
216a normalization filter after the line break filter.
217</p>
218
219<!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
220
221<h3 id="low">Low-level filters</h3>
222
223<!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
224
225<p class="name" id="b64">
226A, B = mime.<b>b64(</b>C [, D]<b>)</b>
227</p>
228
229<p class="description">
230Low-level filter to perform Base64 encoding.
231</p>
232
233<p class="description">
234<tt>A</tt> is the encoded version of the largest prefix of
235<tt>C..D</tt>
236that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
237<tt>C..D</tt>, <em>before</em> encoding.
238If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
239the encoding of the remaining bytes of <tt>C</tt>.
240</p>
241
242<p class="note">
243Note: The simplest use of this function is to encode a string into it's
244Base64 transfer content encoding. Notice the extra parenthesis around the
245call to <tt>mime.b64</tt>, to discard the second return value.
246</p>
247
248<pre class="example">
249print((mime.b64("diego:password")))
250--&gt; ZGllZ286cGFzc3dvcmQ=
251</pre>
252
253<!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
254<p class="name" id="dot">
255A, n = mime.<b>dot(</b>m [, B]<b>)</b>
256</p>
257
258<p class="description">
259Low-level filter to perform SMTP stuffing and enable transmission of
260messages containing the sequence "CRLF.CRLF".
261</p>
262
263<p class="parameters">
264<tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the
265number of characters from the sequence CRLF seen in the end of <tt>B</tt>.
266'<tt>m</tt>' should tell the same, but for the previous chunk.
267</p>
268
269<p class="note">Note: The message body is defined to begin with
270an implicit CRLF. Therefore, to stuff a message correctly, the
271first <tt>m</tt> should have the value 2.
272</p>
273
274<pre class="example">
275print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n")))
276--&gt; ..\nStuffing the message.\n..\n..
277</pre>
278
279<p class="note">
280Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function
281uses this filter automatically. You don't need to
282apply it again.
283</p>
284
285<!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
286
287<p class="name" id="eol">
288A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b>
289</p>
290
291<p class="description">
292Low-level filter to perform end-of-line marker translation.
293For each chunk, the function needs to know if the last character of the
294previous chunk could be part of an end-of-line marker or not. This is the
295context the function receives besides the chunk. An updated version of
296the context is returned after each new chunk.
297</p>
298
299<p class="parameters">
300<tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the
301ASCII value of the last character of the previous chunk, if it was a
302candidate for line break, or 0 otherwise.
303<tt>B</tt> is the same as <tt>C</tt>, but for the current
304chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF.
305</p>
306
307<pre class="example">
308-- translates the end-of-line marker to UNIX
309unix = mime.eol(0, dos, "\n")
310</pre>
311
312<!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
313
314<p class="name" id="qp">
315A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b>
316</p>
317
318<p class="description">
319Low-level filter to perform Quoted-Printable encoding.
320</p>
321
322<p class="parameters">
323<tt>A</tt> is the encoded version of the largest prefix of
324<tt>C..D</tt>
325that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
326<tt>C..D</tt>, <em>before</em> encoding.
327If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
328the encoding of the remaining bytes of <tt>C</tt>.
329Throughout encoding, occurrences of CRLF are replaced by the
330<tt>marker</tt>, which itself defaults to CRLF.
331</p>
332
333<p class="note">
334Note: The simplest use of this function is to encode a string into it's
335Quoted-Printable transfer content encoding.
336Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
337</p>
338
339<pre class="example">
340print((mime.qp("ma��")))
341--&gt; ma=E7=E3=
342</pre>
343
344<!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
345
346<p class="name" id="qpwrp">
347A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b>
348</p>
349
350<p class="description">
351Low-level filter to break Quoted-Printable text into lines.
352</p>
353
354<p class="parameters">
355<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
356<tt>length</tt> bytes (defaults to 76).
357'<tt>n</tt>' should tell how many bytes are left for the first
358line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
359left in the last line of <tt>A</tt>.
360</p>
361
362<p class="note">
363Note: Besides breaking text into lines, this function makes sure the line
364breaks don't fall in the middle of an escaped character combination. Also,
365this function only breaks lines that are bigger than <tt>length</tt> bytes.
366</p>
367
368<!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
369
370<p class="name" id="unb64">
371A, B = mime.<b>unb64(</b>C [, D]<b>)</b>
372</p>
373
374<p class="description">
375Low-level filter to perform Base64 decoding.
376</p>
377
378<p class="parameters">
379<tt>A</tt> is the decoded version of the largest prefix of
380<tt>C..D</tt>
381that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
382<tt>C..D</tt>, <em>before</em> decoding.
383If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string
384and <tt>B</tt> returns whatever couldn't be decoded.
385</p>
386
387<p class="note">
388Note: The simplest use of this function is to decode a string from it's
389Base64 transfer content encoding.
390Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
391</p>
392
393<pre class="example">
394print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
395--&gt; diego:password
396</pre>
397
398<!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
399
400<p class="name" id="unqp">
401A, B = mime.<b>unqp(</b>C [, D]<b>)</b>
402</p>
403
404<p class="description">
405Low-level filter to remove the Quoted-Printable transfer content encoding
406from data.
407</p>
408
409<p class="parameters">
410<tt>A</tt> is the decoded version of the largest prefix of
411<tt>C..D</tt>
412that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
413<tt>C..D</tt>, <em>before</em> decoding.
414If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with
415the encoding of the remaining bytes of <tt>C</tt>.
416</p>
417
418<p class="note">
419Note: The simplest use of this function is to decode a string from it's
420Quoted-Printable transfer content encoding.
421Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
422</p>
423
424<pre class="example">
425print((mime.qp("ma=E7=E3=")))
426--&gt; ma��
427</pre>
428
429<!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
430
431<p class="name" id="wrp">
432A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b>
433</p>
434
435<p class="description">
436Low-level filter to break text into lines with CRLF marker.
437Text is assumed to be in the <a href="#normalize"><tt>normalize</tt></a> form.
438</p>
439
440<p class="parameters">
441<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
442<tt>length</tt> bytes (defaults to 76).
443'<tt>n</tt>' should tell how many bytes are left for the first
444line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
445left in the last line of <tt>A</tt>.
446</p>
447
448<p class="note">
449Note: This function only breaks lines that are bigger than
450<tt>length</tt> bytes. The resulting line length does not include the CRLF
451marker.
452</p>
453
454
455<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
456
457<div class="footer">
458<hr>
459<center>
460<p class="bar">
461<a href="index.html">home</a> &middot;
462<a href="index.html#down">download</a> &middot;
463<a href="installation.html">installation</a> &middot;
464<a href="introduction.html">introduction</a> &middot;
465<a href="reference.html">reference</a>
466</p>
467<p>
468<small>
469Last modified by Diego Nehab on <br>
470Fri Mar 4 15:19:17 BRT 2016
471</small>
472</p>
473</center>
474</div>
475
476</body>
477</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-21 13:12:53 +0000