Blame doc/mime.html

Packit b53373
Packit b53373
    "http://www.w3.org/TR/html4/strict.dtd">
Packit b53373
<html>
Packit b53373
Packit b53373
<head>
Packit b53373
<meta name="description" content="LuaSocket: MIME support">
Packit b53373
<meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support"> 
Packit b53373
<title>LuaSocket: MIME module</title>
Packit b53373
<link rel="stylesheet" href="reference.css" type="text/css">
Packit b53373
</head>
Packit b53373
Packit b53373
<body>
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
<center>
Packit b53373
Packit b53373
Packit b53373
LuaSocket
Packit b53373
Packit b53373
Network support for the Lua language
Packit b53373
Packit b53373
Packit b53373

Packit b53373
home ·
Packit b53373
download ·
Packit b53373
installation ·
Packit b53373
introduction ·
Packit b53373
reference 
Packit b53373

Packit b53373
</center>
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

MIME

Packit b53373
Packit b53373

Packit b53373
The <tt>mime</tt> namespace offers filters that apply and remove common
Packit b53373
content transfer encodings, such as Base64 and Quoted-Printable.
Packit b53373
It also provides functions to break text into lines and change
Packit b53373
the end-of-line convention.
Packit b53373
MIME is described mainly in 
Packit b53373
RFC 2045,
Packit b53373
2046,
Packit b53373
2047,
Packit b53373
2048, and
Packit b53373
2049.
Packit b53373

Packit b53373
Packit b53373

Packit b53373
All functionality provided by the MIME module 
Packit b53373
follows the ideas presented in 
Packit b53373
Packit b53373
LTN012, Filters sources and sinks. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
To obtain the <tt>mime</tt> namespace, run:
Packit b53373

Packit b53373
Packit b53373
Packit b53373
-- loads the MIME module and everything it requires
Packit b53373
local mime = require("mime")
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

High-level filters

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
mime.normalize([marker])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Converts most common end-of-line markers to a specific given marker. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic 
Packit b53373
end-of-line marker defined by the MIME standard.
Packit b53373

Packit b53373
Packit b53373

Packit b53373
The function returns a filter that performs the conversion. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Note: There is no perfect solution to this problem. Different end-of-line
Packit b53373
markers are an evil that will probably plague developers forever. 
Packit b53373
This function, however, will work perfectly for text created with any of
Packit b53373
the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF), 
Packit b53373
or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
Packit b53373
markers, the function will still work well, although it doesn't 
Packit b53373
guarantee that the number of empty lines will be correct.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
mime.decode("base64")
Packit b53373
mime.decode("quoted-printable")
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Returns a filter that decodes data from a given transfer content
Packit b53373
encoding.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
mime.encode("base64")
Packit b53373
mime.encode("quoted-printable" [, mode])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Returns a filter that encodes data according to a given transfer content
Packit b53373
encoding.
Packit b53373

Packit b53373
Packit b53373

Packit b53373
In the Quoted-Printable case, the user can specify whether the data is
Packit b53373
textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or
Packit b53373
"<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>".
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Although both transfer content encodings specify a limit for the line
Packit b53373
length, the encoding filters do not break text into lines (for
Packit b53373
added flexibility). 
Packit b53373
Below is a filter that converts binary data to the Base64 transfer content
Packit b53373
encoding and breaks it into lines of the correct size.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
base64 = ltn12.filter.chain(
Packit b53373
  mime.encode("base64"),
Packit b53373
  mime.wrap("base64")
Packit b53373
)
Packit b53373
Packit b53373
Packit b53373

Packit b53373
Note: Text data has to be converted to canonic form
Packit b53373
before being encoded.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
base64 = ltn12.filter.chain(
Packit b53373
  mime.normalize(),
Packit b53373
  mime.encode("base64"),
Packit b53373
  mime.wrap("base64")
Packit b53373
)
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
mime.stuff()
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Creates and returns a filter that performs stuffing of SMTP messages.
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Note: The <tt>smtp.send</tt> function 
Packit b53373
uses this filter automatically. You don't need to chain it with your
Packit b53373
source, or apply it to your message body.  
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
mime.wrap("text" [, length])
Packit b53373
mime.wrap("base64")
Packit b53373
mime.wrap("quoted-printable")
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Returns a filter that breaks data into lines. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
The "<tt>text</tt>" line-wrap filter simply breaks text into lines by 
Packit b53373
inserting CRLF end-of-line markers at appropriate positions. 
Packit b53373
<tt>Length</tt> defaults 76. 
Packit b53373
The "<tt>base64</tt>" line-wrap filter works just like the default
Packit b53373
"<tt>text</tt>" line-wrap filter with default length. 
Packit b53373
The function can also wrap "<tt>quoted-printable</tt>" lines, taking care
Packit b53373
not to break lines in the middle of an escaped character. In that case, the
Packit b53373
line length is fixed at 76.
Packit b53373

Packit b53373
Packit b53373

Packit b53373
For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
Packit b53373

Packit b53373
Packit b53373
Packit b53373
qp = ltn12.filter.chain(
Packit b53373
  mime.normalize(),
Packit b53373
  mime.encode("quoted-printable"),
Packit b53373
  mime.wrap("quoted-printable")
Packit b53373
)
Packit b53373
Packit b53373
Packit b53373

Packit b53373
Note: To break into lines with a different end-of-line convention, apply
Packit b53373
a normalization filter after the line break filter. 
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Low-level filters

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
A, B = mime.b64(C [, D])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Low-level filter to perform Base64 encoding. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>A</tt> is the encoded version of the largest prefix of 
Packit b53373
<tt>C..D</tt> 
Packit b53373
that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of 
Packit b53373
<tt>C..D</tt>, before encoding. 
Packit b53373
If <tt>D</tt> is <tt>nil</tt>, <tt>A</tt> is padded with 
Packit b53373
the encoding of the remaining bytes of <tt>C</tt>. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Note: The simplest use of this function is to encode a string into it's
Packit b53373
Base64 transfer content encoding. Notice the extra parenthesis around the
Packit b53373
call to <tt>mime.b64</tt>, to discard the second return value.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
print((mime.b64("diego:password")))
Packit b53373
--> ZGllZ286cGFzc3dvcmQ=
Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
A, n = mime.dot(m [, B])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Low-level filter to perform SMTP stuffing and enable transmission of
Packit b53373
messages containing the sequence "CRLF.CRLF". 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the
Packit b53373
number of characters from the sequence CRLF seen in the end of <tt>B</tt>.
Packit b53373
'<tt>m</tt>' should tell the same, but for the previous chunk.
Packit b53373

Packit b53373
Packit b53373

Note: The message body is defined to begin with

Packit b53373
an implicit CRLF. Therefore, to stuff a message correctly, the
Packit b53373
first <tt>m</tt> should have the value 2. 
Packit b53373

Packit b53373
Packit b53373
Packit b53373
print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n")))
Packit b53373
--> ..\nStuffing the message.\n..\n..
Packit b53373
Packit b53373
Packit b53373

Packit b53373
Note: The <tt>smtp.send</tt> function 
Packit b53373
uses this filter automatically. You don't need to 
Packit b53373
apply it again. 
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
A, B = mime.eol(C [, D, marker])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Low-level filter to perform end-of-line marker translation. 
Packit b53373
For each chunk, the function needs to know if the last character of the
Packit b53373
previous chunk could be part of an end-of-line marker or not. This is the
Packit b53373
context the function receives besides the chunk.  An updated version of
Packit b53373
the context is returned after each new chunk. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the
Packit b53373
ASCII value of the last character of the previous chunk, if it was a
Packit b53373
candidate for line break, or 0 otherwise. 
Packit b53373
<tt>B</tt> is the same as <tt>C</tt>, but for the current
Packit b53373
chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
-- translates the end-of-line marker to UNIX
Packit b53373
unix = mime.eol(0, dos, "\n") 
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
A, B = mime.qp(C [, D, marker])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Low-level filter to perform Quoted-Printable encoding. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>A</tt> is the encoded version of the largest prefix of 
Packit b53373
<tt>C..D</tt> 
Packit b53373
that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of 
Packit b53373
<tt>C..D</tt>, before encoding. 
Packit b53373
If <tt>D</tt> is <tt>nil</tt>, <tt>A</tt> is padded with 
Packit b53373
the encoding of the remaining bytes of <tt>C</tt>. 
Packit b53373
Throughout encoding, occurrences of CRLF are replaced by the 
Packit b53373
<tt>marker</tt>, which itself defaults to CRLF.
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Note: The simplest use of this function is to encode a string into it's
Packit b53373
Quoted-Printable transfer content encoding. 
Packit b53373
Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
print((mime.qp("maçã")))
Packit b53373
--> ma=E7=E3=
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
A, m = mime.qpwrp(n [, B, length])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Low-level filter to break Quoted-Printable text into lines. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most 
Packit b53373
<tt>length</tt> bytes (defaults to 76). 
Packit b53373
'<tt>n</tt>' should tell how many bytes are left for the first 
Packit b53373
line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes 
Packit b53373
left in the last line of <tt>A</tt>. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Note: Besides breaking text into lines, this function makes sure the line
Packit b53373
breaks don't fall in the middle of an escaped character combination. Also,
Packit b53373
this function only breaks lines that are bigger than <tt>length</tt> bytes.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
A, B = mime.unb64(C [, D])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Low-level filter to perform Base64 decoding. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>A</tt> is the decoded version of the largest prefix of 
Packit b53373
<tt>C..D</tt> 
Packit b53373
that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of 
Packit b53373
<tt>C..D</tt>, before decoding. 
Packit b53373
If <tt>D</tt> is <tt>nil</tt>, <tt>A</tt> is the empty string
Packit b53373
and <tt>B</tt> returns whatever couldn't be decoded. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Note: The simplest use of this function is to decode a string from it's
Packit b53373
Base64 transfer content encoding. 
Packit b53373
Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
Packit b53373
--> diego:password
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
A, B = mime.unqp(C [, D])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Low-level filter to remove the Quoted-Printable transfer content encoding
Packit b53373
from data. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>A</tt> is the decoded version of the largest prefix of 
Packit b53373
<tt>C..D</tt> 
Packit b53373
that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of 
Packit b53373
<tt>C..D</tt>, before decoding. 
Packit b53373
If <tt>D</tt> is <tt>nil</tt>, <tt>A</tt> is augmented with 
Packit b53373
the encoding of the remaining bytes of <tt>C</tt>. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Note: The simplest use of this function is to decode a string from it's
Packit b53373
Quoted-Printable transfer content encoding. 
Packit b53373
Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
print((mime.qp("ma=E7=E3=")))
Packit b53373
--> maçã
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
A, m = mime.wrp(n [, B, length])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Low-level filter to break text into lines with CRLF marker. 
Packit b53373
Text is assumed to be in the <tt>normalize</tt> form.
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most 
Packit b53373
<tt>length</tt> bytes (defaults to 76). 
Packit b53373
'<tt>n</tt>' should tell how many bytes are left for the first 
Packit b53373
line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes 
Packit b53373
left in the last line of <tt>A</tt>. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Note: This function only breaks lines that are bigger than 
Packit b53373
<tt>length</tt> bytes. The resulting line length does not include the CRLF
Packit b53373
marker.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
<center>
Packit b53373

Packit b53373
home ·
Packit b53373
download ·
Packit b53373
installation ·
Packit b53373
introduction ·
Packit b53373
reference
Packit b53373

Packit b53373

Packit b53373
<small>
Packit b53373
Last modified by Diego Nehab on 
Packit b53373
Thu Apr 20 00:25:44 EDT 2006
Packit b53373
</small>
Packit b53373

Packit b53373
</center>
Packit b53373
Packit b53373
Packit b53373
</body>
Packit b53373
</html>