zyppe/luasocket
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

LuaSocket 2.0 User's Manual.

Browse source
This commit is contained in:
Diego Nehab 2003-08-31 01:00:15 +00:00
parent 6789b83ff5
commit 982781f146
14 changed files with 3223 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

228
doc/smtp.html Normal file
View file

@ -0,0 +1,228 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</title>
<link rel="stylesheet" href="reference.css" type="text/css">
</head>
<body>
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header>
<hr>
<center>
<table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org">
<img border=0 alt="LuaSocket" src="luasocket.png">
</a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language
</td></tr>
</table>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=smtp>SMTP</h2>
<p>
The module <tt>smtp.lua</tt> provides functionality to send e-mail
messages. The implementation conforms to the Simple Mail Transfer Protocol,
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
The other RFC of interest in this implementation is
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
which governs the Internet Message Format.
</p>
<p>
MIME headers are represented as a Lua table in the form:
</p>
<blockquote>
<table summary="MIME headers in Lua table">
<tr><td><tt>
headers = {<br>
&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,
</tt></td></tr>
<tr><td align=center><tt>
&nbsp;&nbsp;...
</tt></td></tr>
<tr><td><tt>
&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
}
</tt></td></tr>
</table>
</blockquote>
<p>
Field names are case insensitive (as specified by the standard) and all
functions work with lowercase field names.
Field values are left unmodified.
</p>
<p class=note>
Note: MIME headers are independent of order. Therefore, there is no problem
in representing them in a Lua table.
</p>
<!-- mail +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=mail>
socket.smtp.<b>mail{</b><br>
&nbsp;&nbsp;from = <i>string</i>,<br>
&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
&nbsp;&nbsp;body = <i>string</i>,<br>
&nbsp;&nbsp;headers = <i>headers-table</i>,<br>
&nbsp;&nbsp;server = <i>string</i><br>
<b>}</b>
</p>
<p class=description>
Sends a message to a recipient list.
</p>
<p class=parameters>
<tt>Rcpt</tt> is a Lua table with one entry for each recipient, or a string
in case there is just one recipient.
The sender is given by the e-mail address <tt>from</tt>.
The message is composed by the optional MIME Headers <tt>headers</tt>
and text <tt>body</tt>. The message is sent using the server
<tt>server</tt>.
</p>
<p class=return>
If successful, the function returns 1. Otherwise, the function returns
<tt>nil</tt> followed by an error message.
</p>
<p class=note>
Big note: There is a good deal of misconception with the use of the
destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
'<tt>Bcc</tt>' header to your messages because it will probably do the
exact opposite of what you expect.
</p>
<p class=note>
Only recipients specified in the recipient list will receive a copy of the
message. Each recipient of an SMTP mail message receives a copy of the
message body along with the headers, and nothing more. The headers are
considered as part of the message. The list of recipients is <em>not</em>
part of the message.
</p>
<p class=note>
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>
has two <em>important and short</em> sections, "3.6.3. Destination address
fields" and "5. Security considerations", explaining the proper
use of these headers. Here is a summary of what it says:
</p>
<ul>
<li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
of the message;
<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of
making a copy on a typewriter using carbon paper) contains the
addresses of others who are to receive the message, though the
content of the message may not be directed at them;
<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon
Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message.
</ul>
<p class=note>
The LuaSocket <tt>mail</tt> function does not interpret the headers you
pass to, but it gives you full control over what is sent and to whom
it is sent:
</p>
<ul>
<li> If someone is to receive the message, the e-mail address <em>has</em>
to be in the recipient list. This is the only parameter that controls who
gets a copy of the message;
<li> If there are multiple recipients, none of them will automatically
know that someone else got that message. That is, the default behavior is
similar to the <tt>Bcc</tt> field of popular e-mail clients;
<li> It is up to you to add the <tt>To</tt> header with the list of primary
recipients so that other recipients can see it;
<li> It is also up to you to add the <tt>Cc</tt> header with the
list of additional recipients so that everyone else sees it;
<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is
empty. Otherwise, everyone receiving the message will see it and that is
exactly what you <em>don't</em> want to happen!
</ul>
<p class=note>
I hope this clarifies the issue. Otherwise, please refer to
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>
and
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>.
</p>
<pre class=example>
-- Connects to server "localhost" and sends a message to users
-- "fulano@tecgraf.puc-rio.br", "beltrano@tecgraf.puc-rio.br",
-- and "sicrano@tecgraf.puc-rio.br".
-- Note that "fulano" is the primary recipient, "beltrano" receives a
-- carbon copy and neither of them knows that "sicrano" received a blind
-- carbon copy of the message.
headers = {
to = "fulano@tecgraf.puc-rio.br",
cc = "beltrano@tecgraf.puc-rio.br",
subject = "LuaSocket test message"
}
from = "luasocket@tecgraf.puc-rio.br"
rcpt = {
"fulano@tecgraf.puc-rio.br",
"beltrano@tecgraf.puc-rio.br",
"sicrano@tecgraf.puc-rio.br"
}
body = "This is a test message. Please ignore."
server = "localhost"
r, e = socket.smtp.mail{
from = from,
rcpt = rcpt,
headers = headers,
body = body,
server = server
}
</pre>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>