diff options
| author | Caleb Maclennan <caleb@alerque.com> | 2022-03-23 00:09:53 +0300 |
|---|---|---|
| committer | Caleb Maclennan <caleb@alerque.com> | 2022-03-23 00:11:24 +0300 |
| commit | f98977b2dac48fc66822402b095336e683715126 (patch) | |
| tree | 890645acb9d4f8ace095add229447b7c2411a138 /docs | |
| parent | c1eacfa6d24dc15476f5f9befa8370e2244931d4 (diff) | |
| download | luasocket-f98977b2dac48fc66822402b095336e683715126.tar.gz luasocket-f98977b2dac48fc66822402b095336e683715126.tar.bz2 luasocket-f98977b2dac48fc66822402b095336e683715126.zip | |
Move doc→docs so we can serve it with GitHub Pages
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/dns.html | 183 | ||||
| -rw-r--r-- | docs/ftp.html | 288 | ||||
| -rw-r--r-- | docs/http.html | 339 | ||||
| -rw-r--r-- | docs/index.html | 215 | ||||
| -rw-r--r-- | docs/installation.html | 127 | ||||
| -rw-r--r-- | docs/introduction.html | 333 | ||||
| -rw-r--r-- | docs/ltn12.html | 440 | ||||
| -rw-r--r-- | docs/lua05.ppt | bin | 0 -> 304128 bytes | |||
| -rw-r--r-- | docs/luasocket.png | bin | 0 -> 11732 bytes | |||
| -rw-r--r-- | docs/mime.html | 477 | ||||
| -rw-r--r-- | docs/reference.css | 55 | ||||
| -rw-r--r-- | docs/reference.html | 261 | ||||
| -rw-r--r-- | docs/smtp.html | 419 | ||||
| -rw-r--r-- | docs/socket.html | 481 | ||||
| -rw-r--r-- | docs/tcp.html | 732 | ||||
| -rw-r--r-- | docs/udp.html | 596 | ||||
| -rw-r--r-- | docs/url.html | 328 |
17 files changed, 5274 insertions, 0 deletions
diff --git a/docs/dns.html b/docs/dns.html new file mode 100644 index 0000000..56ce3ba --- /dev/null +++ b/docs/dns.html | |||
| @@ -0,0 +1,183 @@ | |||
| 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: DNS support"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, DNS, Network, Library, Support"> | ||
| 8 | <title>LuaSocket: DNS support</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> · | ||
| 28 | <a href="index.html#download">download</a> · | ||
| 29 | <a href="installation.html">installation</a> · | ||
| 30 | <a href="introduction.html">introduction</a> · | ||
| 31 | <a href="reference.html">reference</a> | ||
| 32 | </p> | ||
| 33 | </center> | ||
| 34 | <hr> | ||
| 35 | </div> | ||
| 36 | |||
| 37 | <!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 38 | |||
| 39 | <h2 id="dns">DNS</h2> | ||
| 40 | |||
| 41 | <p> | ||
| 42 | IPv4 name resolution functions | ||
| 43 | <a href="#toip"><tt>dns.toip</tt></a> | ||
| 44 | and | ||
| 45 | <a href="#tohostname"><tt>dns.tohostname</tt></a> | ||
| 46 | return <em>all</em> information obtained from | ||
| 47 | the resolver in a table of the form: | ||
| 48 | </p> | ||
| 49 | |||
| 50 | <blockquote><tt> | ||
| 51 | resolved4 = {<br> | ||
| 52 | name = <i>canonic-name</i>,<br> | ||
| 53 | alias = <i>alias-list</i>,<br> | ||
| 54 | ip = <i>ip-address-list</i><br> | ||
| 55 | } | ||
| 56 | </tt> </blockquote> | ||
| 57 | |||
| 58 | <p> | ||
| 59 | Note that the <tt>alias</tt> list can be empty. | ||
| 60 | </p> | ||
| 61 | |||
| 62 | <p> | ||
| 63 | The more general name resolution function | ||
| 64 | <a href="#getaddrinfo"><tt>dns.getaddrinfo</tt></a>, which | ||
| 65 | supports both IPv6 and IPv4, | ||
| 66 | returns <em>all</em> information obtained from | ||
| 67 | the resolver in a table of the form: | ||
| 68 | </p> | ||
| 69 | |||
| 70 | <blockquote><tt> | ||
| 71 | resolved6 = {<br> | ||
| 72 | [1] = {<br> | ||
| 73 | family = <i>family-name-1</i>,<br> | ||
| 74 | addr = <i>address-1</i><br> | ||
| 75 | },<br> | ||
| 76 | ...<br> | ||
| 77 | [n] = {<br> | ||
| 78 | family = <i>family-name-n</i>,<br> | ||
| 79 | addr = <i>address-n</i><br> | ||
| 80 | }<br> | ||
| 81 | } | ||
| 82 | </tt> </blockquote> | ||
| 83 | |||
| 84 | <p> | ||
| 85 | Here, <tt>family</tt> contains the string <tt>"inet"</tt> for IPv4 | ||
| 86 | addresses, and <tt>"inet6"</tt> for IPv6 addresses. | ||
| 87 | </p> | ||
| 88 | |||
| 89 | <!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 90 | |||
| 91 | <p class="name" id="getaddrinfo"> | ||
| 92 | socket.dns.<b>getaddrinfo(</b>address<b>)</b> | ||
| 93 | </p> | ||
| 94 | |||
| 95 | <p class="description"> | ||
| 96 | Converts from host name to address. | ||
| 97 | </p> | ||
| 98 | |||
| 99 | <p class="parameters"> | ||
| 100 | <tt>Address</tt> can be an IPv4 or IPv6 address or host name. | ||
| 101 | </p> | ||
| 102 | |||
| 103 | <p class="return"> | ||
| 104 | The function returns a table with all information returned by | ||
| 105 | the resolver. In case of error, the function returns <b><tt>nil</tt></b> | ||
| 106 | followed by an error message. | ||
| 107 | </p> | ||
| 108 | |||
| 109 | <!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 110 | |||
| 111 | <p class="name" id="gethostname"> | ||
| 112 | socket.dns.<b>gethostname()</b> | ||
| 113 | </p> | ||
| 114 | |||
| 115 | <p class="description"> | ||
| 116 | Returns the standard host name for the machine as a string. | ||
| 117 | </p> | ||
| 118 | |||
| 119 | <!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 120 | |||
| 121 | <p class="name" id="tohostname"> | ||
| 122 | socket.dns.<b>tohostname(</b>address<b>)</b> | ||
| 123 | </p> | ||
| 124 | |||
| 125 | <p class="description"> | ||
| 126 | Converts from IPv4 address to host name. | ||
| 127 | </p> | ||
| 128 | |||
| 129 | <p class="parameters"> | ||
| 130 | <tt>Address</tt> can be an IP address or host name. | ||
| 131 | </p> | ||
| 132 | |||
| 133 | <p class="return"> | ||
| 134 | The function returns a string with the canonic host name of the given | ||
| 135 | <tt>address</tt>, followed by a table with all information returned by | ||
| 136 | the resolver. In case of error, the function returns <b><tt>nil</tt></b> | ||
| 137 | followed by an error message. | ||
| 138 | </p> | ||
| 139 | |||
| 140 | <!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 141 | |||
| 142 | <p class="name" id="toip"> | ||
| 143 | socket.dns.<b>toip(</b>address<b>)</b> | ||
| 144 | </p> | ||
| 145 | |||
| 146 | <p class="description"> | ||
| 147 | Converts from host name to IPv4 address. | ||
| 148 | </p> | ||
| 149 | |||
| 150 | <p class="parameters"> | ||
| 151 | <tt>Address</tt> can be an IP address or host name. | ||
| 152 | </p> | ||
| 153 | |||
| 154 | <p class="return"> | ||
| 155 | Returns a string with the first IP address found for <tt>address</tt>, | ||
| 156 | followed by a table with all information returned by the resolver. | ||
| 157 | In case of error, the function returns <b><tt>nil</tt></b> followed by an error | ||
| 158 | message. | ||
| 159 | </p> | ||
| 160 | |||
| 161 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 162 | |||
| 163 | <div class="footer"> | ||
| 164 | <hr> | ||
| 165 | <center> | ||
| 166 | <p class="bar"> | ||
| 167 | <a href="index.html">home</a> · | ||
| 168 | <a href="index.html#down">download</a> · | ||
| 169 | <a href="installation.html">installation</a> · | ||
| 170 | <a href="introduction.html">introduction</a> · | ||
| 171 | <a href="reference.html">reference</a> | ||
| 172 | </p> | ||
| 173 | <p> | ||
| 174 | <small> | ||
| 175 | Last modified by Diego Nehab on <br> | ||
| 176 | Thu Apr 20 00:25:07 EDT 2006 | ||
| 177 | </small> | ||
| 178 | </p> | ||
| 179 | </center> | ||
| 180 | </div> | ||
| 181 | |||
| 182 | </body> | ||
| 183 | </html> | ||
diff --git a/docs/ftp.html b/docs/ftp.html new file mode 100644 index 0000000..7f7da2e --- /dev/null +++ b/docs/ftp.html | |||
| @@ -0,0 +1,288 @@ | |||
| 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: FTP support"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, FTP, Network, Library, Support"> | ||
| 8 | <title>LuaSocket: FTP support</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> · | ||
| 28 | <a href="index.html#download">download</a> · | ||
| 29 | <a href="installation.html">installation</a> · | ||
| 30 | <a href="introduction.html">introduction</a> · | ||
| 31 | <a href="reference.html">reference</a> | ||
| 32 | </p> | ||
| 33 | </center> | ||
| 34 | <hr> | ||
| 35 | </div> | ||
| 36 | |||
| 37 | <!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 38 | |||
| 39 | <h2 id="ftp">FTP</h2> | ||
| 40 | |||
| 41 | <p> | ||
| 42 | FTP (File Transfer Protocol) is a protocol used to transfer files | ||
| 43 | between hosts. The <tt>ftp</tt> namespace offers thorough support | ||
| 44 | to FTP, under a simple interface. The implementation conforms to | ||
| 45 | <a href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</a>. | ||
| 46 | </p> | ||
| 47 | |||
| 48 | <p> | ||
| 49 | High level functions are provided supporting the most common operations. | ||
| 50 | These high level functions are implemented on top of a lower level | ||
| 51 | interface. Using the low-level interface, users can easily create their | ||
| 52 | own functions to access <em>any</em> operation supported by the FTP | ||
| 53 | protocol. For that, check the implementation. | ||
| 54 | </p> | ||
| 55 | |||
| 56 | <p> | ||
| 57 | To really benefit from this module, a good understanding of | ||
| 58 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> | ||
| 59 | LTN012, Filters sources and sinks</a> is necessary. | ||
| 60 | </p> | ||
| 61 | |||
| 62 | <p> | ||
| 63 | To obtain the <tt>ftp</tt> namespace, run: | ||
| 64 | </p> | ||
| 65 | |||
| 66 | <pre class="example"> | ||
| 67 | -- loads the FTP module and any libraries it requires | ||
| 68 | local ftp = require("socket.ftp") | ||
| 69 | </pre> | ||
| 70 | |||
| 71 | <p> | ||
| 72 | URLs MUST conform to | ||
| 73 | <a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, | ||
| 74 | that is, an URL is a string in the form: | ||
| 75 | </p> | ||
| 76 | |||
| 77 | <blockquote> | ||
| 78 | <tt> | ||
| 79 | [ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][<i>type</i>=a|i]</tt> | ||
| 80 | </blockquote> | ||
| 81 | |||
| 82 | <p> | ||
| 83 | The following constants in the namespace can be set to control the default behavior of | ||
| 84 | the FTP module: | ||
| 85 | </p> | ||
| 86 | |||
| 87 | <ul> | ||
| 88 | <li> <tt>PASSWORD</tt>: default anonymous password.</li> | ||
| 89 | <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li> | ||
| 90 | <li> <tt>USER</tt>: default anonymous user;</li> | ||
| 91 | </ul> | ||
| 92 | |||
| 93 | |||
| 94 | <!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 95 | |||
| 96 | <p class="name" id="get"> | ||
| 97 | ftp.<b>get(</b>url<b>)</b><br> | ||
| 98 | ftp.<b>get{</b><br> | ||
| 99 | host = <i>string</i>,<br> | ||
| 100 | sink = <i>LTN12 sink</i>,<br> | ||
| 101 | argument <i>or</i> path = <i>string</i>,<br> | ||
| 102 | [user = <i>string</i>,]<br> | ||
| 103 | [password = <i>string</i>]<br> | ||
| 104 | [command = <i>string</i>,]<br> | ||
| 105 | [port = <i>number</i>,]<br> | ||
| 106 | [type = <i>string</i>,]<br> | ||
| 107 | [step = <i>LTN12 pump step</i>,]<br> | ||
| 108 | [create = <i>function</i>]<br> | ||
| 109 | <b>}</b> | ||
| 110 | </p> | ||
| 111 | |||
| 112 | <p class="description"> | ||
| 113 | The <tt>get</tt> function has two forms. The simple form has fixed | ||
| 114 | functionality: it downloads the contents of a URL and returns it as a | ||
| 115 | string. The generic form allows a <em>lot</em> more control, as explained | ||
| 116 | below. | ||
| 117 | </p> | ||
| 118 | |||
| 119 | <p class="parameters"> | ||
| 120 | If the argument of the <tt>get</tt> function is a table, the function | ||
| 121 | expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of | ||
| 122 | <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes | ||
| 123 | precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is | ||
| 124 | the <em>simple</em> | ||
| 125 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 126 | sink that will receive the downloaded data. <tt>Argument</tt> or | ||
| 127 | <tt>path</tt> give the target path to the resource in the server. The | ||
| 128 | optional arguments are the following: | ||
| 129 | </p> | ||
| 130 | <ul> | ||
| 131 | <li><tt>user</tt>, <tt>password</tt>: User name and password used for | ||
| 132 | authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li> | ||
| 133 | <li><tt>command</tt>: The FTP command used to obtain data. Defaults to | ||
| 134 | "<tt>retr</tt>", but see example below;</li> | ||
| 135 | <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li> | ||
| 136 | <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or | ||
| 137 | "<tt>a</tt>". Defaults to whatever is the server default;</li> | ||
| 138 | <li><tt>step</tt>: | ||
| 139 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 140 | pump step function used to pass data from the | ||
| 141 | server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li> | ||
| 142 | <li><tt>create</tt>: An optional function to be used instead of | ||
| 143 | <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li> | ||
| 144 | </ul> | ||
| 145 | |||
| 146 | <p class="return"> | ||
| 147 | If successful, the simple version returns the URL contents as a | ||
| 148 | string, and the generic function returns 1. In case of error, both | ||
| 149 | functions return <b><tt>nil</tt></b> and an error message describing the | ||
| 150 | error. | ||
| 151 | </p> | ||
| 152 | |||
| 153 | <pre class="example"> | ||
| 154 | -- load the ftp support | ||
| 155 | local ftp = require("socket.ftp") | ||
| 156 | |||
| 157 | -- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br", | ||
| 158 | -- and get file "lua.tar.gz" from directory "pub/lua" as binary. | ||
| 159 | f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i") | ||
| 160 | </pre> | ||
| 161 | |||
| 162 | <pre class="example"> | ||
| 163 | -- load needed modules | ||
| 164 | local ftp = require("socket.ftp") | ||
| 165 | local ltn12 = require("ltn12") | ||
| 166 | local url = require("socket.url") | ||
| 167 | |||
| 168 | -- a function that returns a directory listing | ||
| 169 | function nlst(u) | ||
| 170 | local t = {} | ||
| 171 | local p = url.parse(u) | ||
| 172 | p.command = "nlst" | ||
| 173 | p.sink = ltn12.sink.table(t) | ||
| 174 | local r, e = ftp.get(p) | ||
| 175 | return r and table.concat(t), e | ||
| 176 | end | ||
| 177 | </pre> | ||
| 178 | |||
| 179 | <!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 180 | |||
| 181 | <p class="name" id="put"> | ||
| 182 | ftp.<b>put(</b>url, content<b>)</b><br> | ||
| 183 | ftp.<b>put{</b><br> | ||
| 184 | host = <i>string</i>,<br> | ||
| 185 | source = <i>LTN12 sink</i>,<br> | ||
| 186 | argument <i>or</i> path = <i>string</i>,<br> | ||
| 187 | [user = <i>string</i>,]<br> | ||
| 188 | [password = <i>string</i>]<br> | ||
| 189 | [command = <i>string</i>,]<br> | ||
| 190 | [port = <i>number</i>,]<br> | ||
| 191 | [type = <i>string</i>,]<br> | ||
| 192 | [step = <i>LTN12 pump step</i>,]<br> | ||
| 193 | [create = <i>function</i>]<br> | ||
| 194 | <b>}</b> | ||
| 195 | </p> | ||
| 196 | |||
| 197 | <p class="description"> | ||
| 198 | The <tt>put</tt> function has two forms. The simple form has fixed | ||
| 199 | functionality: it uploads a string of content into a URL. The generic form | ||
| 200 | allows a <em>lot</em> more control, as explained below. | ||
| 201 | </p> | ||
| 202 | |||
| 203 | <p class="parameters"> | ||
| 204 | If the argument of the <tt>put</tt> function is a table, the function | ||
| 205 | expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of | ||
| 206 | <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes | ||
| 207 | precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is | ||
| 208 | the <em>simple</em> | ||
| 209 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 210 | source that will provide the contents to be uploaded. | ||
| 211 | <tt>Argument</tt> or | ||
| 212 | <tt>path</tt> give the target path to the resource in the server. The | ||
| 213 | optional arguments are the following: | ||
| 214 | </p> | ||
| 215 | <ul> | ||
| 216 | <li><tt>user</tt>, <tt>password</tt>: User name and password used for | ||
| 217 | authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li> | ||
| 218 | <li><tt>command</tt>: The FTP command used to send data. Defaults to | ||
| 219 | "<tt>stor</tt>", but see example below;</li> | ||
| 220 | <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li> | ||
| 221 | <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or | ||
| 222 | "<tt>a</tt>". Defaults to whatever is the server default;</li> | ||
| 223 | <li><tt>step</tt>: | ||
| 224 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 225 | pump step function used to pass data from the | ||
| 226 | server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li> | ||
| 227 | <li><tt>create</tt>: An optional function to be used instead of | ||
| 228 | <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li> | ||
| 229 | </ul> | ||
| 230 | |||
| 231 | <p class="return"> | ||
| 232 | Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error | ||
| 233 | message describing the reason for failure. | ||
| 234 | </p> | ||
| 235 | |||
| 236 | <pre class="example"> | ||
| 237 | -- load the ftp support | ||
| 238 | local ftp = require("socket.ftp") | ||
| 239 | |||
| 240 | -- Log as user "fulano" on server "ftp.example.com", | ||
| 241 | -- using password "silva", and store a file "README" with contents | ||
| 242 | -- "wrong password, of course" | ||
| 243 | f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README", | ||
| 244 | "wrong password, of course") | ||
| 245 | </pre> | ||
| 246 | |||
| 247 | <pre class="example"> | ||
| 248 | -- load the ftp support | ||
| 249 | local ftp = require("socket.ftp") | ||
| 250 | local ltn12 = require("ltn12") | ||
| 251 | |||
| 252 | -- Log as user "fulano" on server "ftp.example.com", | ||
| 253 | -- using password "silva", and append to the remote file "LOG", sending the | ||
| 254 | -- contents of the local file "LOCAL-LOG" | ||
| 255 | f, e = ftp.put{ | ||
| 256 | host = "ftp.example.com", | ||
| 257 | user = "fulano", | ||
| 258 | password = "silva", | ||
| 259 | command = "appe", | ||
| 260 | argument = "LOG", | ||
| 261 | source = ltn12.source.file(io.open("LOCAL-LOG", "r")) | ||
| 262 | } | ||
| 263 | </pre> | ||
| 264 | |||
| 265 | |||
| 266 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 267 | |||
| 268 | <div class="footer"> | ||
| 269 | <hr> | ||
| 270 | <center> | ||
| 271 | <p class="bar"> | ||
| 272 | <a href="index.html">home</a> · | ||
| 273 | <a href="index.html#download">download</a> · | ||
| 274 | <a href="installation.html">installation</a> · | ||
| 275 | <a href="introduction.html">introduction</a> · | ||
| 276 | <a href="reference.html">reference</a> | ||
| 277 | </p> | ||
| 278 | <p> | ||
| 279 | <small> | ||
| 280 | Last modified by Diego Nehab on <br> | ||
| 281 | Thu Apr 20 00:25:18 EDT 2006 | ||
| 282 | </small> | ||
| 283 | </p> | ||
| 284 | </center> | ||
| 285 | </div> | ||
| 286 | |||
| 287 | </body> | ||
| 288 | </html> | ||
diff --git a/docs/http.html b/docs/http.html new file mode 100644 index 0000000..52b8a30 --- /dev/null +++ b/docs/http.html | |||
| @@ -0,0 +1,339 @@ | |||
| 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: HTTP support"> | ||
| 7 | <meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support"> | ||
| 8 | <title>LuaSocket: HTTP support</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> · | ||
| 28 | <a href="index.html#download">download</a> · | ||
| 29 | <a href="introduction.html">introduction</a> · | ||
| 30 | <a href="introduction.html">introduction</a> · | ||
| 31 | <a href="reference.html">reference</a> | ||
| 32 | </p> | ||
| 33 | </center> | ||
| 34 | <hr> | ||
| 35 | </div> | ||
| 36 | |||
| 37 | <!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 38 | |||
| 39 | <h2 id="http">HTTP</h2> | ||
| 40 | |||
| 41 | <p> | ||
| 42 | HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange | ||
| 43 | information between web-browsers and servers. The <tt>http</tt> | ||
| 44 | namespace offers full support for the client side of the HTTP | ||
| 45 | protocol (i.e., | ||
| 46 | the facilities that would be used by a web-browser implementation). The | ||
| 47 | implementation conforms to the HTTP/1.1 standard, | ||
| 48 | <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>. | ||
| 49 | </p> | ||
| 50 | |||
| 51 | <p> | ||
| 52 | The module exports functions that provide HTTP functionality in different | ||
| 53 | levels of abstraction. From the simple | ||
| 54 | string oriented requests, through generic | ||
| 55 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based, down to even lower-level if you bother to look through the source code. | ||
| 56 | </p> | ||
| 57 | |||
| 58 | <p> | ||
| 59 | To obtain the <tt>http</tt> namespace, run: | ||
| 60 | </p> | ||
| 61 | |||
| 62 | <pre class="example"> | ||
| 63 | -- loads the HTTP module and any libraries it requires | ||
| 64 | local http = require("socket.http") | ||
| 65 | </pre> | ||
| 66 | |||
| 67 | <p> | ||
| 68 | URLs must conform to | ||
| 69 | <a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, | ||
| 70 | that is, an URL is a string in the form: | ||
| 71 | </p> | ||
| 72 | |||
| 73 | <blockquote> | ||
| 74 | <pre> | ||
| 75 | [http://][<user>[:<password>]@]<host>[:<port>][/<path>] | ||
| 76 | </pre> | ||
| 77 | </blockquote> | ||
| 78 | |||
| 79 | <p> | ||
| 80 | MIME headers are represented as a Lua table in the form: | ||
| 81 | </p> | ||
| 82 | |||
| 83 | <blockquote> | ||
| 84 | <table summary="MIME headers in Lua table"> | ||
| 85 | <tr><td><tt> | ||
| 86 | headers = {<br> | ||
| 87 | field-1-name = <i>field-1-value</i>,<br> | ||
| 88 | field-2-name = <i>field-2-value</i>,<br> | ||
| 89 | field-3-name = <i>field-3-value</i>,<br> | ||
| 90 | ...<br> | ||
| 91 | field-n-name = <i>field-n-value</i><br> | ||
| 92 | } | ||
| 93 | </tt></td></tr> | ||
| 94 | </table> | ||
| 95 | </blockquote> | ||
| 96 | |||
| 97 | <p> | ||
| 98 | Field names are case insensitive (as specified by the standard) and all | ||
| 99 | functions work with lowercase field names (but see | ||
| 100 | <a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>). | ||
| 101 | Field values are left unmodified. | ||
| 102 | </p> | ||
| 103 | |||
| 104 | <p class="note"> | ||
| 105 | Note: MIME headers are independent of order. Therefore, there is no problem | ||
| 106 | in representing them in a Lua table. | ||
| 107 | </p> | ||
| 108 | |||
| 109 | <p> | ||
| 110 | The following constants can be set to control the default behavior of | ||
| 111 | the HTTP module: | ||
| 112 | </p> | ||
| 113 | |||
| 114 | <ul> | ||
| 115 | <li> <tt>PROXY</tt>: default proxy used for connections;</li> | ||
| 116 | <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li> | ||
| 117 | <li> <tt>USERAGENT</tt>: default user agent reported to server.</li> | ||
| 118 | </ul> | ||
| 119 | |||
| 120 | <p class="note"> | ||
| 121 | Note: These constants are global. Changing them will also | ||
| 122 | change the behavior other code that might be using LuaSocket. | ||
| 123 | </p> | ||
| 124 | |||
| 125 | <!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 126 | |||
| 127 | <p class="name" id="request"> | ||
| 128 | http.<b>request(</b>url [, body]<b>)</b><br> | ||
| 129 | http.<b>request{</b><br> | ||
| 130 | url = <i>string</i>,<br> | ||
| 131 | [sink = <i>LTN12 sink</i>,]<br> | ||
| 132 | [method = <i>string</i>,]<br> | ||
| 133 | [headers = <i>header-table</i>,]<br> | ||
| 134 | [source = <i>LTN12 source</i>],<br> | ||
| 135 | [step = <i>LTN12 pump step</i>,]<br> | ||
| 136 | [proxy = <i>string</i>,]<br> | ||
| 137 | [redirect = <i>boolean</i>,]<br> | ||
| 138 | [create = <i>function</i>,]<br> | ||
| 139 | [maxredirects = <i>number</i>]<br> | ||
| 140 | <b>}</b> | ||
| 141 | </p> | ||
| 142 | |||
| 143 | <p class="description"> | ||
| 144 | The request function has two forms. The simple form downloads | ||
| 145 | a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based | ||
| 146 | on strings. The generic form performs any HTTP method and is | ||
| 147 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based. | ||
| 148 | </p> | ||
| 149 | |||
| 150 | <p class="parameters"> | ||
| 151 | If the first argument of the <tt>request</tt> function is a string, it | ||
| 152 | should be an <tt>url</tt>. In that case, if a <tt>body</tt> | ||
| 153 | is provided as a string, the function will perform a <tt>POST</tt> method | ||
| 154 | in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the | ||
| 155 | <tt>url</tt> | ||
| 156 | </p> | ||
| 157 | |||
| 158 | <p class="parameters"> | ||
| 159 | If the first argument is instead a table, the most important fields are | ||
| 160 | the <tt>url</tt> and the <em>simple</em> | ||
| 161 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 162 | <tt>sink</tt> that will receive the downloaded content. | ||
| 163 | Any part of the <tt>url</tt> can be overridden by including | ||
| 164 | the appropriate field in the request table. | ||
| 165 | If authentication information is provided, the function | ||
| 166 | uses the Basic Authentication Scheme (see <a href="#authentication">note</a>) | ||
| 167 | to retrieve the document. If <tt>sink</tt> is <tt><b>nil</b></tt>, the | ||
| 168 | function discards the downloaded data. The optional parameters are the | ||
| 169 | following: | ||
| 170 | </p> | ||
| 171 | <ul> | ||
| 172 | <li><tt>method</tt>: The HTTP request method. Defaults to "GET";</li> | ||
| 173 | <li><tt>headers</tt>: Any additional HTTP headers to send with the request;</li> | ||
| 174 | <li><tt>source</tt>: <em>simple</em> | ||
| 175 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 176 | source to provide the request body. If there | ||
| 177 | is a body, you need to provide an appropriate "<tt>content-length</tt>" | ||
| 178 | request header field, or the function will attempt to send the body as | ||
| 179 | "<tt>chunked</tt>" (something few servers support). Defaults to the empty source;</li> | ||
| 180 | <li><tt>step</tt>: | ||
| 181 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 182 | pump step function used to move data. | ||
| 183 | Defaults to the LTN12 <tt>pump.step</tt> function.</li> | ||
| 184 | <li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;</li> | ||
| 185 | <li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the | ||
| 186 | function from automatically following 301 or 302 server redirect messages;</li> | ||
| 187 | <li><tt>create</tt>: An optional function to be used instead of | ||
| 188 | <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li> | ||
| 189 | <li><tt>maxredirects</tt>: An optional number specifying the maximum number of | ||
| 190 | redirects to follow. Defaults to <tt>5</tt> if not specified. A boolean | ||
| 191 | <tt>false</tt> value means no maximum (unlimited).</li> | ||
| 192 | </ul> | ||
| 193 | |||
| 194 | <p class="return"> | ||
| 195 | In case of failure, the function returns <tt><b>nil</b></tt> followed by an | ||
| 196 | error message. If successful, the simple form returns the response | ||
| 197 | body as a string, followed by the response status code, the response | ||
| 198 | headers and the response status line. The generic function returns the same | ||
| 199 | information, except the first return value is just the number 1 (the body | ||
| 200 | goes to the <tt>sink</tt>). | ||
| 201 | </p> | ||
| 202 | |||
| 203 | <p class="return"> | ||
| 204 | Even when the server fails to provide the contents of the requested URL (URL not found, for example), | ||
| 205 | it usually returns a message body (a web page informing the | ||
| 206 | URL was not found or some other useless page). To make sure the | ||
| 207 | operation was successful, check the returned status <tt>code</tt>. For | ||
| 208 | a list of the possible values and their meanings, refer to <a | ||
| 209 | href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>. | ||
| 210 | </p> | ||
| 211 | |||
| 212 | <p class="description"> | ||
| 213 | Here are a few examples with the simple interface: | ||
| 214 | </p> | ||
| 215 | |||
| 216 | <pre class="example"> | ||
| 217 | -- load the http module | ||
| 218 | local io = require("io") | ||
| 219 | local http = require("socket.http") | ||
| 220 | local ltn12 = require("ltn12") | ||
| 221 | |||
| 222 | -- connect to server "www.cs.princeton.edu" and retrieves this manual | ||
| 223 | -- file from "~diego/professional/luasocket/http.html" and print it to stdout | ||
| 224 | http.request{ | ||
| 225 | url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html", | ||
| 226 | sink = ltn12.sink.file(io.stdout) | ||
| 227 | } | ||
| 228 | |||
| 229 | -- connect to server "www.example.com" and tries to retrieve | ||
| 230 | -- "/private/index.html". Fails because authentication is needed. | ||
| 231 | b, c, h = http.request("http://www.example.com/private/index.html") | ||
| 232 | -- b returns some useless page telling about the denied access, | ||
| 233 | -- h returns authentication information | ||
| 234 | -- and c returns with value 401 (Authentication Required) | ||
| 235 | |||
| 236 | -- tries to connect to server "wrong.host" to retrieve "/" | ||
| 237 | -- and fails because the host does not exist. | ||
| 238 | r, e = http.request("http://wrong.host/") | ||
| 239 | -- r is nil, and e returns with value "host not found" | ||
| 240 | </pre> | ||
| 241 | |||
| 242 | <p class="description"> | ||
| 243 | And here is an example using the generic interface: | ||
| 244 | </p> | ||
| 245 | |||
| 246 | <pre class="example"> | ||
| 247 | -- load the http module | ||
| 248 | http = require("socket.http") | ||
| 249 | |||
| 250 | -- Requests information about a document, without downloading it. | ||
| 251 | -- Useful, for example, if you want to display a download gauge and need | ||
| 252 | -- to know the size of the document in advance | ||
| 253 | r, c, h = http.request { | ||
| 254 | method = "HEAD", | ||
| 255 | url = "http://www.tecgraf.puc-rio.br/~diego" | ||
| 256 | } | ||
| 257 | -- r is 1, c is 200, and h would return the following headers: | ||
| 258 | -- h = { | ||
| 259 | -- date = "Tue, 18 Sep 2001 20:42:21 GMT", | ||
| 260 | -- server = "Apache/1.3.12 (Unix) (Red Hat/Linux)", | ||
| 261 | -- ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT", | ||
| 262 | -- ["content-length"] = 15652, | ||
| 263 | -- ["connection"] = "close", | ||
| 264 | -- ["content-Type"] = "text/html" | ||
| 265 | -- } | ||
| 266 | </pre> | ||
| 267 | |||
| 268 | <p class="note" id="post"> | ||
| 269 | Note: When sending a POST request, simple interface adds a | ||
| 270 | "<tt>Content-type: application/x-www-form-urlencoded</tt>" | ||
| 271 | header to the request. This is the type used by | ||
| 272 | HTML forms. If you need another type, use the generic | ||
| 273 | interface. | ||
| 274 | </p> | ||
| 275 | |||
| 276 | <p class="note" id="authentication"> | ||
| 277 | Note: Some URLs are protected by their | ||
| 278 | servers from anonymous download. For those URLs, the server must receive | ||
| 279 | some sort of authentication along with the request or it will deny | ||
| 280 | download and return status "401 Authentication Required". | ||
| 281 | </p> | ||
| 282 | |||
| 283 | <p class="note"> | ||
| 284 | The HTTP/1.1 standard defines two authentication methods: the Basic | ||
| 285 | Authentication Scheme and the Digest Authentication Scheme, both | ||
| 286 | explained in detail in | ||
| 287 | <a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>. | ||
| 288 | </p> | ||
| 289 | |||
| 290 | <p class="note">The Basic Authentication Scheme sends | ||
| 291 | <tt><user></tt> and | ||
| 292 | <tt><password></tt> unencrypted to the server and is therefore | ||
| 293 | considered unsafe. Unfortunately, by the time of this implementation, | ||
| 294 | the wide majority of servers and browsers support the Basic Scheme only. | ||
| 295 | Therefore, this is the method used by the toolkit whenever | ||
| 296 | authentication is required. | ||
| 297 | </p> | ||
| 298 | |||
| 299 | <pre class="example"> | ||
| 300 | -- load required modules | ||
| 301 | http = require("socket.http") | ||
| 302 | mime = require("mime") | ||
| 303 | |||
| 304 | -- Connect to server "www.example.com" and tries to retrieve | ||
| 305 | -- "/private/index.html", using the provided name and password to | ||
| 306 | -- authenticate the request | ||
| 307 | b, c, h = http.request("http://fulano:silva@www.example.com/private/index.html") | ||
| 308 | |||
| 309 | -- Alternatively, one could fill the appropriate header and authenticate | ||
| 310 | -- the request directly. | ||
| 311 | r, c = http.request { | ||
| 312 | url = "http://www.example.com/private/index.html", | ||
| 313 | headers = { authorization = "Basic " .. (mime.b64("fulano:silva")) } | ||
| 314 | } | ||
| 315 | </pre> | ||
| 316 | |||
| 317 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 318 | |||
| 319 | <div class="footer"> | ||
| 320 | <hr> | ||
| 321 | <center> | ||
| 322 | <p class="bar"> | ||
| 323 | <a href="index.html">home</a> · | ||
| 324 | <a href="index.html#download">download</a> · | ||
| 325 | <a href="installation.html">installation</a> · | ||
| 326 | <a href="introduction.html">introduction</a> · | ||
| 327 | <a href="reference.html">reference</a> | ||
| 328 | </p> | ||
| 329 | <p> | ||
| 330 | <small> | ||
| 331 | Last modified by Eric Westbrook on <br> | ||
| 332 | Sat Feb 23 19:09:42 UTC 2019 | ||
| 333 | </small> | ||
| 334 | </p> | ||
| 335 | </center> | ||
| 336 | </div> | ||
| 337 | |||
| 338 | </body> | ||
| 339 | </html> | ||
diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..e92b4d4 --- /dev/null +++ b/docs/index.html | |||
| @@ -0,0 +1,215 @@ | |||
| 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="The LuaSocket Homepage"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, Network, Library, Support, Internet"> | ||
| 8 | <title>LuaSocket: Network support for the Lua language </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> · | ||
| 28 | <a href="index.html#download">download</a> · | ||
| 29 | <a href="installation.html">installation</a> · | ||
| 30 | <a href="introduction.html">introduction</a> · | ||
| 31 | <a href="reference.html">reference</a> | ||
| 32 | </p> | ||
| 33 | </center> | ||
| 34 | <hr> | ||
| 35 | </div> | ||
| 36 | |||
| 37 | <!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 38 | |||
| 39 | <h2 id="whatis">What is LuaSocket?</h2> | ||
| 40 | |||
| 41 | <p> | ||
| 42 | LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library | ||
| 43 | that is composed by two parts: a C core that provides support for the TCP | ||
| 44 | and UDP transport layers, and a set of Lua modules that add support for | ||
| 45 | functionality commonly needed by applications that deal with the Internet. | ||
| 46 | </p> | ||
| 47 | |||
| 48 | <p> | ||
| 49 | The core support has been implemented so that it is both efficient and | ||
| 50 | simple to use. It is available to any Lua application once it has been | ||
| 51 | properly initialized by the interpreter in use. The code has been tested | ||
| 52 | and runs well on several Windows and UNIX platforms. </p> | ||
| 53 | |||
| 54 | <p> | ||
| 55 | Among the support modules, the most commonly used implement the | ||
| 56 | <a href="smtp.html">SMTP</a> | ||
| 57 | (sending e-mails), | ||
| 58 | <a href="http.html">HTTP</a> | ||
| 59 | (WWW access) and | ||
| 60 | <a href="ftp.html">FTP</a> | ||
| 61 | (uploading and downloading files) client | ||
| 62 | protocols. These provide a very natural and generic interface to the | ||
| 63 | functionality defined by each protocol. | ||
| 64 | In addition, you will find that the | ||
| 65 | <a href="mime.html">MIME</a> (common encodings), | ||
| 66 | <a href="url.html">URL</a> | ||
| 67 | (anything you could possible want to do with one) and | ||
| 68 | <a href="ltn12.html">LTN12</a> | ||
| 69 | (filters, sinks, sources and pumps) modules can be very handy. | ||
| 70 | </p> | ||
| 71 | |||
| 72 | <p> | ||
| 73 | The library is available under the same | ||
| 74 | <a href="http://www.lua.org/copyright.html"> | ||
| 75 | terms and conditions</a> as the Lua language, the MIT license. The idea is | ||
| 76 | that if you can use Lua in a project, you should also be able to use | ||
| 77 | LuaSocket. | ||
| 78 | </p> | ||
| 79 | |||
| 80 | <p> | ||
| 81 | Copyright © 1999-2013 Diego Nehab. All rights reserved. <br> | ||
| 82 | Author: <a href="http://www.impa.br/~diego">Diego Nehab</a> | ||
| 83 | </p> | ||
| 84 | |||
| 85 | <!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 86 | |||
| 87 | <h2 id="download">Download</h2> | ||
| 88 | |||
| 89 | <p> | ||
| 90 | LuaSocket version 3.0-rc1 is now available for download! | ||
| 91 | It is compatible with Lua 5.1 and 5.2, and has | ||
| 92 | been tested on Windows XP, Linux, and Mac OS X. Chances | ||
| 93 | are it works well on most UNIX distributions and Windows flavors. | ||
| 94 | </p> | ||
| 95 | |||
| 96 | <p> | ||
| 97 | The current version of the library can be found at | ||
| 98 | the <a href="https://github.com/diegonehab/luasocket">LuaSocket | ||
| 99 | project page</a> on GitHub. Besides the full C and Lua source code | ||
| 100 | for the library, the distribution contains several examples, | ||
| 101 | this user's manual and basic test procedures. | ||
| 102 | </p> | ||
| 103 | |||
| 104 | <p> Take a look at the <a | ||
| 105 | href="installation.html">installation</a> section of the | ||
| 106 | manual to find out how to properly install the library. | ||
| 107 | </p> | ||
| 108 | |||
| 109 | <!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 110 | |||
| 111 | <h2 id="thanks">Special thanks</h2> | ||
| 112 | |||
| 113 | <p> | ||
| 114 | This marks the first release of LuaSocket that | ||
| 115 | wholeheartedly embraces the open-source development | ||
| 116 | philosophy. After a long hiatus, Matthew Wild finally | ||
| 117 | convinced me it was time for a release including IPv6 and | ||
| 118 | Lua 5.2 support. It was more work than we anticipated. | ||
| 119 | Special thanks to Sam Roberts, Florian Zeitz, and Paul | ||
| 120 | Aurich, Liam Devine, Alexey Melnichuk, and everybody else | ||
| 121 | that has helped bring this library back to life. | ||
| 122 | </p> | ||
| 123 | |||
| 124 | <!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 125 | |||
| 126 | <h2 id="new">What's New</h2> | ||
| 127 | |||
| 128 | <p> | ||
| 129 | Main changes for LuaSocket 3.0-rc1 are IPv6 support | ||
| 130 | and Lua 5.2 compatibility. | ||
| 131 | </p> | ||
| 132 | |||
| 133 | <ul> | ||
| 134 | <li> Added: Compatible with Lua 5.2</li> | ||
| 135 | <ul> | ||
| 136 | <li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>, | ||
| 137 | package tables will <em>not</em> be exported as globals!</li> | ||
| 138 | </ul> | ||
| 139 | <li> Added: IPv6 support;</li> | ||
| 140 | <ul> | ||
| 141 | <li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses;</li> | ||
| 142 | <li> <tt>Getpeername</tt> and <tt>getsockname</tt> support | ||
| 143 | IPv6 addresses, and return the socket family as a third value;</li> | ||
| 144 | <li> URL module updated to support IPv6 host names;</li> | ||
| 145 | <li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions;</li> | ||
| 146 | <li> New <tt>socket.dns.getaddrinfo</tt> and | ||
| 147 | <tt>socket.dns.getnameinfo</tt> functions;</li> | ||
| 148 | </ul> | ||
| 149 | <li> Added: <tt>getoption</tt> method;</li> | ||
| 150 | <li> Fixed: <tt>url.unescape</tt> was returning additional values;</li> | ||
| 151 | <li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>, | ||
| 152 | <tt>mime.b64</tt>, and <tt>mime.unb64</tt> could | ||
| 153 | mistaking their own stack slots for functions arguments;</li> | ||
| 154 | <li> Fixed: Receiving zero-length datagram is now possible;</li> | ||
| 155 | <li> Improved: Hidden all internal library symbols;</li> | ||
| 156 | <li> Improved: Better error messages;</li> | ||
| 157 | <li> Improved: Better documentation of socket options.</li> | ||
| 158 | <li> Fixed: manual sample of HTTP authentication now uses correct | ||
| 159 | "authorization" header (Alexandre Ittner);</li> | ||
| 160 | <li> Fixed: failure on bind() was destroying the socket (Sam Roberts);</li> | ||
| 161 | <li> Fixed: receive() returns immediatelly if prefix can satisfy | ||
| 162 | bytes requested (M Joonas Pihlaja);</li> | ||
| 163 | <li> Fixed: multicast didn't work on Windows, or anywhere | ||
| 164 | else for that matter (Herbert Leuwer, Adrian Sietsma);</li> | ||
| 165 | <li> Fixed: select() now reports an error when called with more | ||
| 166 | sockets than FD_SETSIZE (Lorenzo Leonini);</li> | ||
| 167 | <li> Fixed: manual links to home.html changed to index.html | ||
| 168 | (Robert Hahn);</li> | ||
| 169 | <li> Fixed: mime.unb64() would return an empty string on results that started | ||
| 170 | with a null character (Robert Raschke);</li> | ||
| 171 | <li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray);</li> | ||
| 172 | <li> Fixed: calling sleep() with negative numbers could | ||
| 173 | block forever, wasting CPU. Now it returns immediately (MPB);</li> | ||
| 174 | <li> Improved: FTP commands are now sent in upper case to | ||
| 175 | help buggy servers (Anders Eurenius);</li> | ||
| 176 | <li> Improved: known headers now sent in canonic | ||
| 177 | capitalization to help buggy servers (Joseph Stewart);</li> | ||
| 178 | <li> Improved: Clarified tcp:receive() in the manual (MPB);</li> | ||
| 179 | <li> Improved: Decent makefiles (LHF).</li> | ||
| 180 | <li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei).</li> | ||
| 181 | </ul> | ||
| 182 | |||
| 183 | <!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 184 | |||
| 185 | <h2 id="old">Old Versions</h2> | ||
| 186 | |||
| 187 | <p> | ||
| 188 | All previous versions of the LuaSocket library can be downloaded <a | ||
| 189 | href="http://www.impa.br/~diego/software/luasocket/old"> | ||
| 190 | here</a>. Although these versions are no longer supported, they are | ||
| 191 | still available for those that have compatibility issues. | ||
| 192 | </p> | ||
| 193 | |||
| 194 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 195 | |||
| 196 | <div class="footer"> | ||
| 197 | <hr> | ||
| 198 | <center> | ||
| 199 | <p class="bar"> | ||
| 200 | <a href="index.html#download">download</a> · | ||
| 201 | <a href="installation.html">installation</a> · | ||
| 202 | <a href="introduction.html">introduction</a> · | ||
| 203 | <a href="reference.html">reference</a> | ||
| 204 | </p> | ||
| 205 | <p> | ||
| 206 | <small> | ||
| 207 | Last modified by Diego Nehab on <br> | ||
| 208 | Tue Jun 11 18:50:23 HKT 2013 | ||
| 209 | </small> | ||
| 210 | </p> | ||
| 211 | </center> | ||
| 212 | </div> | ||
| 213 | |||
| 214 | </body> | ||
| 215 | </html> | ||
diff --git a/docs/installation.html b/docs/installation.html new file mode 100644 index 0000000..28a9fbb --- /dev/null +++ b/docs/installation.html | |||
| @@ -0,0 +1,127 @@ | |||
| 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: Introduction to the core"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network, Support, | ||
| 8 | Installation"> | ||
| 9 | <title>LuaSocket: Installation</title> | ||
| 10 | <link rel="stylesheet" href="reference.css" type="text/css"> | ||
| 11 | </head> | ||
| 12 | |||
| 13 | <body> | ||
| 14 | |||
| 15 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 16 | |||
| 17 | <div class=header> | ||
| 18 | <hr> | ||
| 19 | <center> | ||
| 20 | <table summary="LuaSocket logo"> | ||
| 21 | <tr><td align=center><a href="http://www.lua.org"> | ||
| 22 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | ||
| 23 | </a></td></tr> | ||
| 24 | <tr><td align=center valign=top>Network support for the Lua language | ||
| 25 | </td></tr> | ||
| 26 | </table> | ||
| 27 | <p class=bar> | ||
| 28 | <a href="index.html">home</a> · | ||
| 29 | <a href="index.html#download">download</a> · | ||
| 30 | <a href="installation.html">installation</a> · | ||
| 31 | <a href="introduction.html">introduction</a> · | ||
| 32 | <a href="reference.html">reference</a> | ||
| 33 | </p> | ||
| 34 | </center> | ||
| 35 | <hr> | ||
| 36 | </div> | ||
| 37 | |||
| 38 | <!-- installation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 39 | |||
| 40 | <h2>Installation</h2> | ||
| 41 | |||
| 42 | <p> Here we describe the standard distribution. If the | ||
| 43 | standard doesn't meet your needs, we refer you to the Lua | ||
| 44 | discussion list, where any question about the package scheme | ||
| 45 | will likely already have been answered. </p> | ||
| 46 | |||
| 47 | <h3>Directory structure</h3> | ||
| 48 | |||
| 49 | <p> On Unix systems, the standard distribution uses two base | ||
| 50 | directories, one for system dependent files, and another for system | ||
| 51 | independent files. Let's call these directories <tt><CDIR></tt> | ||
| 52 | and <tt><LDIR></tt>, respectively. | ||
| 53 | For example, in my laptp, Lua 5.1 is configured to | ||
| 54 | use '<tt>/usr/local/lib/lua/5.1</tt>' for | ||
| 55 | <tt><CDIR></tt> and '<tt>/usr/local/share/lua/5.1</tt>' for | ||
| 56 | <tt><LDIR></tt>. On Windows, <tt><CDIR></tt> | ||
| 57 | usually points to the directory where the Lua executable is | ||
| 58 | found, and <tt><LDIR></tt> points to a | ||
| 59 | <tt>lua/</tt> directory inside <tt><CDIR></tt>. (These | ||
| 60 | settings can be overridden by environment variables | ||
| 61 | <tt>LUA_PATH</tt> and <tt>LUA_CPATH</tt>. See the Lua | ||
| 62 | documentation for details.) Here is the standard LuaSocket | ||
| 63 | distribution directory structure:</p> | ||
| 64 | |||
| 65 | <pre class=example> | ||
| 66 | <LDIR>/ltn12.lua | ||
| 67 | <LDIR>/socket.lua | ||
| 68 | <CDIR>/socket/core.dll | ||
| 69 | <LDIR>/socket/http.lua | ||
| 70 | <LDIR>/socket/tp.lua | ||
| 71 | <LDIR>/socket/ftp.lua | ||
| 72 | <LDIR>/socket/smtp.lua | ||
| 73 | <LDIR>/socket/url.lua | ||
| 74 | <LDIR>/mime.lua | ||
| 75 | <CDIR>/mime/core.dll | ||
| 76 | </pre> | ||
| 77 | |||
| 78 | <p> Naturally, on Unix systems, <tt>core.dll</tt> | ||
| 79 | would be replaced by <tt>core.so</tt>. | ||
| 80 | </p> | ||
| 81 | |||
| 82 | <h3>Using LuaSocket</h3> | ||
| 83 | |||
| 84 | <p> With the above setup, and an interpreter with shared library support, | ||
| 85 | it should be easy to use LuaSocket. Just fire the interpreter and use the | ||
| 86 | <tt>require</tt> function to gain access to whatever module you need:</p> | ||
| 87 | |||
| 88 | <pre class=example> | ||
| 89 | Lua 5.2.2 Copyright (C) 1994-2013 Lua.org, PUC-Rio | ||
| 90 | > socket = require("socket") | ||
| 91 | > print(socket._VERSION) | ||
| 92 | --> LuaSocket 3.0-rc1 | ||
| 93 | </pre> | ||
| 94 | |||
| 95 | <p> Each module loads their dependencies automatically, so you only need to | ||
| 96 | load the modules you directly depend upon: </p> | ||
| 97 | |||
| 98 | <pre class=example> | ||
| 99 | Lua 5.2.2 Copyright (C) 1994-2013 Lua.org, PUC-Rio | ||
| 100 | > http = require("socket.http") | ||
| 101 | > print(http.request("http://www.impa.br/~diego/software/luasocket")) | ||
| 102 | --> homepage gets dumped to terminal | ||
| 103 | </pre> | ||
| 104 | |||
| 105 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 106 | |||
| 107 | <div class=footer> | ||
| 108 | <hr> | ||
| 109 | <center> | ||
| 110 | <p class=bar> | ||
| 111 | <a href="index.html">home</a> · | ||
| 112 | <a href="index.html#down">download</a> · | ||
| 113 | <a href="installation.html">installation</a> · | ||
| 114 | <a href="introduction.html">introduction</a> · | ||
| 115 | <a href="reference.html">reference</a> | ||
| 116 | </p> | ||
| 117 | <p> | ||
| 118 | <small> | ||
| 119 | Last modified by Diego Nehab on <br> | ||
| 120 | Tue Jun 11 19:06:14 HKT 2013 | ||
| 121 | </small> | ||
| 122 | </p> | ||
| 123 | </center> | ||
| 124 | </div> | ||
| 125 | |||
| 126 | </body> | ||
| 127 | </html> | ||
diff --git a/docs/introduction.html b/docs/introduction.html new file mode 100644 index 0000000..fd22f48 --- /dev/null +++ b/docs/introduction.html | |||
| @@ -0,0 +1,333 @@ | |||
| 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: Introduction to the core"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network, | ||
| 8 | Library, Support"> | ||
| 9 | <title>LuaSocket: Introduction to the core</title> | ||
| 10 | <link rel="stylesheet" href="reference.css" type="text/css"> | ||
| 11 | </head> | ||
| 12 | |||
| 13 | <body> | ||
| 14 | |||
| 15 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 16 | |||
| 17 | <div class=header> | ||
| 18 | <hr> | ||
| 19 | <center> | ||
| 20 | <table summary="LuaSocket logo"> | ||
| 21 | <tr><td align=center><a href="http://www.lua.org"> | ||
| 22 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | ||
| 23 | </a></td></tr> | ||
| 24 | <tr><td align=center valign=top>Network support for the Lua language | ||
| 25 | </td></tr> | ||
| 26 | </table> | ||
| 27 | <p class=bar> | ||
| 28 | <a href="index.html">home</a> · | ||
| 29 | <a href="index.html#download">download</a> · | ||
| 30 | <a href="installation.html">installation</a> · | ||
| 31 | <a href="introduction.html">introduction</a> · | ||
| 32 | <a href="reference.html">reference</a> | ||
| 33 | </p> | ||
| 34 | </center> | ||
| 35 | <hr> | ||
| 36 | </div> | ||
| 37 | |||
| 38 | <!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 39 | |||
| 40 | <h2>Introduction</h2> | ||
| 41 | |||
| 42 | <p> | ||
| 43 | LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library | ||
| 44 | that is composed by two parts: a C core that provides support for the TCP | ||
| 45 | and UDP transport layers, and a set of Lua modules that add support for | ||
| 46 | the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and | ||
| 47 | downloading files) protocols and other functionality commonly needed by | ||
| 48 | applications that deal with the Internet. This introduction is about the C | ||
| 49 | core. | ||
| 50 | </p> | ||
| 51 | |||
| 52 | <p> | ||
| 53 | Communication in LuaSocket is performed via I/O objects. These can | ||
| 54 | represent different network domains. Currently, support is provided for TCP | ||
| 55 | and UDP, but nothing prevents other developers from implementing SSL, Local | ||
| 56 | Domain, Pipes, File Descriptors etc. I/O objects provide a standard | ||
| 57 | interface to I/O across different domains and operating systems. | ||
| 58 | </p> | ||
| 59 | |||
| 60 | <p> | ||
| 61 | The API design had two goals in mind. First, users | ||
| 62 | experienced with the C API to sockets should feel comfortable using LuaSocket. | ||
| 63 | Second, the simplicity and the feel of the Lua language should be | ||
| 64 | preserved. To achieve these goals, the LuaSocket API keeps the function names and semantics the C API whenever possible, but their usage in Lua has been greatly simplified. | ||
| 65 | </p> | ||
| 66 | |||
| 67 | |||
| 68 | <p> | ||
| 69 | One of the simplifications is the receive pattern capability. | ||
| 70 | Applications can read data from stream domains (such as TCP) | ||
| 71 | line by line, block by block, or until the connection is closed. | ||
| 72 | All I/O reads are buffered and the performance differences between | ||
| 73 | different receive patterns are negligible. | ||
| 74 | </p> | ||
| 75 | |||
| 76 | <p> | ||
| 77 | Another advantage is the flexible timeout control | ||
| 78 | mechanism. As in C, all I/O operations are blocking by default. For | ||
| 79 | example, the <a href=tcp.html#send><tt>send</tt></a>, | ||
| 80 | <a href=tcp.html#receive><tt>receive</tt></a> and | ||
| 81 | <a href=tcp.html#accept><tt>accept</tt></a> methods | ||
| 82 | of the TCP domain will block the caller application until | ||
| 83 | the operation is completed (if ever!). However, with a call to the | ||
| 84 | <a href=tcp.html#settimeout><tt>settimeout</tt></a> | ||
| 85 | method, an application can specify upper limits on | ||
| 86 | the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on | ||
| 87 | the time LuaSocket can internally be blocked by any OS call (the | ||
| 88 | "<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket | ||
| 89 | call might perform several OS calls, so that the two timeout values are | ||
| 90 | <em>not</em> equivalent. | ||
| 91 | </p> | ||
| 92 | |||
| 93 | <p> | ||
| 94 | Finally, the host name resolution is transparent, meaning that most | ||
| 95 | functions and methods accept both IP addresses and host names. In case a | ||
| 96 | host name is given, the library queries the system's resolver and | ||
| 97 | tries the main IP address returned. Note that direct use of IP addresses | ||
| 98 | is more efficient, of course. The | ||
| 99 | <a href=dns.html#toip><tt>toip</tt></a> | ||
| 100 | and <a href=dns.html#tohostname><tt>tohostname</tt></a> | ||
| 101 | functions from the DNS module are provided to convert between host names and IP addresses. | ||
| 102 | </p> | ||
| 103 | |||
| 104 | <p> | ||
| 105 | Together, these changes make network programming in LuaSocket much simpler | ||
| 106 | than it is in C, as the following sections will show. | ||
| 107 | </p> | ||
| 108 | |||
| 109 | <!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 110 | |||
| 111 | <h3 id=tcp>TCP</h3> | ||
| 112 | |||
| 113 | <p> | ||
| 114 | TCP (Transfer Control Protocol) is reliable stream protocol. In other | ||
| 115 | words, applications communicating through TCP can send and receive data as | ||
| 116 | an error free stream of bytes. Data is split in one end and | ||
| 117 | reassembled transparently on the other end. There are no boundaries in | ||
| 118 | the data transfers. The library allows users to read data from the | ||
| 119 | sockets in several different granularities: patterns are available for | ||
| 120 | lines, arbitrary sized blocks or "read up to connection closed", all with | ||
| 121 | good performance. | ||
| 122 | </p> | ||
| 123 | |||
| 124 | <p> | ||
| 125 | The library distinguishes three types of TCP sockets: <em>master</em>, | ||
| 126 | <em>client</em> and <em>server</em> sockets. | ||
| 127 | </p> | ||
| 128 | |||
| 129 | <p> | ||
| 130 | Master sockets are newly created TCP sockets returned by the function | ||
| 131 | <a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is | ||
| 132 | transformed into a server socket | ||
| 133 | after it is associated with a <em>local</em> address by a call to the | ||
| 134 | <a href=tcp.html#bind><tt>bind</tt></a> method followed by a call to the | ||
| 135 | <a href=tcp.html#listen><tt>listen</tt></a>. Conversely, a master socket | ||
| 136 | can be changed into a client socket with the method | ||
| 137 | <a href=tcp.html#connect><tt>connect</tt></a>, | ||
| 138 | which associates it with a <em>remote</em> address. | ||
| 139 | </p> | ||
| 140 | |||
| 141 | <p> | ||
| 142 | On server sockets, applications can use the | ||
| 143 | <a href=tcp.html#accept><tt>accept</tt></a> method | ||
| 144 | to wait for a client connection. Once a connection is established, a | ||
| 145 | client socket object is returned representing this connection. The | ||
| 146 | other methods available for server socket objects are | ||
| 147 | <a href=tcp.html#getsockname><tt>getsockname</tt></a>, | ||
| 148 | <a href=tcp.html#setoption><tt>setoption</tt></a>, | ||
| 149 | <a href=tcp.html#settimeout><tt>settimeout</tt></a>, and | ||
| 150 | <a href=tcp.html#close><tt>close</tt></a>. | ||
| 151 | </p> | ||
| 152 | |||
| 153 | <p> | ||
| 154 | Client sockets are used to exchange data between two applications over | ||
| 155 | the Internet. Applications can call the methods | ||
| 156 | <a href=tcp.html#send><tt>send</tt></a> and | ||
| 157 | <a href=tcp.html#receive><tt>receive</tt></a> | ||
| 158 | to send and receive data. The other methods | ||
| 159 | available for client socket objects are | ||
| 160 | <a href=tcp.html#getsockname><tt>getsockname</tt></a>, | ||
| 161 | <a href=tcp.html#getpeername><tt>getpeername</tt></a>, | ||
| 162 | <a href=tcp.html#setoption><tt>setoption</tt></a>, | ||
| 163 | <a href=tcp.html#settimeout><tt>settimeout</tt></a>, | ||
| 164 | <a href=tcp.html#shutdown><tt>shutdown</tt></a>, and | ||
| 165 | <a href=tcp.html#close><tt>close</tt></a>. | ||
| 166 | </p> | ||
| 167 | |||
| 168 | <p> | ||
| 169 | Example: | ||
| 170 | </p> | ||
| 171 | <blockquote> | ||
| 172 | <p> | ||
| 173 | A simple echo server, using LuaSocket. The program binds to an ephemeral | ||
| 174 | port (one that is chosen by the operating system) on the local host and | ||
| 175 | awaits client connections on that port. When a connection is established, | ||
| 176 | the program reads a line from the remote end and sends it back, closing | ||
| 177 | the connection immediately. You can test it using the telnet | ||
| 178 | program. | ||
| 179 | </p> | ||
| 180 | |||
| 181 | <pre class=example> | ||
| 182 | -- load namespace | ||
| 183 | local socket = require("socket") | ||
| 184 | -- create a TCP socket and bind it to the local host, at any port | ||
| 185 | local server = assert(socket.bind("*", 0)) | ||
| 186 | -- find out which port the OS chose for us | ||
| 187 | local ip, port = server:getsockname() | ||
| 188 | -- print a message informing what's up | ||
| 189 | print("Please telnet to localhost on port " .. port) | ||
| 190 | print("After connecting, you have 10s to enter a line to be echoed") | ||
| 191 | -- loop forever waiting for clients | ||
| 192 | while 1 do | ||
| 193 | -- wait for a connection from any client | ||
| 194 | local client = server:accept() | ||
| 195 | -- make sure we don't block waiting for this client's line | ||
| 196 | client:settimeout(10) | ||
| 197 | -- receive the line | ||
| 198 | local line, err = client:receive() | ||
| 199 | -- if there was no error, send it back to the client | ||
| 200 | if not err then client:send(line .. "\n") end | ||
| 201 | -- done with client, close the object | ||
| 202 | client:close() | ||
| 203 | end | ||
| 204 | </pre> | ||
| 205 | </blockquote> | ||
| 206 | |||
| 207 | <!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 208 | |||
| 209 | <h3 id=udp>UDP</h3> | ||
| 210 | |||
| 211 | <p> | ||
| 212 | UDP (User Datagram Protocol) is a non-reliable datagram protocol. In | ||
| 213 | other words, applications communicating through UDP send and receive | ||
| 214 | data as independent blocks, which are not guaranteed to reach the other | ||
| 215 | end. Even when they do reach the other end, they are not guaranteed to be | ||
| 216 | error free. Data transfers are atomic, one datagram at a time. Reading | ||
| 217 | only part of a datagram discards the rest, so that the following read | ||
| 218 | operation will act on the next datagram. The advantages are in | ||
| 219 | simplicity (no connection setup) and performance (no error checking or | ||
| 220 | error correction). | ||
| 221 | </p> | ||
| 222 | |||
| 223 | <p> | ||
| 224 | Note that although no guarantees are made, these days | ||
| 225 | networks are so good that, under normal circumstances, few errors | ||
| 226 | happen in practice. | ||
| 227 | </p> | ||
| 228 | |||
| 229 | <p> | ||
| 230 | An UDP socket object is created by the | ||
| 231 | <a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP | ||
| 232 | sockets do not need to be connected before use. The method | ||
| 233 | <a href=udp.html#sendto><tt>sendto</tt></a> | ||
| 234 | can be used immediately after creation to | ||
| 235 | send a datagram to IP address and port. Host names are not allowed | ||
| 236 | because performing name resolution for each packet would be forbiddingly | ||
| 237 | slow. Methods | ||
| 238 | <a href=udp.html#receive><tt>receive</tt></a> and | ||
| 239 | <a href=udp.html#receivefrom><tt>receivefrom</tt></a> | ||
| 240 | can be used to retrieve datagrams, the latter returning the IP and port of | ||
| 241 | the sender as extra return values (thus being slightly less | ||
| 242 | efficient). | ||
| 243 | </p> | ||
| 244 | |||
| 245 | <p> | ||
| 246 | When communication is performed repeatedly with a single peer, an | ||
| 247 | application should call the | ||
| 248 | <a href=udp.html#setpeername><tt>setpeername</tt></a> method to specify a | ||
| 249 | permanent partner. Methods | ||
| 250 | <a href=udp.html#sendto><tt>sendto</tt></a> and | ||
| 251 | <a href=udp.html#receivefrom><tt>receivefrom</tt></a> | ||
| 252 | can no longer be used, but the method | ||
| 253 | <a href=udp.html#send><tt>send</tt></a> can be used to send data | ||
| 254 | directly to the peer, and the method | ||
| 255 | <a href=udp.html#receive><tt>receive</tt></a> | ||
| 256 | will only return datagrams originating | ||
| 257 | from that peer. There is about 30% performance gain due to this practice. | ||
| 258 | </p> | ||
| 259 | |||
| 260 | <p> | ||
| 261 | To associate an UDP socket with a local address, an application calls the | ||
| 262 | <a href=udp.html#setsockname><tt>setsockname</tt></a> | ||
| 263 | method <em>before</em> sending any datagrams. Otherwise, the socket is | ||
| 264 | automatically bound to an ephemeral address before the first data | ||
| 265 | transmission and once bound the local address cannot be changed. | ||
| 266 | The other methods available for UDP sockets are | ||
| 267 | <a href=udp.html#getpeername><tt>getpeername</tt></a>, | ||
| 268 | <a href=udp.html#getsockname><tt>getsockname</tt></a>, | ||
| 269 | <a href=udp.html#settimeout><tt>settimeout</tt></a>, | ||
| 270 | <a href=udp.html#setoption><tt>setoption</tt></a> and | ||
| 271 | <a href=udp.html#close><tt>close</tt></a>. | ||
| 272 | </p> | ||
| 273 | |||
| 274 | <p> | ||
| 275 | Example: | ||
| 276 | </p> | ||
| 277 | <blockquote> | ||
| 278 | <p> | ||
| 279 | A simple daytime client, using LuaSocket. The program connects to a remote | ||
| 280 | server and tries to retrieve the daytime, printing the answer it got or an | ||
| 281 | error message. | ||
| 282 | </p> | ||
| 283 | |||
| 284 | <pre class=example> | ||
| 285 | -- change here to the host an port you want to contact | ||
| 286 | local host, port = "localhost", 13 | ||
| 287 | -- load namespace | ||
| 288 | local socket = require("socket") | ||
| 289 | -- convert host name to ip address | ||
| 290 | local ip = assert(socket.dns.toip(host)) | ||
| 291 | -- create a new UDP object | ||
| 292 | local udp = assert(socket.udp()) | ||
| 293 | -- contact daytime host | ||
| 294 | assert(udp:sendto("anything", ip, port)) | ||
| 295 | -- retrieve the answer and print results | ||
| 296 | io.write(assert(udp:receive())) | ||
| 297 | </pre> | ||
| 298 | </blockquote> | ||
| 299 | |||
| 300 | <!-- More +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 301 | |||
| 302 | <h3 id=more>Support modules</h3> | ||
| 303 | |||
| 304 | <p> Although not covered in the introduction, LuaSocket offers | ||
| 305 | much more than TCP and UDP functionality. As the library | ||
| 306 | evolved, support for <a href=http.html>HTTP</a>, <a href=ftp.html>FTP</a>, | ||
| 307 | and <a href=smtp.html>SMTP</a> were built on top of these. These modules | ||
| 308 | and many others are covered by the <a href=reference.html>reference manual</a>. | ||
| 309 | </p> | ||
| 310 | |||
| 311 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 312 | |||
| 313 | <div class=footer> | ||
| 314 | <hr> | ||
| 315 | <center> | ||
| 316 | <p class=bar> | ||
| 317 | <a href="index.html">home</a> · | ||
| 318 | <a href="index.html#down">download</a> · | ||
| 319 | <a href="installation.html">installation</a> · | ||
| 320 | <a href="introduction.html">introduction</a> · | ||
| 321 | <a href="reference.html">reference</a> | ||
| 322 | </p> | ||
| 323 | <p> | ||
| 324 | <small> | ||
| 325 | Last modified by Diego Nehab on <br> | ||
| 326 | Thu Apr 20 00:25:36 EDT 2006 | ||
| 327 | </small> | ||
| 328 | </p> | ||
| 329 | </center> | ||
| 330 | </div> | ||
| 331 | |||
| 332 | </body> | ||
| 333 | </html> | ||
diff --git a/docs/ltn12.html b/docs/ltn12.html new file mode 100644 index 0000000..fe3e3a0 --- /dev/null +++ b/docs/ltn12.html | |||
| @@ -0,0 +1,440 @@ | |||
| 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: LTN12 support"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, Filters, Source, Sink, | ||
| 8 | Pump, Support, Library"> | ||
| 9 | <title>LuaSocket: LTN12 module</title> | ||
| 10 | <link rel="stylesheet" href="reference.css" type="text/css"> | ||
| 11 | </head> | ||
| 12 | |||
| 13 | <body> | ||
| 14 | |||
| 15 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 16 | |||
| 17 | <div class="header"> | ||
| 18 | <hr> | ||
| 19 | <center> | ||
| 20 | <table summary="LuaSocket logo"> | ||
| 21 | <tr><td align="center"><a href="http://www.lua.org"> | ||
| 22 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> | ||
| 23 | </a></td></tr> | ||
| 24 | <tr><td align="center" valign="top">Network support for the Lua language | ||
| 25 | </td></tr> | ||
| 26 | </table> | ||
| 27 | <p class="bar"> | ||
| 28 | <a href="index.html">home</a> · | ||
| 29 | <a href="index.html#download">download</a> · | ||
| 30 | <a href="installation.html">installation</a> · | ||
| 31 | <a href="introduction.html">introduction</a> · | ||
| 32 | <a href="reference.html">reference</a> | ||
| 33 | </p> | ||
| 34 | </center> | ||
| 35 | <hr> | ||
| 36 | </div> | ||
| 37 | |||
| 38 | <!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 39 | |||
| 40 | <h2 id="ltn12">LTN12</h2> | ||
| 41 | |||
| 42 | <p> The <tt>ltn12</tt> namespace implements the ideas described in | ||
| 43 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> | ||
| 44 | LTN012, Filters sources and sinks</a>. This manual simply describes the | ||
| 45 | functions. Please refer to the LTN for a deeper explanation of the | ||
| 46 | functionality provided by this module. | ||
| 47 | </p> | ||
| 48 | |||
| 49 | <p> | ||
| 50 | To obtain the <tt>ltn12</tt> namespace, run: | ||
| 51 | </p> | ||
| 52 | |||
| 53 | <pre class="example"> | ||
| 54 | -- loads the LTN21 module | ||
| 55 | local ltn12 = require("ltn12") | ||
| 56 | </pre> | ||
| 57 | |||
| 58 | <!-- filters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 59 | |||
| 60 | <h3 id="filter">Filters</h3> | ||
| 61 | |||
| 62 | <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 63 | |||
| 64 | <p class="name" id="filter.chain"> | ||
| 65 | ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub> | ||
| 66 | [, ... filter<sub>N</sub>]<b>)</b> | ||
| 67 | </p> | ||
| 68 | |||
| 69 | <p class="description"> | ||
| 70 | Returns a filter that passes all data it receives through each of a | ||
| 71 | series of given filters. | ||
| 72 | </p> | ||
| 73 | |||
| 74 | <p class="parameters"> | ||
| 75 | <tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple | ||
| 76 | filters. | ||
| 77 | </p> | ||
| 78 | |||
| 79 | <p class="return"> | ||
| 80 | The function returns the chained filter. | ||
| 81 | </p> | ||
| 82 | |||
| 83 | <p class="note"> | ||
| 84 | The nesting of filters can be arbitrary. For instance, the useless filter | ||
| 85 | below doesn't do anything but return the data that was passed to it, | ||
| 86 | unaltered. | ||
| 87 | </p> | ||
| 88 | |||
| 89 | <pre class="example"> | ||
| 90 | -- load required modules | ||
| 91 | local ltn12 = require("ltn12") | ||
| 92 | local mime = require("mime") | ||
| 93 | |||
| 94 | -- create a silly identity filter | ||
| 95 | id = ltn12.filter.chain( | ||
| 96 | mime.encode("quoted-printable"), | ||
| 97 | mime.encode("base64"), | ||
| 98 | mime.decode("base64"), | ||
| 99 | mime.decode("quoted-printable") | ||
| 100 | ) | ||
| 101 | </pre> | ||
| 102 | |||
| 103 | <!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 104 | |||
| 105 | <p class="name" id="filter.cycle"> | ||
| 106 | ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b> | ||
| 107 | </p> | ||
| 108 | |||
| 109 | <p class="description"> | ||
| 110 | Returns a high-level filter that cycles though a low-level filter by | ||
| 111 | passing it each chunk and updating a context between calls. | ||
| 112 | </p> | ||
| 113 | |||
| 114 | <p class="parameters"> | ||
| 115 | <tt>Low</tt> is the low-level filter to be cycled, | ||
| 116 | <tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra | ||
| 117 | argument the low-level filter might take. | ||
| 118 | </p> | ||
| 119 | |||
| 120 | <p class="return"> | ||
| 121 | The function returns the high-level filter. | ||
| 122 | </p> | ||
| 123 | |||
| 124 | <pre class="example"> | ||
| 125 | -- load the ltn12 module | ||
| 126 | local ltn12 = require("ltn12") | ||
| 127 | |||
| 128 | -- the base64 mime filter factory | ||
| 129 | encodet['base64'] = function() | ||
| 130 | return ltn12.filter.cycle(b64, "") | ||
| 131 | end | ||
| 132 | </pre> | ||
| 133 | |||
| 134 | <!-- pumps ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 135 | |||
| 136 | <h3 id="pump">Pumps</h3> | ||
| 137 | |||
| 138 | <!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 139 | |||
| 140 | <p class="name" id="pump.all"> | ||
| 141 | ltn12.pump.<b>all(</b>source, sink<b>)</b> | ||
| 142 | </p> | ||
| 143 | |||
| 144 | <p class="description"> | ||
| 145 | Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>. | ||
| 146 | </p> | ||
| 147 | |||
| 148 | <p class="return"> | ||
| 149 | If successful, the function returns a value that evaluates to | ||
| 150 | <b><tt>true</tt></b>. In case | ||
| 151 | of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. | ||
| 152 | </p> | ||
| 153 | |||
| 154 | <!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 155 | |||
| 156 | <p class="name" id="pump.step"> | ||
| 157 | ltn12.pump.<b>step(</b>source, sink<b>)</b> | ||
| 158 | </p> | ||
| 159 | |||
| 160 | <p class="description"> | ||
| 161 | Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>. | ||
| 162 | </p> | ||
| 163 | |||
| 164 | <p class="return"> | ||
| 165 | If successful, the function returns a value that evaluates to | ||
| 166 | <b><tt>true</tt></b>. In case | ||
| 167 | of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. | ||
| 168 | </p> | ||
| 169 | |||
| 170 | <!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 171 | |||
| 172 | <h3 id="sink">Sinks</h3> | ||
| 173 | |||
| 174 | <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 175 | |||
| 176 | <p class="name" id="sink.chain"> | ||
| 177 | ltn12.sink.<b>chain(</b>filter, sink<b>)</b> | ||
| 178 | </p> | ||
| 179 | |||
| 180 | <p class="description"> | ||
| 181 | Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>. | ||
| 182 | </p> | ||
| 183 | |||
| 184 | <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 185 | |||
| 186 | <p class="name" id="sink.error"> | ||
| 187 | ltn12.sink.<b>error(</b>message<b>)</b> | ||
| 188 | </p> | ||
| 189 | |||
| 190 | <p class="description"> | ||
| 191 | Creates and returns a sink that aborts transmission with the error | ||
| 192 | <tt>message</tt>. | ||
| 193 | </p> | ||
| 194 | |||
| 195 | <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 196 | |||
| 197 | <p class="name" id="sink.file"> | ||
| 198 | ltn12.sink.<b>file(</b>handle, message<b>)</b> | ||
| 199 | </p> | ||
| 200 | |||
| 201 | <p class="description"> | ||
| 202 | Creates a sink that sends data to a file. | ||
| 203 | </p> | ||
| 204 | |||
| 205 | <p class="parameters"> | ||
| 206 | <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, | ||
| 207 | <tt>message</tt> should give the reason for failure. | ||
| 208 | </p> | ||
| 209 | |||
| 210 | <p class="return"> | ||
| 211 | The function returns a sink that sends all data to the given <tt>handle</tt> | ||
| 212 | and closes the file when done, or a sink that aborts the transmission with | ||
| 213 | the error <tt>message</tt> | ||
| 214 | </p> | ||
| 215 | |||
| 216 | <p class="note"> | ||
| 217 | In the following example, notice how the prototype is designed to | ||
| 218 | fit nicely with the <tt>io.open</tt> function. | ||
| 219 | </p> | ||
| 220 | |||
| 221 | <pre class="example"> | ||
| 222 | -- load the ltn12 module | ||
| 223 | local ltn12 = require("ltn12") | ||
| 224 | |||
| 225 | -- copy a file | ||
| 226 | ltn12.pump.all( | ||
| 227 | ltn12.source.file(io.open("original.png", "rb")), | ||
| 228 | ltn12.sink.file(io.open("copy.png", "wb")) | ||
| 229 | ) | ||
| 230 | </pre> | ||
| 231 | |||
| 232 | <!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 233 | |||
| 234 | <p class="name" id="sink.null"> | ||
| 235 | ltn12.sink.<b>null()</b> | ||
| 236 | </p> | ||
| 237 | |||
| 238 | <p class="description"> | ||
| 239 | Returns a sink that ignores all data it receives. | ||
| 240 | </p> | ||
| 241 | |||
| 242 | <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 243 | |||
| 244 | <p class="name" id="sink.simplify"> | ||
| 245 | ltn12.sink.<b>simplify(</b>sink<b>)</b> | ||
| 246 | </p> | ||
| 247 | |||
| 248 | <p class="description"> | ||
| 249 | Creates and returns a simple sink given a fancy <tt>sink</tt>. | ||
| 250 | </p> | ||
| 251 | |||
| 252 | <!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 253 | |||
| 254 | <p class="name" id="sink.table"> | ||
| 255 | ltn12.sink.<b>table(</b>[table]<b>)</b> | ||
| 256 | </p> | ||
| 257 | |||
| 258 | <p class="description"> | ||
| 259 | Creates a sink that stores all chunks in a table. The chunks can later be | ||
| 260 | efficiently concatenated into a single string. | ||
| 261 | </p> | ||
| 262 | |||
| 263 | <p class="parameters"> | ||
| 264 | <tt>Table</tt> is used to hold the chunks. If | ||
| 265 | <tt><b>nil</b></tt>, the function creates its own table. | ||
| 266 | </p> | ||
| 267 | |||
| 268 | <p class="return"> | ||
| 269 | The function returns the sink and the table used to store the chunks. | ||
| 270 | </p> | ||
| 271 | |||
| 272 | <pre class="example"> | ||
| 273 | -- load needed modules | ||
| 274 | local http = require("socket.http") | ||
| 275 | local ltn12 = require("ltn12") | ||
| 276 | |||
| 277 | -- a simplified http.get function | ||
| 278 | function http.get(u) | ||
| 279 | local t = {} | ||
| 280 | local respt = request{ | ||
| 281 | url = u, | ||
| 282 | sink = ltn12.sink.table(t) | ||
| 283 | } | ||
| 284 | return table.concat(t), respt.headers, respt.code | ||
| 285 | end | ||
| 286 | </pre> | ||
| 287 | |||
| 288 | <!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 289 | |||
| 290 | <h3 id="source">Sources</h3> | ||
| 291 | |||
| 292 | <!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 293 | |||
| 294 | <p class="name" id="source.cat"> | ||
| 295 | ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ..., | ||
| 296 | source<sub>N</sub>]<b>)</b> | ||
| 297 | </p> | ||
| 298 | |||
| 299 | <p class="description"> | ||
| 300 | Creates a new source that produces the concatenation of the data produced | ||
| 301 | by a number of sources. | ||
| 302 | </p> | ||
| 303 | |||
| 304 | <p class="parameters"> | ||
| 305 | <tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original | ||
| 306 | sources. | ||
| 307 | </p> | ||
| 308 | |||
| 309 | <p class="return"> | ||
| 310 | The function returns the new source. | ||
| 311 | </p> | ||
| 312 | |||
| 313 | <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 314 | |||
| 315 | <p class="name" id="source.chain"> | ||
| 316 | ltn12.source.<b>chain(</b>source, filter<b>)</b> | ||
| 317 | </p> | ||
| 318 | |||
| 319 | <p class="description"> | ||
| 320 | Creates a new <tt>source</tt> that passes data through a <tt>filter</tt> | ||
| 321 | before returning it. | ||
| 322 | </p> | ||
| 323 | |||
| 324 | <p class="return"> | ||
| 325 | The function returns the new source. | ||
| 326 | </p> | ||
| 327 | |||
| 328 | <!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 329 | |||
| 330 | <p class="name" id="source.empty"> | ||
| 331 | ltn12.source.<b>empty()</b> | ||
| 332 | </p> | ||
| 333 | |||
| 334 | <p class="description"> | ||
| 335 | Creates and returns an empty source. | ||
| 336 | </p> | ||
| 337 | |||
| 338 | <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 339 | |||
| 340 | <p class="name" id="source.error"> | ||
| 341 | ltn12.source.<b>error(</b>message<b>)</b> | ||
| 342 | </p> | ||
| 343 | |||
| 344 | <p class="description"> | ||
| 345 | Creates and returns a source that aborts transmission with the error | ||
| 346 | <tt>message</tt>. | ||
| 347 | </p> | ||
| 348 | |||
| 349 | <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 350 | |||
| 351 | <p class="name" id="source.file"> | ||
| 352 | ltn12.source.<b>file(</b>handle, message<b>)</b> | ||
| 353 | </p> | ||
| 354 | |||
| 355 | <p class="description"> | ||
| 356 | Creates a source that produces the contents of a file. | ||
| 357 | </p> | ||
| 358 | |||
| 359 | <p class="parameters"> | ||
| 360 | <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, | ||
| 361 | <tt>message</tt> should give the reason for failure. | ||
| 362 | </p> | ||
| 363 | |||
| 364 | <p class="return"> | ||
| 365 | The function returns a source that reads chunks of data from | ||
| 366 | given <tt>handle</tt> and returns it to the user, | ||
| 367 | closing the file when done, or a source that aborts the transmission with | ||
| 368 | the error <tt>message</tt> | ||
| 369 | </p> | ||
| 370 | |||
| 371 | <p class="note"> | ||
| 372 | In the following example, notice how the prototype is designed to | ||
| 373 | fit nicely with the <tt>io.open</tt> function. | ||
| 374 | </p> | ||
| 375 | |||
| 376 | <pre class="example"> | ||
| 377 | -- load the ltn12 module | ||
| 378 | local ltn12 = require("ltn12") | ||
| 379 | |||
| 380 | -- copy a file | ||
| 381 | ltn12.pump.all( | ||
| 382 | ltn12.source.file(io.open("original.png", "rb")), | ||
| 383 | ltn12.sink.file(io.open("copy.png", "wb")) | ||
| 384 | ) | ||
| 385 | </pre> | ||
| 386 | |||
| 387 | <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 388 | |||
| 389 | <p class="name" id="source.simplify"> | ||
| 390 | ltn12.source.<b>simplify(</b>source<b>)</b> | ||
| 391 | </p> | ||
| 392 | |||
| 393 | <p class="description"> | ||
| 394 | Creates and returns a simple source given a fancy <tt>source</tt>. | ||
| 395 | </p> | ||
| 396 | |||
| 397 | <!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 398 | |||
| 399 | <p class="name" id="source.string"> | ||
| 400 | ltn12.source.<b>string(</b>string<b>)</b> | ||
| 401 | </p> | ||
| 402 | |||
| 403 | <p class="description"> | ||
| 404 | Creates and returns a source that produces the contents of a | ||
| 405 | <tt>string</tt>, chunk by chunk. | ||
| 406 | </p> | ||
| 407 | |||
| 408 | <!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 409 | |||
| 410 | <p class="name" id="source.table"> | ||
| 411 | ltn12.source.<b>table(</b>table<b>)</b> | ||
| 412 | </p> | ||
| 413 | |||
| 414 | <p class="description"> | ||
| 415 | Creates and returns a source that produces the numerically-indexed values of a <tt>table</tt> successively beginning at 1. The source returns nil (end-of-stream) whenever a nil value is produced by the current index, which proceeds forward regardless. | ||
| 416 | </p> | ||
| 417 | |||
| 418 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 419 | |||
| 420 | <div class="footer"> | ||
| 421 | <hr> | ||
| 422 | <center> | ||
| 423 | <p class="bar"> | ||
| 424 | <a href="index.html">home</a> · | ||
| 425 | <a href="index.html#down">download</a> · | ||
| 426 | <a href="installation.html">installation</a> · | ||
| 427 | <a href="introduction.html">introduction</a> · | ||
| 428 | <a href="reference.html">reference</a> | ||
| 429 | </p> | ||
| 430 | <p> | ||
| 431 | <small> | ||
| 432 | Last modified by Diego Nehab on <br> | ||
| 433 | Thu Apr 20 00:25:41 EDT 2006 | ||
| 434 | </small> | ||
| 435 | </p> | ||
| 436 | </center> | ||
| 437 | </div> | ||
| 438 | |||
| 439 | </body> | ||
| 440 | </html> | ||
diff --git a/docs/lua05.ppt b/docs/lua05.ppt new file mode 100644 index 0000000..e2b7ab4 --- /dev/null +++ b/docs/lua05.ppt | |||
| Binary files differ | |||
diff --git a/docs/luasocket.png b/docs/luasocket.png new file mode 100644 index 0000000..d24a954 --- /dev/null +++ b/docs/luasocket.png | |||
| Binary files differ | |||
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> · | ||
| 28 | <a href="index.html#download">download</a> · | ||
| 29 | <a href="installation.html">installation</a> · | ||
| 30 | <a href="introduction.html">introduction</a> · | ||
| 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.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> | ||
| 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 | |||
| 76 | <!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 77 | |||
| 78 | <p class="name" id="decode"> | ||
| 79 | mime.<b>decode(</b>"base64"<b>)</b><br> | ||
| 80 | mime.<b>decode(</b>"quoted-printable"<b>)</b> | ||
| 81 | </p> | ||
| 82 | |||
| 83 | <p class="description"> | ||
| 84 | Returns a filter that decodes data from a given transfer content | ||
| 85 | encoding. | ||
| 86 | </p> | ||
| 87 | |||
| 88 | <!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 89 | |||
| 90 | <p class="name" id="encode"> | ||
| 91 | mime.<b>encode(</b>"base64"<b>)</b><br> | ||
| 92 | mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b> | ||
| 93 | </p> | ||
| 94 | |||
| 95 | <p class="description"> | ||
| 96 | Returns a filter that encodes data according to a given transfer content | ||
| 97 | encoding. | ||
| 98 | </p> | ||
| 99 | |||
| 100 | <p class="parameters"> | ||
| 101 | In the Quoted-Printable case, the user can specify whether the data is | ||
| 102 | textual 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"> | ||
| 107 | Although both transfer content encodings specify a limit for the line | ||
| 108 | length, the encoding filters do <em>not</em> break text into lines (for | ||
| 109 | added flexibility). | ||
| 110 | Below is a filter that converts binary data to the Base64 transfer content | ||
| 111 | encoding and breaks it into lines of the correct size. | ||
| 112 | </p> | ||
| 113 | |||
| 114 | <pre class="example"> | ||
| 115 | base64 = ltn12.filter.chain( | ||
| 116 | mime.encode("base64"), | ||
| 117 | mime.wrap("base64") | ||
| 118 | ) | ||
| 119 | </pre> | ||
| 120 | |||
| 121 | <p class="note"> | ||
| 122 | Note: Text data <em>has</em> to be converted to canonic form | ||
| 123 | <em>before</em> being encoded. | ||
| 124 | </p> | ||
| 125 | |||
| 126 | <pre class="example"> | ||
| 127 | base64 = 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"> | ||
| 137 | mime.<b>normalize(</b>[marker]<b>)</b> | ||
| 138 | </p> | ||
| 139 | |||
| 140 | <p class="description"> | ||
| 141 | Converts 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 | ||
| 146 | end-of-line marker defined by the MIME standard. | ||
| 147 | </p> | ||
| 148 | |||
| 149 | <p class="return"> | ||
| 150 | The function returns a filter that performs the conversion. | ||
| 151 | </p> | ||
| 152 | |||
| 153 | <p class="note"> | ||
| 154 | Note: There is no perfect solution to this problem. Different end-of-line | ||
| 155 | markers are an evil that will probably plague developers forever. | ||
| 156 | This function, however, will work perfectly for text created with any of | ||
| 157 | the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF), | ||
| 158 | or the DOS (CRLF) conventions. Even if the data has mixed end-of-line | ||
| 159 | markers, the function will still work well, although it doesn't | ||
| 160 | guarantee that the number of empty lines will be correct. | ||
| 161 | </p> | ||
| 162 | |||
| 163 | <!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 164 | |||
| 165 | <p class="name" id="stuff"> | ||
| 166 | mime.<b>stuff()</b><br> | ||
| 167 | </p> | ||
| 168 | |||
| 169 | <p class="description"> | ||
| 170 | Creates and returns a filter that performs stuffing of SMTP messages. | ||
| 171 | </p> | ||
| 172 | |||
| 173 | <p class="note"> | ||
| 174 | Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function | ||
| 175 | uses this filter automatically. You don't need to chain it with your | ||
| 176 | source, or apply it to your message body. | ||
| 177 | </p> | ||
| 178 | |||
| 179 | <!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 180 | |||
| 181 | <p class="name" id="wrap"> | ||
| 182 | mime.<b>wrap(</b>"text" [, length]<b>)</b><br> | ||
| 183 | mime.<b>wrap(</b>"base64"<b>)</b><br> | ||
| 184 | mime.<b>wrap(</b>"quoted-printable"<b>)</b> | ||
| 185 | </p> | ||
| 186 | |||
| 187 | <p class="description"> | ||
| 188 | Returns a filter that breaks data into lines. | ||
| 189 | </p> | ||
| 190 | |||
| 191 | <p class="parameters"> | ||
| 192 | The "<tt>text</tt>" line-wrap filter simply breaks text into lines by | ||
| 193 | inserting CRLF end-of-line markers at appropriate positions. | ||
| 194 | <tt>Length</tt> defaults 76. | ||
| 195 | The "<tt>base64</tt>" line-wrap filter works just like the default | ||
| 196 | "<tt>text</tt>" line-wrap filter with default length. | ||
| 197 | The function can also wrap "<tt>quoted-printable</tt>" lines, taking care | ||
| 198 | not to break lines in the middle of an escaped character. In that case, the | ||
| 199 | line length is fixed at 76. | ||
| 200 | </p> | ||
| 201 | |||
| 202 | <p class="note"> | ||
| 203 | For 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"> | ||
| 207 | qp = ltn12.filter.chain( | ||
| 208 | mime.normalize(), | ||
| 209 | mime.encode("quoted-printable"), | ||
| 210 | mime.wrap("quoted-printable") | ||
| 211 | ) | ||
| 212 | </pre> | ||
| 213 | |||
| 214 | <p class="note"> | ||
| 215 | Note: To break into lines with a different end-of-line convention, apply | ||
| 216 | a 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"> | ||
| 226 | A, B = mime.<b>b64(</b>C [, D]<b>)</b> | ||
| 227 | </p> | ||
| 228 | |||
| 229 | <p class="description"> | ||
| 230 | Low-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> | ||
| 236 | that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of | ||
| 237 | <tt>C..D</tt>, <em>before</em> encoding. | ||
| 238 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with | ||
| 239 | the encoding of the remaining bytes of <tt>C</tt>. | ||
| 240 | </p> | ||
| 241 | |||
| 242 | <p class="note"> | ||
| 243 | Note: The simplest use of this function is to encode a string into it's | ||
| 244 | Base64 transfer content encoding. Notice the extra parenthesis around the | ||
| 245 | call to <tt>mime.b64</tt>, to discard the second return value. | ||
| 246 | </p> | ||
| 247 | |||
| 248 | <pre class="example"> | ||
| 249 | print((mime.b64("diego:password"))) | ||
| 250 | --> ZGllZ286cGFzc3dvcmQ= | ||
| 251 | </pre> | ||
| 252 | |||
| 253 | <!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 254 | <p class="name" id="dot"> | ||
| 255 | A, n = mime.<b>dot(</b>m [, B]<b>)</b> | ||
| 256 | </p> | ||
| 257 | |||
| 258 | <p class="description"> | ||
| 259 | Low-level filter to perform SMTP stuffing and enable transmission of | ||
| 260 | messages 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 | ||
| 265 | number 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 | ||
| 270 | an implicit CRLF. Therefore, to stuff a message correctly, the | ||
| 271 | first <tt>m</tt> should have the value 2. | ||
| 272 | </p> | ||
| 273 | |||
| 274 | <pre class="example"> | ||
| 275 | print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n"))) | ||
| 276 | --> ..\nStuffing the message.\n..\n.. | ||
| 277 | </pre> | ||
| 278 | |||
| 279 | <p class="note"> | ||
| 280 | Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function | ||
| 281 | uses this filter automatically. You don't need to | ||
| 282 | apply it again. | ||
| 283 | </p> | ||
| 284 | |||
| 285 | <!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 286 | |||
| 287 | <p class="name" id="eol"> | ||
| 288 | A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b> | ||
| 289 | </p> | ||
| 290 | |||
| 291 | <p class="description"> | ||
| 292 | Low-level filter to perform end-of-line marker translation. | ||
| 293 | For each chunk, the function needs to know if the last character of the | ||
| 294 | previous chunk could be part of an end-of-line marker or not. This is the | ||
| 295 | context the function receives besides the chunk. An updated version of | ||
| 296 | the 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 | ||
| 301 | ASCII value of the last character of the previous chunk, if it was a | ||
| 302 | candidate for line break, or 0 otherwise. | ||
| 303 | <tt>B</tt> is the same as <tt>C</tt>, but for the current | ||
| 304 | chunk. <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 | ||
| 309 | unix = mime.eol(0, dos, "\n") | ||
| 310 | </pre> | ||
| 311 | |||
| 312 | <!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 313 | |||
| 314 | <p class="name" id="qp"> | ||
| 315 | A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b> | ||
| 316 | </p> | ||
| 317 | |||
| 318 | <p class="description"> | ||
| 319 | Low-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> | ||
| 325 | that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of | ||
| 326 | <tt>C..D</tt>, <em>before</em> encoding. | ||
| 327 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with | ||
| 328 | the encoding of the remaining bytes of <tt>C</tt>. | ||
| 329 | Throughout encoding, occurrences of CRLF are replaced by the | ||
| 330 | <tt>marker</tt>, which itself defaults to CRLF. | ||
| 331 | </p> | ||
| 332 | |||
| 333 | <p class="note"> | ||
| 334 | Note: The simplest use of this function is to encode a string into it's | ||
| 335 | Quoted-Printable transfer content encoding. | ||
| 336 | Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value. | ||
| 337 | </p> | ||
| 338 | |||
| 339 | <pre class="example"> | ||
| 340 | print((mime.qp("ma��"))) | ||
| 341 | --> ma=E7=E3= | ||
| 342 | </pre> | ||
| 343 | |||
| 344 | <!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 345 | |||
| 346 | <p class="name" id="qpwrp"> | ||
| 347 | A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b> | ||
| 348 | </p> | ||
| 349 | |||
| 350 | <p class="description"> | ||
| 351 | Low-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 | ||
| 358 | line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes | ||
| 359 | left in the last line of <tt>A</tt>. | ||
| 360 | </p> | ||
| 361 | |||
| 362 | <p class="note"> | ||
| 363 | Note: Besides breaking text into lines, this function makes sure the line | ||
| 364 | breaks don't fall in the middle of an escaped character combination. Also, | ||
| 365 | this function only breaks lines that are bigger than <tt>length</tt> bytes. | ||
| 366 | </p> | ||
| 367 | |||
| 368 | <!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 369 | |||
| 370 | <p class="name" id="unb64"> | ||
| 371 | A, B = mime.<b>unb64(</b>C [, D]<b>)</b> | ||
| 372 | </p> | ||
| 373 | |||
| 374 | <p class="description"> | ||
| 375 | Low-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> | ||
| 381 | that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of | ||
| 382 | <tt>C..D</tt>, <em>before</em> decoding. | ||
| 383 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string | ||
| 384 | and <tt>B</tt> returns whatever couldn't be decoded. | ||
| 385 | </p> | ||
| 386 | |||
| 387 | <p class="note"> | ||
| 388 | Note: The simplest use of this function is to decode a string from it's | ||
| 389 | Base64 transfer content encoding. | ||
| 390 | Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. | ||
| 391 | </p> | ||
| 392 | |||
| 393 | <pre class="example"> | ||
| 394 | print((mime.unb64("ZGllZ286cGFzc3dvcmQ="))) | ||
| 395 | --> diego:password | ||
| 396 | </pre> | ||
| 397 | |||
| 398 | <!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 399 | |||
| 400 | <p class="name" id="unqp"> | ||
| 401 | A, B = mime.<b>unqp(</b>C [, D]<b>)</b> | ||
| 402 | </p> | ||
| 403 | |||
| 404 | <p class="description"> | ||
| 405 | Low-level filter to remove the Quoted-Printable transfer content encoding | ||
| 406 | from 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> | ||
| 412 | that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of | ||
| 413 | <tt>C..D</tt>, <em>before</em> decoding. | ||
| 414 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with | ||
| 415 | the encoding of the remaining bytes of <tt>C</tt>. | ||
| 416 | </p> | ||
| 417 | |||
| 418 | <p class="note"> | ||
| 419 | Note: The simplest use of this function is to decode a string from it's | ||
| 420 | Quoted-Printable transfer content encoding. | ||
| 421 | Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. | ||
| 422 | </p> | ||
| 423 | |||
| 424 | <pre class="example"> | ||
| 425 | print((mime.qp("ma=E7=E3="))) | ||
| 426 | --> ma�� | ||
| 427 | </pre> | ||
| 428 | |||
| 429 | <!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 430 | |||
| 431 | <p class="name" id="wrp"> | ||
| 432 | A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b> | ||
| 433 | </p> | ||
| 434 | |||
| 435 | <p class="description"> | ||
| 436 | Low-level filter to break text into lines with CRLF marker. | ||
| 437 | Text 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 | ||
| 444 | line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes | ||
| 445 | left in the last line of <tt>A</tt>. | ||
| 446 | </p> | ||
| 447 | |||
| 448 | <p class="note"> | ||
| 449 | Note: This function only breaks lines that are bigger than | ||
| 450 | <tt>length</tt> bytes. The resulting line length does not include the CRLF | ||
| 451 | marker. | ||
| 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> · | ||
| 462 | <a href="index.html#down">download</a> · | ||
| 463 | <a href="installation.html">installation</a> · | ||
| 464 | <a href="introduction.html">introduction</a> · | ||
| 465 | <a href="reference.html">reference</a> | ||
| 466 | </p> | ||
| 467 | <p> | ||
| 468 | <small> | ||
| 469 | Last modified by Diego Nehab on <br> | ||
| 470 | Fri Mar 4 15:19:17 BRT 2016 | ||
| 471 | </small> | ||
| 472 | </p> | ||
| 473 | </center> | ||
| 474 | </div> | ||
| 475 | |||
| 476 | </body> | ||
| 477 | </html> | ||
diff --git a/docs/reference.css b/docs/reference.css new file mode 100644 index 0000000..04e38cf --- /dev/null +++ b/docs/reference.css | |||
| @@ -0,0 +1,55 @@ | |||
| 1 | body { | ||
| 2 | margin-left: 1em; | ||
| 3 | margin-right: 1em; | ||
| 4 | font-family: "Verdana", sans-serif; | ||
| 5 | background: #ffffff; | ||
| 6 | } | ||
| 7 | |||
| 8 | tt { | ||
| 9 | font-family: "Andale Mono", monospace; | ||
| 10 | } | ||
| 11 | |||
| 12 | h1, h2, h3, h4 { margin-left: 0em; } | ||
| 13 | |||
| 14 | |||
| 15 | h3 { padding-top: 1em; } | ||
| 16 | |||
| 17 | p { margin-left: 1em; } | ||
| 18 | |||
| 19 | p.name { | ||
| 20 | font-family: "Andale Mono", monospace; | ||
| 21 | padding-top: 1em; | ||
| 22 | margin-left: 0em; | ||
| 23 | } | ||
| 24 | |||
| 25 | a[href] { color: #00007f; } | ||
| 26 | |||
| 27 | blockquote { margin-left: 3em; } | ||
| 28 | |||
| 29 | pre.example { | ||
| 30 | background: #ccc; | ||
| 31 | padding: 1em; | ||
| 32 | margin-left: 1em; | ||
| 33 | font-family: "Andale Mono", monospace; | ||
| 34 | font-size: small; | ||
| 35 | } | ||
| 36 | |||
| 37 | hr { | ||
| 38 | margin-left: 0em; | ||
| 39 | background: #00007f; | ||
| 40 | border: 0px; | ||
| 41 | height: 1px; | ||
| 42 | } | ||
| 43 | |||
| 44 | ul { list-style-type: disc; } | ||
| 45 | |||
| 46 | table.index { border: 1px #00007f; } | ||
| 47 | table.index td { text-align: left; vertical-align: top; } | ||
| 48 | table.index ul { padding-top: 0em; margin-top: 0em; } | ||
| 49 | |||
| 50 | h1:first-letter, | ||
| 51 | h2:first-letter, | ||
| 52 | h2:first-letter, | ||
| 53 | h3:first-letter { color: #00007f; } | ||
| 54 | |||
| 55 | div.header, div.footer { margin-left: 0em; } | ||
diff --git a/docs/reference.html b/docs/reference.html new file mode 100644 index 0000000..2bc5f78 --- /dev/null +++ b/docs/reference.html | |||
| @@ -0,0 +1,261 @@ | |||
| 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: Index to reference manual"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, Index, Manual, Network, Library, | ||
| 8 | Support, Manual"> | ||
| 9 | <title>LuaSocket: Index to reference manual</title> | ||
| 10 | <link rel="stylesheet" href="reference.css" type="text/css"> | ||
| 11 | </head> | ||
| 12 | |||
| 13 | <body> | ||
| 14 | |||
| 15 | <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 16 | |||
| 17 | <div class="header"> | ||
| 18 | <hr> | ||
| 19 | <center> | ||
| 20 | <table summary="LuaSocket logo"> | ||
| 21 | <tr><td align="center"><a href="http://www.lua.org"> | ||
| 22 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> | ||
| 23 | </a></td></tr> | ||
| 24 | <tr><td align="center" valign="top">Network support for the Lua language | ||
| 25 | </td></tr> | ||
| 26 | </table> | ||
| 27 | <p class="bar"> | ||
| 28 | <a href="index.html">home</a> · | ||
| 29 | <a href="index.html#download">download</a> · | ||
| 30 | <a href="installation.html">installation</a> · | ||
| 31 | <a href="introduction.html">introduction</a> · | ||
| 32 | <a href="reference.html">reference</a> | ||
| 33 | </p> | ||
| 34 | </center> | ||
| 35 | <hr> | ||
| 36 | </div> | ||
| 37 | |||
| 38 | <!-- reference +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 39 | |||
| 40 | <h2>Reference</h2> | ||
| 41 | |||
| 42 | <blockquote> | ||
| 43 | <a href="dns.html">DNS (in socket)</a> | ||
| 44 | <blockquote> | ||
| 45 | <a href="dns.html#getaddrinfo">getaddrinfo</a>, | ||
| 46 | <a href="dns.html#gethostname">gethostname</a>, | ||
| 47 | <a href="dns.html#tohostname">tohostname</a>, | ||
| 48 | <a href="dns.html#toip">toip</a>. | ||
| 49 | </blockquote> | ||
| 50 | </blockquote> | ||
| 51 | |||
| 52 | <!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 53 | |||
| 54 | <blockquote> | ||
| 55 | <a href="ftp.html">FTP</a> | ||
| 56 | <blockquote> | ||
| 57 | <a href="ftp.html#get">get</a>, | ||
| 58 | <a href="ftp.html#put">put</a>. | ||
| 59 | </blockquote> | ||
| 60 | </blockquote> | ||
| 61 | |||
| 62 | <!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 63 | |||
| 64 | <blockquote> | ||
| 65 | <a href="http.html">HTTP</a> | ||
| 66 | <blockquote> | ||
| 67 | <a href="http.html#request">request</a>. | ||
| 68 | </blockquote> | ||
| 69 | </blockquote> | ||
| 70 | |||
| 71 | <!-- ltn12 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 72 | |||
| 73 | <blockquote> | ||
| 74 | <a href="ltn12.html">LTN12</a> | ||
| 75 | <blockquote> | ||
| 76 | <a href="ltn12.html#filter">filter</a>: | ||
| 77 | <a href="ltn12.html#filter.chain">chain</a>, | ||
| 78 | <a href="ltn12.html#filter.cycle">cycle</a>. | ||
| 79 | </blockquote> | ||
| 80 | <blockquote> | ||
| 81 | <a href="ltn12.html#pump">pump</a>: | ||
| 82 | <a href="ltn12.html#pump.all">all</a>, | ||
| 83 | <a href="ltn12.html#pump.step">step</a>. | ||
| 84 | </blockquote> | ||
| 85 | <blockquote> | ||
| 86 | <a href="ltn12.html#sink">sink</a>: | ||
| 87 | <a href="ltn12.html#sink.chain">chain</a>, | ||
| 88 | <a href="ltn12.html#sink.error">error</a>, | ||
| 89 | <a href="ltn12.html#sink.file">file</a>, | ||
| 90 | <a href="ltn12.html#sink.null">null</a>, | ||
| 91 | <a href="ltn12.html#sink.simplify">simplify</a>, | ||
| 92 | <a href="ltn12.html#sink.table">table</a>. | ||
| 93 | </blockquote> | ||
| 94 | <blockquote> | ||
| 95 | <a href="ltn12.html#source">source</a>: | ||
| 96 | <a href="ltn12.html#source.cat">cat</a>, | ||
| 97 | <a href="ltn12.html#source.chain">chain</a>, | ||
| 98 | <a href="ltn12.html#source.empty">empty</a>, | ||
| 99 | <a href="ltn12.html#source.error">error</a>, | ||
| 100 | <a href="ltn12.html#source.file">file</a>, | ||
| 101 | <a href="ltn12.html#source.simplify">simplify</a>, | ||
| 102 | <a href="ltn12.html#source.string">string</a>, | ||
| 103 | <a href="ltn12.html#source.table">table</a>. | ||
| 104 | </blockquote> | ||
| 105 | </blockquote> | ||
| 106 | |||
| 107 | <!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 108 | |||
| 109 | <blockquote> | ||
| 110 | <a href="mime.html">MIME</a> | ||
| 111 | <blockquote> | ||
| 112 | <a href="mime.html#high">high-level</a>: | ||
| 113 | <a href="mime.html#decode">decode</a>, | ||
| 114 | <a href="mime.html#encode">encode</a>, | ||
| 115 | <a href="mime.html#normalize">normalize</a>, | ||
| 116 | <a href="mime.html#stuff">stuff</a>, | ||
| 117 | <a href="mime.html#wrap">wrap</a>. | ||
| 118 | </blockquote> | ||
| 119 | <blockquote> | ||
| 120 | <a href="mime.html#low">low-level</a>: | ||
| 121 | <a href="mime.html#b64">b64</a>, | ||
| 122 | <a href="mime.html#dot">dot</a>, | ||
| 123 | <a href="mime.html#eol">eol</a>, | ||
| 124 | <a href="mime.html#qp">qp</a>, | ||
| 125 | <a href="mime.html#qpwrp">qpwrp</a>, | ||
| 126 | <a href="mime.html#unb64">unb64</a>, | ||
| 127 | <a href="mime.html#unqp">unqp</a>, | ||
| 128 | <a href="mime.html#wrp">wrp</a>. | ||
| 129 | </blockquote> | ||
| 130 | </blockquote> | ||
| 131 | |||
| 132 | <!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 133 | |||
| 134 | <blockquote> | ||
| 135 | <a href="smtp.html">SMTP</a> | ||
| 136 | <blockquote> | ||
| 137 | <a href="smtp.html#message">message</a>, | ||
| 138 | <a href="smtp.html#send">send</a>. | ||
| 139 | </blockquote> | ||
| 140 | </blockquote> | ||
| 141 | |||
| 142 | <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 143 | |||
| 144 | <blockquote> | ||
| 145 | <a href="socket.html">Socket</a> | ||
| 146 | <blockquote> | ||
| 147 | <a href="socket.html#bind">bind</a>, | ||
| 148 | <a href="socket.html#connect">connect</a>, | ||
| 149 | <a href="socket.html#connect">connect4</a>, | ||
| 150 | <a href="socket.html#connect">connect6</a>, | ||
| 151 | <a href="socket.html#datagramsize">_DATAGRAMSIZE</a>, | ||
| 152 | <a href="socket.html#debug">_DEBUG</a>, | ||
| 153 | <a href="dns.html#dns">dns</a>, | ||
| 154 | <a href="socket.html#gettime">gettime</a>, | ||
| 155 | <a href="socket.html#headers.canonic">headers.canonic</a>, | ||
| 156 | <a href="socket.html#newtry">newtry</a>, | ||
| 157 | <a href="socket.html#protect">protect</a>, | ||
| 158 | <a href="socket.html#select">select</a>, | ||
| 159 | <a href="socket.html#sink">sink</a>, | ||
| 160 | <a href="socket.html#skip">skip</a>, | ||
| 161 | <a href="socket.html#sleep">sleep</a>, | ||
| 162 | <a href="socket.html#setsize">_SETSIZE</a>, | ||
| 163 | <a href="socket.html#socketinvalid">_SOCKETINVALID</a>, | ||
| 164 | <a href="socket.html#source">source</a>, | ||
| 165 | <a href="tcp.html#socket.tcp">tcp</a>, | ||
| 166 | <a href="tcp.html#socket.tcp4">tcp4</a>, | ||
| 167 | <a href="tcp.html#socket.tcp6">tcp6</a>, | ||
| 168 | <a href="socket.html#try">try</a>, | ||
| 169 | <a href="udp.html#socket.udp">udp</a>, | ||
| 170 | <a href="udp.html#socket.udp4">udp4</a>, | ||
| 171 | <a href="udp.html#socket.udp6">udp6</a>, | ||
| 172 | <a href="socket.html#version">_VERSION</a>. | ||
| 173 | </blockquote> | ||
| 174 | </blockquote> | ||
| 175 | |||
| 176 | <!-- tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 177 | |||
| 178 | <blockquote> | ||
| 179 | <a href="tcp.html">TCP (in socket)</a> | ||
| 180 | <blockquote> | ||
| 181 | <a href="tcp.html#accept">accept</a>, | ||
| 182 | <a href="tcp.html#bind">bind</a>, | ||
| 183 | <a href="tcp.html#close">close</a>, | ||
| 184 | <a href="tcp.html#connect">connect</a>, | ||
| 185 | <a href="tcp.html#dirty">dirty</a>, | ||
| 186 | <a href="tcp.html#getfd">getfd</a>, | ||
| 187 | <a href="tcp.html#getoption">getoption</a>, | ||
| 188 | <a href="tcp.html#getpeername">getpeername</a>, | ||
| 189 | <a href="tcp.html#getsockname">getsockname</a>, | ||
| 190 | <a href="tcp.html#getstats">getstats</a>, | ||
| 191 | <a href="tcp.html#gettimeout">gettimeout</a>, | ||
| 192 | <a href="tcp.html#listen">listen</a>, | ||
| 193 | <a href="tcp.html#receive">receive</a>, | ||
| 194 | <a href="tcp.html#send">send</a>, | ||
| 195 | <a href="tcp.html#setfd">setfd</a>, | ||
| 196 | <a href="tcp.html#setoption">setoption</a>, | ||
| 197 | <a href="tcp.html#setstats">setstats</a>, | ||
| 198 | <a href="tcp.html#settimeout">settimeout</a>, | ||
| 199 | <a href="tcp.html#shutdown">shutdown</a>. | ||
| 200 | </blockquote> | ||
| 201 | </blockquote> | ||
| 202 | |||
| 203 | <!-- udp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 204 | |||
| 205 | <blockquote> | ||
| 206 | <a href="udp.html">UDP (in socket)</a> | ||
| 207 | <blockquote> | ||
| 208 | <a href="udp.html#close">close</a>, | ||
| 209 | <a href="udp.html#getoption">getoption</a>, | ||
| 210 | <a href="udp.html#getpeername">getpeername</a>, | ||
| 211 | <a href="udp.html#getsockname">getsockname</a>, | ||
| 212 | <a href="udp.html#gettimeout">gettimeout</a>, | ||
| 213 | <a href="udp.html#receive">receive</a>, | ||
| 214 | <a href="udp.html#receivefrom">receivefrom</a>, | ||
| 215 | <a href="udp.html#send">send</a>, | ||
| 216 | <a href="udp.html#sendto">sendto</a>, | ||
| 217 | <a href="udp.html#setpeername">setpeername</a>, | ||
| 218 | <a href="udp.html#setsockname">setsockname</a>, | ||
| 219 | <a href="udp.html#setoption">setoption</a>, | ||
| 220 | <a href="udp.html#settimeout">settimeout</a>. | ||
| 221 | </blockquote> | ||
| 222 | </blockquote> | ||
| 223 | |||
| 224 | <!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 225 | |||
| 226 | <blockquote> | ||
| 227 | <a href="url.html">URL</a> | ||
| 228 | <blockquote> | ||
| 229 | <a href="url.html#absolute">absolute</a>, | ||
| 230 | <a href="url.html#build">build</a>, | ||
| 231 | <a href="url.html#build_path">build_path</a>, | ||
| 232 | <a href="url.html#escape">escape</a>, | ||
| 233 | <a href="url.html#parse">parse</a>, | ||
| 234 | <a href="url.html#parse_path">parse_path</a>, | ||
| 235 | <a href="url.html#unescape">unescape</a>. | ||
| 236 | </blockquote> | ||
| 237 | </blockquote> | ||
| 238 | |||
| 239 | <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 240 | |||
| 241 | <div class="footer"> | ||
| 242 | <hr> | ||
| 243 | <center> | ||
| 244 | <p class="bar"> | ||
| 245 | <a href="index.html">home</a> · | ||
| 246 | <a href="index.html#down">download</a> · | ||
| 247 | <a href="installation.html">installation</a> · | ||
| 248 | <a href="introduction.html">introduction</a> · | ||
| 249 | <a href="reference.html">reference</a> | ||
| 250 | </p> | ||
| 251 | <p> | ||
| 252 | <small> | ||
| 253 | Last modified by Diego Nehab on <br> | ||
| 254 | Thu Apr 20 00:25:47 EDT 2006 | ||
| 255 | </small> | ||
| 256 | </p> | ||
| 257 | </center> | ||
| 258 | </div> | ||
| 259 | |||
| 260 | </body> | ||
| 261 | </html> | ||
diff --git a/docs/smtp.html b/docs/smtp.html new file mode 100644 index 0000000..787d0b1 --- /dev/null +++ b/docs/smtp.html | |||
| @@ -0,0 +1,419 @@ | |||
| 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: SMTP support"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart, | ||
| 8 | Library, Support"> | ||
| 9 | <title>LuaSocket: SMTP support</title> | ||
| 10 | <link rel="stylesheet" href="reference.css" type="text/css"> | ||
| 11 | </head> | ||
| 12 | |||
| 13 | <body> | ||
| 14 | |||
| 15 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 16 | |||
| 17 | <div class="header"> | ||
| 18 | <hr> | ||
| 19 | <center> | ||
| 20 | <table summary="LuaSocket logo"> | ||
| 21 | <tr><td align="center"><a href="http://www.lua.org"> | ||
| 22 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> | ||
| 23 | </a></td></tr> | ||
| 24 | <tr><td align="center" valign="top">Network support for the Lua language | ||
| 25 | </td></tr> | ||
| 26 | </table> | ||
| 27 | <p class="bar"> | ||
| 28 | <a href="index.html">home</a> · | ||
| 29 | <a href="index.html#download">download</a> · | ||
| 30 | <a href="installation.html">installation</a> · | ||
| 31 | <a href="introduction.html">introduction</a> · | ||
| 32 | <a href="reference.html">reference</a> | ||
| 33 | </p> | ||
| 34 | </center> | ||
| 35 | <hr> | ||
| 36 | </div> | ||
| 37 | |||
| 38 | <!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 39 | |||
| 40 | <h2 id="smtp">SMTP</h2> | ||
| 41 | |||
| 42 | <p> The <tt>smtp</tt> namespace provides functionality to send e-mail | ||
| 43 | messages. The high-level API consists of two functions: one to | ||
| 44 | define an e-mail message, and another to actually send the message. | ||
| 45 | Although almost all users will find that these functions provide more than | ||
| 46 | enough functionality, the underlying implementation allows for even more | ||
| 47 | control (if you bother to read the code). | ||
| 48 | </p> | ||
| 49 | |||
| 50 | <p>The implementation conforms to the Simple Mail Transfer Protocol, | ||
| 51 | <a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a>. | ||
| 52 | Another RFC of interest is <a | ||
| 53 | href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>, | ||
| 54 | which governs the Internet Message Format. | ||
| 55 | Multipart messages (those that contain attachments) are part | ||
| 56 | of the MIME standard, but described mainly | ||
| 57 | in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>.</p> | ||
| 58 | |||
| 59 | <p> In the description below, good understanding of <a | ||
| 60 | href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters | ||
| 61 | sources and sinks</a> and the <a href="mime.html">MIME</a> module is | ||
| 62 | assumed. In fact, the SMTP module was the main reason for their | ||
| 63 | creation. </p> | ||
| 64 | |||
| 65 | <p> | ||
| 66 | To obtain the <tt>smtp</tt> namespace, run: | ||
| 67 | </p> | ||
| 68 | |||
| 69 | <pre class="example"> | ||
| 70 | -- loads the SMTP module and everything it requires | ||
| 71 | local smtp = require("socket.smtp") | ||
| 72 | </pre> | ||
| 73 | |||
| 74 | <p> | ||
| 75 | MIME headers are represented as a Lua table in the form: | ||
| 76 | </p> | ||
| 77 | |||
| 78 | <blockquote> | ||
| 79 | <table summary="MIME headers in Lua table"> | ||
| 80 | <tr><td><tt> | ||
| 81 | headers = {<br> | ||
| 82 | field-1-name = <i>field-1-value</i>,<br> | ||
| 83 | field-2-name = <i>field-2-value</i>,<br> | ||
| 84 | field-3-name = <i>field-3-value</i>,<br> | ||
| 85 | ...<br> | ||
| 86 | field-n-name = <i>field-n-value</i><br> | ||
| 87 | } | ||
| 88 | </tt></td></tr> | ||
| 89 | </table> | ||
| 90 | </blockquote> | ||
| 91 | |||
| 92 | <p> | ||
| 93 | Field names are case insensitive (as specified by the standard) and all | ||
| 94 | functions work with lowercase field names (but see | ||
| 95 | <a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>). | ||
| 96 | Field values are left unmodified. | ||
| 97 | </p> | ||
| 98 | |||
| 99 | <p class="note"> | ||
| 100 | Note: MIME headers are independent of order. Therefore, there is no problem | ||
| 101 | in representing them in a Lua table. | ||
| 102 | </p> | ||
| 103 | |||
| 104 | <p> | ||
| 105 | The following constants can be set to control the default behavior of | ||
| 106 | the SMTP module: | ||
| 107 | </p> | ||
| 108 | |||
| 109 | <ul> | ||
| 110 | <li> <tt>DOMAIN</tt>: domain used to greet the server;</li> | ||
| 111 | <li> <tt>PORT</tt>: default port used for the connection;</li> | ||
| 112 | <li> <tt>SERVER</tt>: default server used for the connection;</li> | ||
| 113 | <li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;</li> | ||
| 114 | <li> <tt>ZONE</tt>: default time zone.</li> | ||
| 115 | </ul> | ||
| 116 | |||
| 117 | <!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 118 | |||
| 119 | <p class="name" id="message"> | ||
| 120 | smtp.<b>message(</b>mesgt<b>)</b> | ||
| 121 | </p> | ||
| 122 | |||
| 123 | <p class="description"> | ||
| 124 | Returns a <em>simple</em> | ||
| 125 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep). | ||
| 126 | </p> | ||
| 127 | |||
| 128 | <p class="parameters"> | ||
| 129 | The only parameter of the function is a table describing the message. | ||
| 130 | <tt>Mesgt</tt> has the following form (notice the recursive structure): | ||
| 131 | </p> | ||
| 132 | |||
| 133 | <blockquote> | ||
| 134 | <table summary="Mesgt table structure"> | ||
| 135 | <tr><td><tt> | ||
| 136 | mesgt = {<br> | ||
| 137 | headers = <i>header-table</i>,<br> | ||
| 138 | body = <i>LTN12 source</i> or <i>string</i> or | ||
| 139 | <i>multipart-mesgt</i><br> | ||
| 140 | }<br> | ||
| 141 | <br> | ||
| 142 | multipart-mesgt = {<br> | ||
| 143 | [preamble = <i>string</i>,]<br> | ||
| 144 | [1] = <i>mesgt</i>,<br> | ||
| 145 | [2] = <i>mesgt</i>,<br> | ||
| 146 | ...<br> | ||
| 147 | [<i>n</i>] = <i>mesgt</i>,<br> | ||
| 148 | [epilogue = <i>string</i>,]<br> | ||
| 149 | }<br> | ||
| 150 | </tt></td></tr> | ||
| 151 | </table> | ||
| 152 | </blockquote> | ||
| 153 | |||
| 154 | <p class="parameters"> | ||
| 155 | For a simple message, all that is needed is a set of <tt>headers</tt> | ||
| 156 | and the <tt>body</tt>. The message <tt>body</tt> can be given as a string | ||
| 157 | or as a <em>simple</em> | ||
| 158 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 159 | source. For multipart messages, the body is a table that | ||
| 160 | recursively defines each part as an independent message, plus an optional | ||
| 161 | <tt>preamble</tt> and <tt>epilogue</tt>. | ||
| 162 | </p> | ||
| 163 | |||
| 164 | <p class="return"> | ||
| 165 | The function returns a <em>simple</em> | ||
| 166 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 167 | source that produces the | ||
| 168 | message contents as defined by <tt>mesgt</tt>, chunk by chunk. | ||
| 169 | Hopefully, the following | ||
| 170 | example will make things clear. When in doubt, refer to the appropriate RFC | ||
| 171 | as listed in the introduction. </p> | ||
| 172 | |||
| 173 | <pre class="example"> | ||
| 174 | -- load the smtp support and its friends | ||
| 175 | local smtp = require("socket.smtp") | ||
| 176 | local mime = require("mime") | ||
| 177 | local ltn12 = require("ltn12") | ||
| 178 | |||
| 179 | -- creates a source to send a message with two parts. The first part is | ||
| 180 | -- plain text, the second part is a PNG image, encoded as base64. | ||
| 181 | source = smtp.message{ | ||
| 182 | headers = { | ||
| 183 | -- Remember that headers are *ignored* by smtp.send. | ||
| 184 | from = "Sicrano de Oliveira <sicrano@example.com>", | ||
| 185 | to = "Fulano da Silva <fulano@example.com>", | ||
| 186 | subject = "Here is a message with attachments" | ||
| 187 | }, | ||
| 188 | body = { | ||
| 189 | preamble = "If your client doesn't understand attachments, \r\n" .. | ||
| 190 | "it will still display the preamble and the epilogue.\r\n" .. | ||
| 191 | "Preamble will probably appear even in a MIME enabled client.", | ||
| 192 | -- first part: no headers means plain text, us-ascii. | ||
| 193 | -- The mime.eol low-level filter normalizes end-of-line markers. | ||
| 194 | [1] = { | ||
| 195 | body = mime.eol(0, [[ | ||
| 196 | Lines in a message body should always end with CRLF. | ||
| 197 | The smtp module will *NOT* perform translation. However, the | ||
| 198 | send function *DOES* perform SMTP stuffing, whereas the message | ||
| 199 | function does *NOT*. | ||
| 200 | ]]) | ||
| 201 | }, | ||
| 202 | -- second part: headers describe content to be a png image, | ||
| 203 | -- sent under the base64 transfer content encoding. | ||
| 204 | -- notice that nothing happens until the message is actually sent. | ||
| 205 | -- small chunks are loaded into memory right before transmission and | ||
| 206 | -- translation happens on the fly. | ||
| 207 | [2] = { | ||
| 208 | headers = { | ||
| 209 | ["content-type"] = 'image/png; name="image.png"', | ||
| 210 | ["content-disposition"] = 'attachment; filename="image.png"', | ||
| 211 | ["content-description"] = 'a beautiful image', | ||
| 212 | ["content-transfer-encoding"] = "BASE64" | ||
| 213 | }, | ||
| 214 | body = ltn12.source.chain( | ||
| 215 | ltn12.source.file(io.open("image.png", "rb")), | ||
| 216 | ltn12.filter.chain( | ||
| 217 | mime.encode("base64"), | ||
| 218 | mime.wrap() | ||
| 219 | ) | ||
| 220 | ) | ||
| 221 | }, | ||
| 222 | epilogue = "This might also show up, but after the attachments" | ||
| 223 | } | ||
| 224 | } | ||
| 225 | |||
| 226 | -- finally send it | ||
| 227 | r, e = smtp.send{ | ||
| 228 | from = "<sicrano@example.com>", | ||
| 229 | rcpt = "<fulano@example.com>", | ||
| 230 | source = source, | ||
| 231 | } | ||
| 232 | </pre> | ||
| 233 | |||
| 234 | |||
| 235 | <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 236 | |||
| 237 | <p class="name" id="send"> | ||
| 238 | smtp.<b>send{</b><br> | ||
| 239 | from = <i>string</i>,<br> | ||
| 240 | rcpt = <i>string</i> or <i>string-table</i>,<br> | ||
| 241 | source = <i>LTN12 source</i>,<br> | ||
| 242 | [user = <i>string</i>,]<br> | ||
| 243 | [password = <i>string</i>,]<br> | ||
| 244 | [server = <i>string</i>,]<br> | ||
| 245 | [port = <i>number</i>,]<br> | ||
| 246 | [domain = <i>string</i>,]<br> | ||
| 247 | [step = <i>LTN12 pump step</i>,]<br> | ||
| 248 | [create = <i>function</i>]<br> | ||
| 249 | <b>}</b> | ||
| 250 | </p> | ||
| 251 | |||
| 252 | <p class="description"> | ||
| 253 | Sends a message to a recipient list. Since sending messages is not as | ||
| 254 | simple as downloading an URL from a FTP or HTTP server, this function | ||
| 255 | doesn't have a simple interface. However, see the | ||
| 256 | <a href="#message"><tt>message</tt></a> source factory for | ||
| 257 | a very powerful way to define the message contents. | ||
| 258 | </p> | ||
| 259 | |||
| 260 | |||
| 261 | <p class="parameters"> | ||
| 262 | The sender is given by the e-mail address in the <tt>from</tt> field. | ||
| 263 | <tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail | ||
| 264 | address, or a string | ||
| 265 | in case there is just one recipient. | ||
| 266 | The contents of the message are given by a <em>simple</em> | ||
| 267 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 268 | <tt>source</tt>. Several arguments are optional: | ||
| 269 | </p> | ||
| 270 | <ul> | ||
| 271 | <li> <tt>user</tt>, <tt>password</tt>: User and password for | ||
| 272 | authentication. The function will attempt LOGIN and PLAIN authentication | ||
| 273 | methods if supported by the server (both are unsafe);</li> | ||
| 274 | <li> <tt>server</tt>: Server to connect to. Defaults to "localhost";</li> | ||
| 275 | <li> <tt>port</tt>: Port to connect to. Defaults to 25;</li> | ||
| 276 | <li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the | ||
| 277 | local machine host name;</li> | ||
| 278 | <li> <tt>step</tt>: | ||
| 279 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 280 | pump step function used to pass data from the | ||
| 281 | source to the server. Defaults to the LTN12 <tt>pump.step</tt> function;</li> | ||
| 282 | <li><tt>create</tt>: An optional function to be used instead of | ||
| 283 | <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li> | ||
| 284 | </ul> | ||
| 285 | |||
| 286 | <p class="return"> | ||
| 287 | If successful, the function returns 1. Otherwise, the function returns | ||
| 288 | <b><tt>nil</tt></b> followed by an error message. | ||
| 289 | </p> | ||
| 290 | |||
| 291 | <p class="note"> | ||
| 292 | Note: SMTP servers can be very picky with the format of e-mail | ||
| 293 | addresses. To be safe, use only addresses of the form | ||
| 294 | "<tt><fulano@example.com></tt>" in the <tt>from</tt> and | ||
| 295 | <tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail | ||
| 296 | addresses can take whatever form you like. </p> | ||
| 297 | |||
| 298 | <p class="note"> | ||
| 299 | Big note: There is a good deal of misconception with the use of the | ||
| 300 | destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>', | ||
| 301 | and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a | ||
| 302 | '<tt>Bcc</tt>' header to your messages because it will probably do the | ||
| 303 | exact opposite of what you expect. | ||
| 304 | </p> | ||
| 305 | |||
| 306 | <p class="note"> | ||
| 307 | Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the | ||
| 308 | message. Each recipient of an SMTP mail message receives a copy of the | ||
| 309 | message body along with the headers, and nothing more. The headers | ||
| 310 | <em>are</em> part of the message and should be produced by the | ||
| 311 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 312 | <tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em> | ||
| 313 | part of the message and will not be sent to anyone. | ||
| 314 | </p> | ||
| 315 | |||
| 316 | <p class="note"> | ||
| 317 | <a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a> | ||
| 318 | has two <em>important and short</em> sections, "3.6.3. Destination address | ||
| 319 | fields" and "5. Security considerations", explaining the proper | ||
| 320 | use of these headers. Here is a summary of what it says: | ||
| 321 | </p> | ||
| 322 | |||
| 323 | <ul> | ||
| 324 | <li> <tt>To</tt>: contains the address(es) of the primary recipient(s) | ||
| 325 | of the message;</li> | ||
| 326 | <li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of | ||
| 327 | making a copy on a typewriter using carbon paper) contains the | ||
| 328 | addresses of others who are to receive the message, though the | ||
| 329 | content of the message may not be directed at them;</li> | ||
| 330 | <li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon | ||
| 331 | Copy") contains addresses of recipients of the message whose addresses are not | ||
| 332 | to be revealed to other recipients of the message.</li> | ||
| 333 | </ul> | ||
| 334 | |||
| 335 | <p class="note"> | ||
| 336 | The LuaSocket <tt>send</tt> function does not care or interpret the | ||
| 337 | headers you send, but it gives you full control over what is sent and | ||
| 338 | to whom it is sent: | ||
| 339 | </p> | ||
| 340 | <ul> | ||
| 341 | <li> If someone is to receive the message, the e-mail address <em>has</em> | ||
| 342 | to be in the recipient list. This is the only parameter that controls who | ||
| 343 | gets a copy of the message;</li> | ||
| 344 | <li> If there are multiple recipients, none of them will automatically | ||
| 345 | know that someone else got that message. That is, the default behavior is | ||
| 346 | similar to the <tt>Bcc</tt> field of popular e-mail clients;</li> | ||
| 347 | <li> It is up to you to add the <tt>To</tt> header with the list of primary | ||
| 348 | recipients so that other recipients can see it;</li> | ||
| 349 | <li> It is also up to you to add the <tt>Cc</tt> header with the | ||
| 350 | list of additional recipients so that everyone else sees it;</li> | ||
| 351 | <li> Adding a header <tt>Bcc</tt> is nonsense, unless it is | ||
| 352 | empty. Otherwise, everyone receiving the message will see it and that is | ||
| 353 | exactly what you <em>don't</em> want to happen!</li> | ||
| 354 | </ul> | ||
| 355 | |||
| 356 | <p class="note"> | ||
| 357 | I hope this clarifies the issue. Otherwise, please refer to | ||
| 358 | <a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a> | ||
| 359 | and | ||
| 360 | <a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>. | ||
| 361 | </p> | ||
| 362 | |||
| 363 | <pre class="example"> | ||
| 364 | -- load the smtp support | ||
| 365 | local smtp = require("socket.smtp") | ||
| 366 | |||
| 367 | -- Connects to server "localhost" and sends a message to users | ||
| 368 | -- "fulano@example.com", "beltrano@example.com", | ||
| 369 | -- and "sicrano@example.com". | ||
| 370 | -- Note that "fulano" is the primary recipient, "beltrano" receives a | ||
| 371 | -- carbon copy and neither of them knows that "sicrano" received a blind | ||
| 372 | -- carbon copy of the message. | ||
| 373 | from = "<luasocket@example.com>" | ||
| 374 | |||
| 375 | rcpt = { | ||
| 376 | "<fulano@example.com>", | ||
| 377 | "<beltrano@example.com>", | ||
| 378 | "<sicrano@example.com>" | ||
| 379 | } | ||
| 380 | |||
| 381 | mesgt = { | ||
| 382 | headers = { | ||
| 383 | to = "Fulano da Silva <fulano@example.com>", | ||
| 384 | cc = '"Beltrano F. Nunes" <beltrano@example.com>', | ||
| 385 | subject = "My first message" | ||
| 386 | }, | ||
| 387 | body = "I hope this works. If it does, I can send you another 1000 copies." | ||
| 388 | } | ||
| 389 | |||
| 390 | r, e = smtp.send{ | ||
| 391 | from = from, | ||
| 392 | rcpt = rcpt, | ||
| 393 | source = smtp.message(mesgt) | ||
| 394 | } | ||
| 395 | </pre> | ||
| 396 | |||
| 397 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 398 | |||
| 399 | <div class="footer"> | ||
| 400 | <hr> | ||
| 401 | <center> | ||
| 402 | <p class="bar"> | ||
| 403 | <a href="index.html">home</a> · | ||
| 404 | <a href="index.html#down">download</a> · | ||
| 405 | <a href="installation.html">installation</a> · | ||
| 406 | <a href="introduction.html">introduction</a> · | ||
| 407 | <a href="reference.html">reference</a> | ||
| 408 | </p> | ||
| 409 | <p> | ||
| 410 | <small> | ||
| 411 | Last modified by Diego Nehab on <br> | ||
| 412 | Thu Apr 20 00:25:51 EDT 2006 | ||
| 413 | </small> | ||
| 414 | </p> | ||
| 415 | </center> | ||
| 416 | </div> | ||
| 417 | |||
| 418 | </body> | ||
| 419 | </html> | ||
diff --git a/docs/socket.html b/docs/socket.html new file mode 100644 index 0000000..c148114 --- /dev/null +++ b/docs/socket.html | |||
| @@ -0,0 +1,481 @@ | |||
| 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: The core namespace"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support"> | ||
| 8 | <title>LuaSocket: The socket namespace</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="https://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> · | ||
| 28 | <a href="index.html#download">download</a> · | ||
| 29 | <a href="installation.html">installation</a> · | ||
| 30 | <a href="introduction.html">introduction</a> · | ||
| 31 | <a href="reference.html">reference</a> | ||
| 32 | </p> | ||
| 33 | </center> | ||
| 34 | <hr> | ||
| 35 | </div> | ||
| 36 | |||
| 37 | <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 38 | |||
| 39 | <h2 id="socket">The socket namespace</h2> | ||
| 40 | |||
| 41 | <p> | ||
| 42 | The <tt>socket</tt> namespace contains the core functionality of LuaSocket. | ||
| 43 | </p> | ||
| 44 | |||
| 45 | <p> | ||
| 46 | To obtain the <tt>socket</tt> namespace, run: | ||
| 47 | </p> | ||
| 48 | |||
| 49 | <pre class="example"> | ||
| 50 | -- loads the socket module | ||
| 51 | local socket = require("socket") | ||
| 52 | </pre> | ||
| 53 | |||
| 54 | <!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 55 | |||
| 56 | <p class="name" id="headers.canonic"> | ||
| 57 | socket.headers.<b>canonic</b></p> | ||
| 58 | |||
| 59 | <p> The <tt>socket.headers.canonic</tt> table | ||
| 60 | is used by the HTTP and SMTP modules to translate from | ||
| 61 | lowercase field names back into their canonic | ||
| 62 | capitalization. When a lowercase field name exists as a key | ||
| 63 | in this table, the associated value is substituted in | ||
| 64 | whenever the field name is sent out. | ||
| 65 | </p> | ||
| 66 | |||
| 67 | <p> | ||
| 68 | You can obtain the <tt>headers</tt> namespace if case run-time | ||
| 69 | modifications are required by running: | ||
| 70 | </p> | ||
| 71 | |||
| 72 | <pre class="example"> | ||
| 73 | -- loads the headers module | ||
| 74 | local headers = require("headers") | ||
| 75 | </pre> | ||
| 76 | |||
| 77 | |||
| 78 | <!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 79 | |||
| 80 | <p class="name" id="bind"> | ||
| 81 | socket.<b>bind(</b>address, port [, backlog]<b>)</b> | ||
| 82 | </p> | ||
| 83 | |||
| 84 | <p class="description"> | ||
| 85 | This function is a shortcut that creates and returns a TCP server object | ||
| 86 | bound to a local <tt>address</tt> and <tt>port</tt>, ready to | ||
| 87 | accept client connections. Optionally, | ||
| 88 | user can also specify the <tt>backlog</tt> argument to the | ||
| 89 | <a href="tcp.html#listen"><tt>listen</tt></a> method (defaults to 32). | ||
| 90 | </p> | ||
| 91 | |||
| 92 | <p class="note"> | ||
| 93 | Note: The server object returned will have the option "<tt>reuseaddr</tt>" | ||
| 94 | set to <tt><b>true</b></tt>. | ||
| 95 | </p> | ||
| 96 | |||
| 97 | <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 98 | |||
| 99 | <p class="name" id="connect"> | ||
| 100 | socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b> | ||
| 101 | </p> | ||
| 102 | |||
| 103 | <p class="description"> | ||
| 104 | This function is a shortcut that creates and returns a TCP client object | ||
| 105 | connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally, | ||
| 106 | the user can also specify the local address and port to bind | ||
| 107 | (<tt>locaddr</tt> and <tt>locport</tt>), or restrict the socket family | ||
| 108 | to "<tt>inet</tt>" or "<tt>inet6</tt>". | ||
| 109 | Without specifying <tt>family</tt> to <tt>connect</tt>, whether a tcp or tcp6 | ||
| 110 | connection is created depends on your system configuration. Two variations | ||
| 111 | of connect are defined as simple helper functions that restrict the | ||
| 112 | <tt>family</tt>, <tt>socket.connect4</tt> and <tt>socket.connect6</tt>. | ||
| 113 | </p> | ||
| 114 | |||
| 115 | <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 116 | |||
| 117 | <p class="name" id="debug"> | ||
| 118 | socket.<b>_DEBUG</b> | ||
| 119 | </p> | ||
| 120 | |||
| 121 | <p class="description"> | ||
| 122 | This constant is set to <tt><b>true</b></tt> if the library was compiled | ||
| 123 | with debug support. | ||
| 124 | </p> | ||
| 125 | |||
| 126 | <!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 127 | |||
| 128 | <p class="name" id="datagramsize"> | ||
| 129 | socket.<b>_DATAGRAMSIZE</b> | ||
| 130 | </p> | ||
| 131 | |||
| 132 | <p class="description"> | ||
| 133 | Default datagram size used by calls to | ||
| 134 | <a href="udp.html#receive"><tt>receive</tt></a> and | ||
| 135 | <a href="udp.html#receivefrom"><tt>receivefrom</tt></a>. | ||
| 136 | (Unless changed in compile time, the value is 8192.) | ||
| 137 | </p> | ||
| 138 | |||
| 139 | <!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 140 | |||
| 141 | <p class="name" id="gettime"> | ||
| 142 | socket.<b>gettime()</b> | ||
| 143 | </p> | ||
| 144 | |||
| 145 | <p class="description"> | ||
| 146 | Returns the UNIX time in seconds. You should subtract the values returned by this function | ||
| 147 | to get meaningful values. | ||
| 148 | </p> | ||
| 149 | |||
| 150 | <pre class="example"> | ||
| 151 | t = socket.gettime() | ||
| 152 | -- do stuff | ||
| 153 | print(socket.gettime() - t .. " seconds elapsed") | ||
| 154 | </pre> | ||
| 155 | |||
| 156 | <!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 157 | |||
| 158 | <p class="name" id="newtry"> | ||
| 159 | socket.<b>newtry(</b>finalizer<b>)</b> | ||
| 160 | </p> | ||
| 161 | |||
| 162 | <p class="description"> | ||
| 163 | Creates and returns a <em>clean</em> | ||
| 164 | <a href="#try"><tt>try</tt></a> | ||
| 165 | function that allows for cleanup before the exception | ||
| 166 | is raised. | ||
| 167 | </p> | ||
| 168 | |||
| 169 | <p class="parameters"> | ||
| 170 | <tt>Finalizer</tt> is a function that will be called before | ||
| 171 | <tt>try</tt> throws the exception. | ||
| 172 | </p> | ||
| 173 | |||
| 174 | <p class="return"> | ||
| 175 | The function returns your customized <tt>try</tt> function. | ||
| 176 | </p> | ||
| 177 | |||
| 178 | <p class="note"> | ||
| 179 | Note: This idea saved a <em>lot</em> of work with the | ||
| 180 | implementation of protocols in LuaSocket: | ||
| 181 | </p> | ||
| 182 | |||
| 183 | <pre class="example"> | ||
| 184 | foo = socket.protect(function() | ||
| 185 | -- connect somewhere | ||
| 186 | local c = socket.try(socket.connect("somewhere", 42)) | ||
| 187 | -- create a try function that closes 'c' on error | ||
| 188 | local try = socket.newtry(function() c:close() end) | ||
| 189 | -- do everything reassured c will be closed | ||
| 190 | try(c:send("hello there?\r\n")) | ||
| 191 | local answer = try(c:receive()) | ||
| 192 | ... | ||
| 193 | try(c:send("good bye\r\n")) | ||
| 194 | c:close() | ||
| 195 | end) | ||
| 196 | </pre> | ||
| 197 | |||
| 198 | |||
| 199 | <!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 200 | |||
| 201 | <p class="name" id="protect"> | ||
| 202 | socket.<b>protect(</b>func<b>)</b> | ||
| 203 | </p> | ||
| 204 | |||
| 205 | <p class="description"> | ||
| 206 | Converts a function that throws exceptions into a safe function. This | ||
| 207 | function only catches exceptions thrown by the <a href="#try"><tt>try</tt></a> | ||
| 208 | and <a href="#newtry"><tt>newtry</tt></a> functions. It does not catch normal | ||
| 209 | Lua errors. | ||
| 210 | </p> | ||
| 211 | |||
| 212 | <p class="parameters"> | ||
| 213 | <tt>Func</tt> is a function that calls | ||
| 214 | <a href="#try"><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>) | ||
| 215 | to throw exceptions. | ||
| 216 | </p> | ||
| 217 | |||
| 218 | <p class="return"> | ||
| 219 | Returns an equivalent function that instead of throwing exceptions in case of | ||
| 220 | a failed <a href="#try"><tt>try</tt></a> call, returns <tt><b>nil</b></tt> | ||
| 221 | followed by an error message. | ||
| 222 | </p> | ||
| 223 | |||
| 224 | <!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 225 | |||
| 226 | <p class="name" id="select"> | ||
| 227 | socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b> | ||
| 228 | </p> | ||
| 229 | |||
| 230 | <p class="description"> | ||
| 231 | Waits for a number of sockets to change status. | ||
| 232 | </p> | ||
| 233 | |||
| 234 | <p class="parameters"> | ||
| 235 | <tt>Recvt</tt> is an array with the sockets to test for characters | ||
| 236 | available for reading. Sockets in the <tt>sendt</tt> array are watched to | ||
| 237 | see if it is OK to immediately write on them. <tt>Timeout</tt> is the | ||
| 238 | maximum amount of time (in seconds) to wait for a change in status. A | ||
| 239 | <tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the | ||
| 240 | function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also | ||
| 241 | be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with | ||
| 242 | non-numeric indices) in the arrays will be silently ignored. | ||
| 243 | </p> | ||
| 244 | |||
| 245 | <p class="return"> The function returns a list with the sockets ready for | ||
| 246 | reading, a list with the sockets ready for writing and an error message. | ||
| 247 | The error message is "<tt>timeout</tt>" if a timeout | ||
| 248 | condition was met, "<tt>select failed</tt>" if the call | ||
| 249 | to <tt>select</tt> failed, and | ||
| 250 | <tt><b>nil</b></tt> otherwise. The returned tables are | ||
| 251 | doubly keyed both by integers and also by the sockets | ||
| 252 | themselves, to simplify the test if a specific socket has | ||
| 253 | changed status. | ||
| 254 | </p> | ||
| 255 | |||
| 256 | <p class="note"> | ||
| 257 | <b>Note:</b> <tt>select</tt> can monitor a limited number | ||
| 258 | of sockets, as defined by the constant <a href="#setsize"> | ||
| 259 | <tt>socket._SETSIZE</tt></a>. This | ||
| 260 | number may be as high as 1024 or as low as 64 by default, | ||
| 261 | depending on the system. It is usually possible to change this | ||
| 262 | at compile time. Invoking <tt>select</tt> with a larger | ||
| 263 | number of sockets will raise an error. | ||
| 264 | </p> | ||
| 265 | |||
| 266 | <p class="note"> | ||
| 267 | <b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail | ||
| 268 | on non-blocking TCP sockets. The function may return a socket as | ||
| 269 | writable even though the socket is <em>not</em> ready for sending. | ||
| 270 | </p> | ||
| 271 | |||
| 272 | <p class="note"> | ||
| 273 | <b>Another important note</b>: calling select with a server socket in the receive parameter before a call to accept does <em>not</em> guarantee | ||
| 274 | <a href="tcp.html#accept"><tt>accept</tt></a> will return immediately. | ||
| 275 | Use the <a href="tcp.html#settimeout"><tt>settimeout</tt></a> | ||
| 276 | method or <tt>accept</tt> might block forever. | ||
| 277 | </p> | ||
| 278 | |||
| 279 | <p class="note"> | ||
| 280 | <b>Yet another note</b>: If you close a socket and pass | ||
| 281 | it to <tt>select</tt>, it will be ignored. | ||
| 282 | </p> | ||
| 283 | |||
| 284 | <p class="note"> | ||
| 285 | <b>Using select with non-socket objects</b>: Any object that implements <tt>getfd</tt> and <tt>dirty</tt> can be used with <tt>select</tt>, allowing objects from other libraries to be used within a <tt>socket.select</tt> driven loop. | ||
| 286 | </p> | ||
| 287 | |||
| 288 | <!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 289 | |||
| 290 | <p class="name" id="setsize"> | ||
| 291 | socket.<b>_SETSIZE</b> | ||
| 292 | </p> | ||
| 293 | |||
| 294 | <p class="description"> | ||
| 295 | The maximum number of sockets that the <a | ||
| 296 | href="#select"><tt>select</tt></a> function can handle. | ||
| 297 | </p> | ||
| 298 | |||
| 299 | |||
| 300 | <!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 301 | |||
| 302 | <p class="name" id="sink"> | ||
| 303 | socket.<b>sink(</b>mode, socket<b>)</b> | ||
| 304 | </p> | ||
| 305 | |||
| 306 | <p class="description"> | ||
| 307 | Creates an | ||
| 308 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 309 | sink from a stream socket object. | ||
| 310 | </p> | ||
| 311 | |||
| 312 | <p class="parameters"> | ||
| 313 | <tt>Mode</tt> defines the behavior of the sink. The following | ||
| 314 | options are available: | ||
| 315 | </p> | ||
| 316 | <ul> | ||
| 317 | <li> <tt>"http-chunked"</tt>: sends data through socket after applying the | ||
| 318 | <em>chunked transfer coding</em>, closing the socket when done;</li> | ||
| 319 | <li> <tt>"close-when-done"</tt>: sends all received data through the | ||
| 320 | socket, closing the socket when done;</li> | ||
| 321 | <li> <tt>"keep-open"</tt>: sends all received data through the | ||
| 322 | socket, leaving it open when done.</li> | ||
| 323 | </ul> | ||
| 324 | <p> | ||
| 325 | <tt>Socket</tt> is the stream socket object used to send the data. | ||
| 326 | </p> | ||
| 327 | |||
| 328 | <p class="return"> | ||
| 329 | The function returns a sink with the appropriate behavior. | ||
| 330 | </p> | ||
| 331 | |||
| 332 | <!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 333 | |||
| 334 | <p class="name" id="skip"> | ||
| 335 | socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> | ||
| 336 | </p> | ||
| 337 | |||
| 338 | <p class="description"> | ||
| 339 | Drops a number of arguments and returns the remaining. | ||
| 340 | </p> | ||
| 341 | |||
| 342 | <p class="parameters"> | ||
| 343 | <tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to | ||
| 344 | <tt>ret<sub>N</sub></tt> are the arguments. | ||
| 345 | </p> | ||
| 346 | |||
| 347 | <p class="return"> | ||
| 348 | The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>. | ||
| 349 | </p> | ||
| 350 | |||
| 351 | <p class="note"> | ||
| 352 | Note: This function is useful to avoid creation of dummy variables: | ||
| 353 | </p> | ||
| 354 | |||
| 355 | <pre class="example"> | ||
| 356 | -- get the status code and separator from SMTP server reply | ||
| 357 | local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)")) | ||
| 358 | </pre> | ||
| 359 | |||
| 360 | <!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 361 | |||
| 362 | <p class="name" id="sleep"> | ||
| 363 | socket.<b>sleep(</b>time<b>)</b> | ||
| 364 | </p> | ||
| 365 | |||
| 366 | <p class="description"> | ||
| 367 | Freezes the program execution during a given amount of time. | ||
| 368 | </p> | ||
| 369 | |||
| 370 | <p class="parameters"> | ||
| 371 | <tt>Time</tt> is the number of seconds to sleep for. If | ||
| 372 | <tt>time</tt> is negative, the function returns immediately. | ||
| 373 | </p> | ||
| 374 | |||
| 375 | <!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 376 | |||
| 377 | <p class="name" id="source"> | ||
| 378 | socket.<b>source(</b>mode, socket [, length]<b>)</b> | ||
| 379 | </p> | ||
| 380 | |||
| 381 | <p class="description"> | ||
| 382 | Creates an | ||
| 383 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | ||
| 384 | source from a stream socket object. | ||
| 385 | </p> | ||
| 386 | |||
| 387 | <p class="parameters"> | ||
| 388 | <tt>Mode</tt> defines the behavior of the source. The following | ||
| 389 | options are available: | ||
| 390 | </p> | ||
| 391 | <ul> | ||
| 392 | <li> <tt>"http-chunked"</tt>: receives data from socket and removes the | ||
| 393 | <em>chunked transfer coding</em> before returning the data;</li> | ||
| 394 | <li> <tt>"by-length"</tt>: receives a fixed number of bytes from the | ||
| 395 | socket. This mode requires the extra argument <tt>length</tt>;</li> | ||
| 396 | <li> <tt>"until-closed"</tt>: receives data from a socket until the other | ||
| 397 | side closes the connection.</li> | ||
| 398 | </ul> | ||
| 399 | <p> | ||
| 400 | <tt>Socket</tt> is the stream socket object used to receive the data. | ||
| 401 | </p> | ||
| 402 | |||
| 403 | <p class="return"> | ||
| 404 | The function returns a source with the appropriate behavior. | ||
| 405 | </p> | ||
| 406 | |||
| 407 | <!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 408 | |||
| 409 | <p class="name" id="socketinvalid"> | ||
| 410 | socket.<b>_SOCKETINVALID</b> | ||
| 411 | </p> | ||
| 412 | |||
| 413 | <p class="description"> | ||
| 414 | The OS value for an invalid socket. This can be used with <a href="tcp.html#getfd"> | ||
| 415 | <tt>tcp:getfd</tt></a> and <a href="tcp.html#setfd"><tt>tcp:setfd</tt></a> methods. | ||
| 416 | </p> | ||
| 417 | |||
| 418 | <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 419 | |||
| 420 | <p class="name" id="try"> | ||
| 421 | socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> | ||
| 422 | </p> | ||
| 423 | |||
| 424 | <p class="description"> | ||
| 425 | Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using | ||
| 426 | <tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught | ||
| 427 | by a <a href="#protect"><tt>protect</tt></a>ed function only. | ||
| 428 | </p> | ||
| 429 | |||
| 430 | <p class="parameters"> | ||
| 431 | <tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary | ||
| 432 | arguments, but are usually the return values of a function call | ||
| 433 | nested with <tt>try</tt>. | ||
| 434 | </p> | ||
| 435 | |||
| 436 | <p class="return"> | ||
| 437 | The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if | ||
| 438 | <tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>. | ||
| 439 | Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub> wrapped | ||
| 440 | in a table with metatable used by <a href="#protect"><tt>protect</tt></a> to | ||
| 441 | distinguish exceptions from runtime errors. | ||
| 442 | </p> | ||
| 443 | |||
| 444 | <pre class="example"> | ||
| 445 | -- connects or throws an exception with the appropriate error message | ||
| 446 | c = socket.try(socket.connect("localhost", 80)) | ||
| 447 | </pre> | ||
| 448 | |||
| 449 | <!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 450 | |||
| 451 | <p class="name" id="version"> | ||
| 452 | socket.<b>_VERSION</b> | ||
| 453 | </p> | ||
| 454 | |||
| 455 | <p class="description"> | ||
| 456 | This constant has a string describing the current LuaSocket version. | ||
| 457 | </p> | ||
| 458 | |||
| 459 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 460 | |||
| 461 | <div class="footer"> | ||
| 462 | <hr> | ||
| 463 | <center> | ||
| 464 | <p class="bar"> | ||
| 465 | <a href="index.html">home</a> · | ||
| 466 | <a href="index.html#down">download</a> · | ||
| 467 | <a href="installation.html">installation</a> · | ||
| 468 | <a href="introduction.html">introduction</a> · | ||
| 469 | <a href="reference.html">reference</a> | ||
| 470 | </p> | ||
| 471 | <p> | ||
| 472 | <small> | ||
| 473 | Last modified by Diego Nehab on <br> | ||
| 474 | Thu Apr 20 00:25:54 EDT 2006 | ||
| 475 | </small> | ||
| 476 | </p> | ||
| 477 | </center> | ||
| 478 | </div> | ||
| 479 | |||
| 480 | </body> | ||
| 481 | </html> | ||
diff --git a/docs/tcp.html b/docs/tcp.html new file mode 100644 index 0000000..9cc173e --- /dev/null +++ b/docs/tcp.html | |||
| @@ -0,0 +1,732 @@ | |||
| 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: The TCP/IP support"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, Socket, TCP, Library, Network, Support"> | ||
| 8 | <title>LuaSocket: TCP/IP support</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> · | ||
| 28 | <a href="index.html#download">download</a> · | ||
| 29 | <a href="installation.html">installation</a> · | ||
| 30 | <a href="introduction.html">introduction</a> · | ||
| 31 | <a href="reference.html">reference</a> | ||
| 32 | </p> | ||
| 33 | </center> | ||
| 34 | <hr> | ||
| 35 | </div> | ||
| 36 | |||
| 37 | <!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 38 | |||
| 39 | <h2 id="tcp">TCP</h2> | ||
| 40 | |||
| 41 | <!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 42 | |||
| 43 | <p class="name" id="accept"> | ||
| 44 | server:<b>accept()</b> | ||
| 45 | </p> | ||
| 46 | |||
| 47 | <p class="description"> | ||
| 48 | Waits for a remote connection on the server | ||
| 49 | object and returns a client object representing that connection. | ||
| 50 | </p> | ||
| 51 | |||
| 52 | <p class="return"> | ||
| 53 | If a connection is successfully initiated, a client object is returned. | ||
| 54 | If a timeout condition is met, the method returns <b><tt>nil</tt></b> | ||
| 55 | followed by the error string '<tt>timeout</tt>'. Other errors are | ||
| 56 | reported by <b><tt>nil</tt></b> followed by a message describing the error. | ||
| 57 | </p> | ||
| 58 | |||
| 59 | <p class="note"> | ||
| 60 | Note: calling <a href="socket.html#select"><tt>socket.select</tt></a> | ||
| 61 | with a server object in | ||
| 62 | the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does | ||
| 63 | <em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a | ||
| 64 | href="#settimeout"><tt>settimeout</tt></a> method or <tt>accept</tt> | ||
| 65 | might block until <em>another</em> client shows up. | ||
| 66 | </p> | ||
| 67 | |||
| 68 | <!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 69 | |||
| 70 | <p class="name" id="bind"> | ||
| 71 | master:<b>bind(</b>address, port<b>)</b> | ||
| 72 | </p> | ||
| 73 | |||
| 74 | <p class="description"> | ||
| 75 | Binds a master object to <tt>address</tt> and <tt>port</tt> on the | ||
| 76 | local host. | ||
| 77 | </p> | ||
| 78 | |||
| 79 | <p class="parameters"> | ||
| 80 | <tt>Address</tt> can be an IP address or a host name. | ||
| 81 | <tt>Port</tt> must be an integer number in the range [0..64K). | ||
| 82 | If <tt>address</tt> | ||
| 83 | is '<tt>*</tt>', the system binds to all local interfaces | ||
| 84 | using the <tt>INADDR_ANY</tt> constant or | ||
| 85 | <tt>IN6ADDR_ANY_INIT</tt>, according to the family. | ||
| 86 | If <tt>port</tt> is 0, the system automatically | ||
| 87 | chooses an ephemeral port. | ||
| 88 | </p> | ||
| 89 | |||
| 90 | <p class="return"> | ||
| 91 | In case of success, the method returns 1. In case of error, the | ||
| 92 | method returns <b><tt>nil</tt></b> followed by an error message. | ||
| 93 | </p> | ||
| 94 | |||
| 95 | <p class="note"> | ||
| 96 | Note: The function <a href="socket.html#bind"><tt>socket.bind</tt></a> | ||
| 97 | is available and is a shortcut for the creation of server sockets. | ||
| 98 | </p> | ||
| 99 | |||
| 100 | <!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 101 | |||
| 102 | <p class="name" id="close"> | ||
| 103 | master:<b>close()</b><br> | ||
| 104 | client:<b>close()</b><br> | ||
| 105 | server:<b>close()</b> | ||
| 106 | </p> | ||
| 107 | |||
| 108 | <p class="description"> | ||
| 109 | Closes a TCP object. The internal socket used by the object is closed | ||
| 110 | and the local address to which the object was | ||
| 111 | bound is made available to other applications. No further operations | ||
| 112 | (except for further calls to the <tt>close</tt> method) are allowed on | ||
| 113 | a closed socket. | ||
| 114 | </p> | ||
| 115 | |||
| 116 | <p class="note"> | ||
| 117 | Note: It is important to close all used sockets once they are not | ||
| 118 | needed, since, in many systems, each socket uses a file descriptor, | ||
| 119 | which are limited system resources. Garbage-collected objects are | ||
| 120 | automatically closed before destruction, though. | ||
| 121 | </p> | ||
| 122 | |||
| 123 | <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 124 | |||
| 125 | <p class="name" id="connect"> | ||
| 126 | master:<b>connect(</b>address, port<b>)</b> | ||
| 127 | </p> | ||
| 128 | |||
| 129 | <p class="description"> | ||
| 130 | Attempts to connect a master object to a remote host, transforming it into a | ||
| 131 | client object. | ||
| 132 | Client objects support methods | ||
| 133 | <a href="#send"><tt>send</tt></a>, | ||
| 134 | <a href="#receive"><tt>receive</tt></a>, | ||
| 135 | <a href="#getsockname"><tt>getsockname</tt></a>, | ||
| 136 | <a href="#getpeername"><tt>getpeername</tt></a>, | ||
| 137 | <a href="#settimeout"><tt>settimeout</tt></a>, | ||
| 138 | and <a href="#close"><tt>close</tt></a>. | ||
| 139 | </p> | ||
| 140 | |||
| 141 | <p class="parameters"> | ||
| 142 | <tt>Address</tt> can be an IP address or a host name. | ||
| 143 | <tt>Port</tt> must be an integer number in the range [1..64K). | ||
| 144 | </p> | ||
| 145 | |||
| 146 | <p class="return"> | ||
| 147 | In case of error, the method returns <b><tt>nil</tt></b> followed by a string | ||
| 148 | describing the error. In case of success, the method returns 1. | ||
| 149 | </p> | ||
| 150 | |||
| 151 | <p class="note"> | ||
| 152 | Note: The function <a href="socket.html#connect"><tt>socket.connect</tt></a> | ||
| 153 | is available and is a shortcut for the creation of client sockets. | ||
| 154 | </p> | ||
| 155 | |||
| 156 | <p class="note"> | ||
| 157 | Note: Starting with LuaSocket 2.0, | ||
| 158 | the <a href="#settimeout"><tt>settimeout</tt></a> | ||
| 159 | method affects the behavior of <tt>connect</tt>, causing it to return | ||
| 160 | with an error in case of a timeout. If that happens, you can still call <a | ||
| 161 | href="socket.html#select"><tt>socket.select</tt></a> with the socket in the | ||
| 162 | <tt>sendt</tt> table. The socket will be writable when the connection is | ||
| 163 | established. | ||
| 164 | </p> | ||
| 165 | |||
| 166 | <p class="note"> | ||
| 167 | Note: Starting with LuaSocket 3.0, the host name resolution | ||
| 168 | depends on whether the socket was created by | ||
| 169 | <a href="#socket.tcp"><tt>socket.tcp</tt></a>, | ||
| 170 | <a href="#socket.tcp4"><tt>socket.tcp4</tt></a> or | ||
| 171 | <a href="#socket.tcp6"><tt>socket.tcp6</tt></a>. Addresses from | ||
| 172 | the appropriate family (or both) are tried in the order | ||
| 173 | returned by the resolver until the | ||
| 174 | first success or until the last failure. If the timeout was | ||
| 175 | set to zero, only the first address is tried. | ||
| 176 | </p> | ||
| 177 | |||
| 178 | <!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 179 | |||
| 180 | <p class="name" id="dirty"> | ||
| 181 | master:<b>dirty()</b><br> | ||
| 182 | client:<b>dirty()</b><br> | ||
| 183 | server:<b>dirty()</b> | ||
| 184 | </p> | ||
| 185 | |||
| 186 | <p class="description"> | ||
| 187 | Check the read buffer status. | ||
| 188 | </p> | ||
| 189 | |||
| 190 | <p class="return"> | ||
| 191 | Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise. | ||
| 192 | </p> | ||
| 193 | |||
| 194 | <p class="note"> | ||
| 195 | Note: <b>This is an internal method, use at your own risk.</b> | ||
| 196 | </p> | ||
| 197 | |||
| 198 | |||
| 199 | <!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 200 | |||
| 201 | <p class="name" id="getfd"> | ||
| 202 | master:<b>getfd()</b><br> | ||
| 203 | client:<b>getfd()</b><br> | ||
| 204 | server:<b>getfd()</b> | ||
| 205 | </p> | ||
| 206 | |||
| 207 | <p class="description"> | ||
| 208 | Returns the underling socket descriptor or handle associated to the object. | ||
| 209 | </p> | ||
| 210 | |||
| 211 | <p class="return"> | ||
| 212 | The descriptor or handle. In case the object has been closed, the return value | ||
| 213 | will be -1. For an invalid socket it will be <a href="socket.html#socketinvalid"> | ||
| 214 | <tt>_SOCKETINVALID</tt></a>. | ||
| 215 | </p> | ||
| 216 | |||
| 217 | <p class="note"> | ||
| 218 | Note: <b>This is an internal method. Unlikely to be | ||
| 219 | portable. Use at your own risk. </b> | ||
| 220 | </p> | ||
| 221 | |||
| 222 | |||
| 223 | <!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 224 | |||
| 225 | <p class="name" id="getoption"> | ||
| 226 | client:<b>getoption(option)</b><br> | ||
| 227 | server:<b>getoption(option)</b> | ||
| 228 | </p> | ||
| 229 | |||
| 230 | <p class="description"> | ||
| 231 | Gets options for the TCP object. | ||
| 232 | See <a href="#setoption"><tt>setoption</tt></a> for description of the | ||
| 233 | option names and values. | ||
| 234 | </p> | ||
| 235 | |||
| 236 | <p class="parameters"> | ||
| 237 | <tt>Option</tt> is a string with the option name.</p> | ||
| 238 | <ul> | ||
| 239 | <li> '<tt>keepalive</tt>'</li> | ||
| 240 | <li> '<tt>linger</tt>'</li> | ||
| 241 | <li> '<tt>reuseaddr</tt>'</li> | ||
| 242 | <li> '<tt>tcp-nodelay</tt>'</li> | ||
| 243 | </ul> | ||
| 244 | |||
| 245 | <p class="return"> | ||
| 246 | The method returns the option <tt>value</tt> in case of success, or | ||
| 247 | <b><tt>nil</tt></b> followed by an error message otherwise. | ||
| 248 | </p> | ||
| 249 | |||
| 250 | |||
| 251 | <!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 252 | |||
| 253 | <p class="name" id="getpeername"> | ||
| 254 | client:<b>getpeername()</b> | ||
| 255 | </p> | ||
| 256 | |||
| 257 | <p class="description"> | ||
| 258 | Returns information about the remote side of a connected client object. | ||
| 259 | </p> | ||
| 260 | |||
| 261 | <p class="return"> | ||
| 262 | Returns a string with the IP address of the peer, the | ||
| 263 | port number that peer is using for the connection, | ||
| 264 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). | ||
| 265 | In case of error, the method returns <b><tt>nil</tt></b>. | ||
| 266 | </p> | ||
| 267 | |||
| 268 | <p class="note"> | ||
| 269 | Note: It makes no sense to call this method on server objects. | ||
| 270 | </p> | ||
| 271 | |||
| 272 | <!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 273 | |||
| 274 | <p class="name" id="getsockname"> | ||
| 275 | master:<b>getsockname()</b><br> | ||
| 276 | client:<b>getsockname()</b><br> | ||
| 277 | server:<b>getsockname()</b> | ||
| 278 | </p> | ||
| 279 | |||
| 280 | <p class="description"> | ||
| 281 | Returns the local address information associated to the object. | ||
| 282 | </p> | ||
| 283 | |||
| 284 | <p class="return"> | ||
| 285 | The method returns a string with local IP address, a number with | ||
| 286 | the local port, | ||
| 287 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). | ||
| 288 | In case of error, the method returns <b><tt>nil</tt></b>. | ||
| 289 | </p> | ||
| 290 | |||
| 291 | <!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 292 | |||
| 293 | <p class="name" id="getstats"> | ||
| 294 | master:<b>getstats()</b><br> | ||
| 295 | client:<b>getstats()</b><br> | ||
| 296 | server:<b>getstats()</b><br> | ||
| 297 | </p> | ||
| 298 | |||
| 299 | <p class="description"> | ||
| 300 | Returns accounting information on the socket, useful for throttling | ||
| 301 | of bandwidth. | ||
| 302 | </p> | ||
| 303 | |||
| 304 | <p class="return"> | ||
| 305 | The method returns the number of bytes received, the number of bytes sent, | ||
| 306 | and the age of the socket object in seconds. | ||
| 307 | </p> | ||
| 308 | |||
| 309 | <!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 310 | |||
| 311 | <p class="name" id="gettimeout"> | ||
| 312 | master:<b>gettimeout()</b><br> | ||
| 313 | client:<b>gettimeout()</b><br> | ||
| 314 | server:<b>gettimeout()</b> | ||
| 315 | </p> | ||
| 316 | |||
| 317 | <p class="description"> | ||
| 318 | Returns the current block timeout followed by the curent | ||
| 319 | total timeout. | ||
| 320 | </p> | ||
| 321 | |||
| 322 | |||
| 323 | <!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 324 | |||
| 325 | <p class="name" id="listen"> | ||
| 326 | master:<b>listen(</b>backlog<b>)</b> | ||
| 327 | </p> | ||
| 328 | |||
| 329 | <p class="description"> | ||
| 330 | Specifies the socket is willing to receive connections, transforming the | ||
| 331 | object into a server object. Server objects support the | ||
| 332 | <a href="#accept"><tt>accept</tt></a>, | ||
| 333 | <a href="#getsockname"><tt>getsockname</tt></a>, | ||
| 334 | <a href="#setoption"><tt>setoption</tt></a>, | ||
| 335 | <a href="#settimeout"><tt>settimeout</tt></a>, | ||
| 336 | and <a href="#close"><tt>close</tt></a> methods. | ||
| 337 | </p> | ||
| 338 | |||
| 339 | <p class="parameters"> | ||
| 340 | The parameter <tt>backlog</tt> specifies the number of client | ||
| 341 | connections that can | ||
| 342 | be queued waiting for service. If the queue is full and another client | ||
| 343 | attempts connection, the connection is refused. | ||
| 344 | </p> | ||
| 345 | |||
| 346 | <p class="return"> | ||
| 347 | In case of success, the method returns 1. In case of error, the | ||
| 348 | method returns <b><tt>nil</tt></b> followed by an error message. | ||
| 349 | </p> | ||
| 350 | |||
| 351 | <!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 352 | |||
| 353 | <p class="name" id="receive"> | ||
| 354 | client:<b>receive(</b>[pattern [, prefix]]<b>)</b> | ||
| 355 | </p> | ||
| 356 | |||
| 357 | <p class="description"> | ||
| 358 | Reads data from a client object, according to the specified <em>read | ||
| 359 | pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. | ||
| 360 | </p> | ||
| 361 | |||
| 362 | <p class="parameters"> | ||
| 363 | <tt>Pattern</tt> can be any of the following: | ||
| 364 | </p> | ||
| 365 | |||
| 366 | <ul> | ||
| 367 | <li> '<tt>*a</tt>': reads from the socket until the connection is | ||
| 368 | closed. No end-of-line translation is performed;</li> | ||
| 369 | <li> '<tt>*l</tt>': reads a line of text from the socket. The line is | ||
| 370 | terminated by a LF character (ASCII 10), optionally preceded by a | ||
| 371 | CR character (ASCII 13). The CR and LF characters are not included in | ||
| 372 | the returned line. In fact, <em>all</em> CR characters are | ||
| 373 | ignored by the pattern. This is the default pattern;</li> | ||
| 374 | <li> <tt>number</tt>: causes the method to read a specified <tt>number</tt> | ||
| 375 | of bytes from the socket.</li> | ||
| 376 | </ul> | ||
| 377 | |||
| 378 | <p class="parameters"> | ||
| 379 | <tt>Prefix</tt> is an optional string to be concatenated to the beginning | ||
| 380 | of any received data before return. | ||
| 381 | </p> | ||
| 382 | |||
| 383 | <p class="return"> | ||
| 384 | If successful, the method returns the received pattern. In case of error, | ||
| 385 | the method returns <tt><b>nil</b></tt> followed by an error | ||
| 386 | message, followed by a (possibly empty) string containing | ||
| 387 | the partial that was received. The error message can be | ||
| 388 | the string '<tt>closed</tt>' in case the connection was | ||
| 389 | closed before the transmission was completed or the string | ||
| 390 | '<tt>timeout</tt>' in case there was a timeout during the operation. | ||
| 391 | </p> | ||
| 392 | |||
| 393 | <p class="note"> | ||
| 394 | <b>Important note</b>: This function was changed <em>severely</em>. It used | ||
| 395 | to support multiple patterns (but I have never seen this feature used) and | ||
| 396 | now it doesn't anymore. Partial results used to be returned in the same | ||
| 397 | way as successful results. This last feature violated the idea that all | ||
| 398 | functions should return <tt><b>nil</b></tt> on error. Thus it was changed | ||
| 399 | too. | ||
| 400 | </p> | ||
| 401 | |||
| 402 | <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 403 | |||
| 404 | <p class="name" id="send"> | ||
| 405 | client:<b>send(</b>data [, i [, j]]<b>)</b> | ||
| 406 | </p> | ||
| 407 | |||
| 408 | <p class="description"> | ||
| 409 | Sends <tt>data</tt> through client object. | ||
| 410 | </p> | ||
| 411 | |||
| 412 | <p class="parameters"> | ||
| 413 | <tt>Data</tt> is the string to be sent. The optional arguments | ||
| 414 | <tt>i</tt> and <tt>j</tt> work exactly like the standard | ||
| 415 | <tt>string.sub</tt> Lua function to allow the selection of a | ||
| 416 | substring to be sent. | ||
| 417 | </p> | ||
| 418 | |||
| 419 | <p class="return"> | ||
| 420 | If successful, the method returns the index of the last byte | ||
| 421 | within <tt>[i, j]</tt> that has been sent. Notice that, if | ||
| 422 | <tt>i</tt> is 1 or absent, this is effectively the total | ||
| 423 | number of bytes sent. In case of error, the method returns | ||
| 424 | <b><tt>nil</tt></b>, followed by an error message, followed | ||
| 425 | by the index of the last byte within <tt>[i, j]</tt> that | ||
| 426 | has been sent. You might want to try again from the byte | ||
| 427 | following that. The error message can be '<tt>closed</tt>' | ||
| 428 | in case the connection was closed before the transmission | ||
| 429 | was completed or the string '<tt>timeout</tt>' in case | ||
| 430 | there was a timeout during the operation. | ||
| 431 | </p> | ||
| 432 | |||
| 433 | <p class="note"> | ||
| 434 | Note: Output is <em>not</em> buffered. For small strings, | ||
| 435 | it is always better to concatenate them in Lua | ||
| 436 | (with the '<tt>..</tt>' operator) and send the result in one call | ||
| 437 | instead of calling the method several times. | ||
| 438 | </p> | ||
| 439 | |||
| 440 | <!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 441 | |||
| 442 | <p class="name" id="setoption"> | ||
| 443 | client:<b>setoption(</b>option [, value]<b>)</b><br> | ||
| 444 | server:<b>setoption(</b>option [, value]<b>)</b> | ||
| 445 | </p> | ||
| 446 | |||
| 447 | <p class="description"> | ||
| 448 | Sets options for the TCP object. Options are only needed by low-level or | ||
| 449 | time-critical applications. You should only modify an option if you | ||
| 450 | are sure you need it. | ||
| 451 | </p> | ||
| 452 | |||
| 453 | <p class="parameters"> | ||
| 454 | <tt>Option</tt> is a string with the option name, and <tt>value</tt> | ||
| 455 | depends on the option being set:</p> | ||
| 456 | |||
| 457 | <ul> | ||
| 458 | |||
| 459 | <li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables | ||
| 460 | the periodic transmission of messages on a connected socket. Should the | ||
| 461 | connected party fail to respond to these messages, the connection is | ||
| 462 | considered broken and processes using the socket are notified;</li> | ||
| 463 | |||
| 464 | <li> '<tt>linger</tt>': Controls the action taken when unsent data are | ||
| 465 | queued on a socket and a close is performed. The value is a table with a | ||
| 466 | boolean entry '<tt>on</tt>' and a numeric entry for the time interval | ||
| 467 | '<tt>timeout</tt>' in seconds. If the '<tt>on</tt>' field is set to | ||
| 468 | <tt>true</tt>, the system will block the process on the close attempt until | ||
| 469 | it is able to transmit the data or until '<tt>timeout</tt>' has passed. If | ||
| 470 | '<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will | ||
| 471 | process the close in a manner that allows the process to continue as | ||
| 472 | quickly as possible. I do not advise you to set this to anything other than | ||
| 473 | zero;</li> | ||
| 474 | |||
| 475 | <li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules | ||
| 476 | used in validating addresses supplied in a call to | ||
| 477 | <a href="#bind"><tt>bind</tt></a> should allow reuse of local addresses;</li> | ||
| 478 | |||
| 479 | <li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> | ||
| 480 | disables the Nagle's algorithm for the connection;</li> | ||
| 481 | |||
| 482 | <li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!!</li> | ||
| 483 | |||
| 484 | <li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!!</li> | ||
| 485 | |||
| 486 | <li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!!</li> | ||
| 487 | |||
| 488 | <li> '<tt>ipv6-v6only</tt>': | ||
| 489 | Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to | ||
| 490 | sending and receiving only IPv6 packets.</li> | ||
| 491 | </ul> | ||
| 492 | |||
| 493 | <p class="return"> | ||
| 494 | The method returns 1 in case of success, or <b><tt>nil</tt></b> | ||
| 495 | followed by an error message otherwise. | ||
| 496 | </p> | ||
| 497 | |||
| 498 | <p class="note"> | ||
| 499 | Note: The descriptions above come from the man pages. | ||
| 500 | </p> | ||
| 501 | |||
| 502 | <!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 503 | |||
| 504 | <p class="name" id="setstats"> | ||
| 505 | master:<b>setstats(</b>received, sent, age<b>)</b><br> | ||
| 506 | client:<b>setstats(</b>received, sent, age<b>)</b><br> | ||
| 507 | server:<b>setstats(</b>received, sent, age<b>)</b><br> | ||
| 508 | </p> | ||
| 509 | |||
| 510 | <p class="description"> | ||
| 511 | Resets accounting information on the socket, useful for throttling | ||
| 512 | of bandwidth. | ||
| 513 | </p> | ||
| 514 | |||
| 515 | <p class="parameters"> | ||
| 516 | <tt>Received</tt> is a number with the new number of bytes received. | ||
| 517 | <tt>Sent</tt> is a number with the new number of bytes sent. | ||
| 518 | <tt>Age</tt> is the new age in seconds. | ||
| 519 | </p> | ||
| 520 | |||
| 521 | <p class="return"> | ||
| 522 | The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise. | ||
| 523 | </p> | ||
| 524 | |||
| 525 | <!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 526 | |||
| 527 | <p class="name" id="settimeout"> | ||
| 528 | master:<b>settimeout(</b>value [, mode]<b>)</b><br> | ||
| 529 | client:<b>settimeout(</b>value [, mode]<b>)</b><br> | ||
| 530 | server:<b>settimeout(</b>value [, mode]<b>)</b> | ||
| 531 | </p> | ||
| 532 | |||
| 533 | <p class="description"> | ||
| 534 | Changes the timeout values for the object. By default, | ||
| 535 | all I/O operations are blocking. That is, any call to the methods | ||
| 536 | <a href="#send"><tt>send</tt></a>, | ||
| 537 | <a href="#receive"><tt>receive</tt></a>, and | ||
| 538 | <a href="#accept"><tt>accept</tt></a> | ||
| 539 | will block indefinitely, until the operation completes. The | ||
| 540 | <tt>settimeout</tt> method defines a limit on the amount of time the | ||
| 541 | I/O methods can block. When a timeout is set and the specified amount of | ||
| 542 | time has elapsed, the affected methods give up and fail with an error code. | ||
| 543 | </p> | ||
| 544 | |||
| 545 | <p class="parameters"> | ||
| 546 | The amount of time to wait is specified as the | ||
| 547 | <tt>value</tt> parameter, in seconds. There are two timeout modes and | ||
| 548 | both can be used together for fine tuning: | ||
| 549 | </p> | ||
| 550 | |||
| 551 | <ul> | ||
| 552 | <li> '<tt>b</tt>': <em>block</em> timeout. Specifies the upper limit on | ||
| 553 | the amount of time LuaSocket can be blocked by the operating system | ||
| 554 | while waiting for completion of any single I/O operation. This is the | ||
| 555 | default mode;</li> | ||
| 556 | |||
| 557 | <li> '<tt>t</tt>': <em>total</em> timeout. Specifies the upper limit on | ||
| 558 | the amount of time LuaSocket can block a Lua script before returning from | ||
| 559 | a call.</li> | ||
| 560 | </ul> | ||
| 561 | |||
| 562 | <p class="parameters"> | ||
| 563 | The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block | ||
| 564 | indefinitely. Negative timeout values have the same effect. | ||
| 565 | </p> | ||
| 566 | |||
| 567 | <p class="note"> | ||
| 568 | Note: although timeout values have millisecond precision in LuaSocket, | ||
| 569 | large blocks can cause I/O functions not to respect timeout values due | ||
| 570 | to the time the library takes to transfer blocks to and from the OS | ||
| 571 | and to and from the Lua interpreter. Also, function that accept host names | ||
| 572 | and perform automatic name resolution might be blocked by the resolver for | ||
| 573 | longer than the specified timeout value. | ||
| 574 | </p> | ||
| 575 | |||
| 576 | <p class="note"> | ||
| 577 | Note: The old <tt>timeout</tt> method is deprecated. The name has been | ||
| 578 | changed for sake of uniformity, since all other method names already | ||
| 579 | contained verbs making their imperative nature obvious. | ||
| 580 | </p> | ||
| 581 | |||
| 582 | <!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 583 | |||
| 584 | <p class="name" id="shutdown"> | ||
| 585 | client:<b>shutdown(</b>mode<b>)</b><br> | ||
| 586 | </p> | ||
| 587 | |||
| 588 | <p class="description"> | ||
| 589 | Shuts down part of a full-duplex connection. | ||
| 590 | </p> | ||
| 591 | |||
| 592 | <p class="parameters"> | ||
| 593 | Mode tells which way of the connection should be shut down and can | ||
| 594 | take the value: | ||
| 595 | <ul> | ||
| 596 | <li>"<tt>both</tt>": disallow further sends and receives on the object. | ||
| 597 | This is the default mode;</li> | ||
| 598 | <li>"<tt>send</tt>": disallow further sends on the object;</li> | ||
| 599 | <li>"<tt>receive</tt>": disallow further receives on the object.</li> | ||
| 600 | </ul> | ||
| 601 | </p> | ||
| 602 | |||
| 603 | <p class="return"> | ||
| 604 | This function returns 1. | ||
| 605 | </p> | ||
| 606 | |||
| 607 | <!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 608 | |||
| 609 | <p class="name" id="setfd"> | ||
| 610 | master:<b>setfd(</b>fd<b>)</b><br> | ||
| 611 | client:<b>setfd(</b>fd<b>)</b><br> | ||
| 612 | server:<b>setfd(</b>fd<b>)</b> | ||
| 613 | </p> | ||
| 614 | |||
| 615 | <p class="description"> | ||
| 616 | Sets the underling socket descriptor or handle associated to the object. The current one | ||
| 617 | is simply replaced, not closed, and no other change to the object state is made. | ||
| 618 | To set it as invalid use <a href="socket.html#socketinvalid"><tt>_SOCKETINVALID</tt></a>. | ||
| 619 | </p> | ||
| 620 | |||
| 621 | <p class="return"> | ||
| 622 | No return value. | ||
| 623 | </p> | ||
| 624 | |||
| 625 | <p class="note"> | ||
| 626 | Note: <b>This is an internal method. Unlikely to be | ||
| 627 | portable. Use at your own risk. </b> | ||
| 628 | </p> | ||
| 629 | |||
| 630 | <!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 631 | |||
| 632 | <p class="name" id="socket.tcp"> | ||
| 633 | socket.<b>tcp()</b> | ||
| 634 | </p> | ||
| 635 | |||
| 636 | <p class="description"> | ||
| 637 | Creates and returns an TCP master object. A master object can | ||
| 638 | be transformed into a server object with the method | ||
| 639 | <a href="#listen"><tt>listen</tt></a> (after a call to <a | ||
| 640 | href="#bind"><tt>bind</tt></a>) or into a client object with | ||
| 641 | the method <a href="#connect"><tt>connect</tt></a>. The only other | ||
| 642 | method supported by a master object is the | ||
| 643 | <a href="#close"><tt>close</tt></a> method.</p> | ||
| 644 | |||
| 645 | <p class="return"> | ||
| 646 | In case of success, a new master object is returned. In case of error, | ||
| 647 | <b><tt>nil</tt></b> is returned, followed by an error message. | ||
| 648 | </p> | ||
| 649 | |||
| 650 | <p class="note"> | ||
| 651 | Note: The choice between IPv4 and IPv6 happens during a call to | ||
| 652 | <a href="#bind"><tt>bind</tt></a> or <a | ||
| 653 | href="#bind"><tt>connect</tt></a>, depending on the address | ||
| 654 | family obtained from the resolver. | ||
| 655 | </p> | ||
| 656 | |||
| 657 | <p class="note"> | ||
| 658 | Note: Before the choice between IPv4 and IPv6 happens, | ||
| 659 | the internal socket object is invalid and therefore <a | ||
| 660 | href="#setoption"><tt>setoption</tt></a> will fail. | ||
| 661 | </p> | ||
| 662 | |||
| 663 | <!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 664 | |||
| 665 | <p class="name" id="socket.tcp4"> | ||
| 666 | socket.<b>tcp4()</b> | ||
| 667 | </p> | ||
| 668 | |||
| 669 | <p class="description"> | ||
| 670 | Creates and returns an IPv4 TCP master object. A master object can | ||
| 671 | be transformed into a server object with the method | ||
| 672 | <a href="#listen"><tt>listen</tt></a> (after a call to <a | ||
| 673 | href="#bind"><tt>bind</tt></a>) or into a client object with | ||
| 674 | the method <a href="#connect"><tt>connect</tt></a>. The only other | ||
| 675 | method supported by a master object is the | ||
| 676 | <a href="#close"><tt>close</tt></a> method.</p> | ||
| 677 | |||
| 678 | <p class="return"> | ||
| 679 | In case of success, a new master object is returned. In case of error, | ||
| 680 | <b><tt>nil</tt></b> is returned, followed by an error message. | ||
| 681 | </p> | ||
| 682 | |||
| 683 | <!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 684 | |||
| 685 | <p class="name" id="socket.tcp6"> | ||
| 686 | socket.<b>tcp6()</b> | ||
| 687 | </p> | ||
| 688 | |||
| 689 | <p class="description"> | ||
| 690 | Creates and returns an IPv6 TCP master object. A master object can | ||
| 691 | be transformed into a server object with the method | ||
| 692 | <a href="#listen"><tt>listen</tt></a> (after a call to <a | ||
| 693 | href="#bind"><tt>bind</tt></a>) or into a client object with | ||
| 694 | the method <a href="#connect"><tt>connect</tt></a>. The only other | ||
| 695 | method supported by a master object is the | ||
| 696 | <a href="#close"><tt>close</tt></a> method.</p> | ||
| 697 | |||
| 698 | <p class="return"> | ||
| 699 | In case of success, a new master object is returned. In case of error, | ||
| 700 | <b><tt>nil</tt></b> is returned, followed by an error message. | ||
| 701 | </p> | ||
| 702 | |||
| 703 | <p class="note"> | ||
| 704 | Note: The TCP object returned will have the option | ||
| 705 | "<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. | ||
| 706 | </p> | ||
| 707 | |||
| 708 | |||
| 709 | |||
| 710 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 711 | |||
| 712 | <div class="footer"> | ||
| 713 | <hr> | ||
| 714 | <center> | ||
| 715 | <p class="bar"> | ||
| 716 | <a href="index.html">home</a> · | ||
| 717 | <a href="index.html#down">download</a> · | ||
| 718 | <a href="installation.html">installation</a> · | ||
| 719 | <a href="introduction.html">introduction</a> · | ||
| 720 | <a href="reference.html">reference</a> | ||
| 721 | </p> | ||
| 722 | <p> | ||
| 723 | <small> | ||
| 724 | Last modified by Diego Nehab on <br> | ||
| 725 | Thu Apr 20 00:25:57 EDT 2006 | ||
| 726 | </small> | ||
| 727 | </p> | ||
| 728 | </center> | ||
| 729 | </div> | ||
| 730 | |||
| 731 | </body> | ||
| 732 | </html> | ||
diff --git a/docs/udp.html b/docs/udp.html new file mode 100644 index 0000000..db711cb --- /dev/null +++ b/docs/udp.html | |||
| @@ -0,0 +1,596 @@ | |||
| 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: The UDP support"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, Socket, UDP, Library, Network, Support"> | ||
| 8 | <title>LuaSocket: UDP support</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> · | ||
| 28 | <a href="index.html#download">download</a> · | ||
| 29 | <a href="installation.html">installation</a> · | ||
| 30 | <a href="introduction.html">introduction</a> · | ||
| 31 | <a href="reference.html">reference</a> | ||
| 32 | </p> | ||
| 33 | </center> | ||
| 34 | <hr> | ||
| 35 | </div> | ||
| 36 | |||
| 37 | |||
| 38 | <!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 39 | |||
| 40 | <h2 id="udp">UDP</h2> | ||
| 41 | |||
| 42 | <!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 43 | |||
| 44 | <p class="name" id="close"> | ||
| 45 | connected:<b>close()</b><br> | ||
| 46 | unconnected:<b>close()</b> | ||
| 47 | </p> | ||
| 48 | |||
| 49 | <p class="description"> | ||
| 50 | Closes a UDP object. The internal socket | ||
| 51 | used by the object is closed and the local address to which the | ||
| 52 | object was bound is made available to other applications. No | ||
| 53 | further operations (except for further calls to the <tt>close</tt> | ||
| 54 | method) are allowed on a closed socket. | ||
| 55 | </p> | ||
| 56 | |||
| 57 | <p class="note"> | ||
| 58 | Note: It is important to close all used sockets | ||
| 59 | once they are not needed, since, in many systems, each socket uses | ||
| 60 | a file descriptor, which are limited system resources. | ||
| 61 | Garbage-collected objects are automatically closed before | ||
| 62 | destruction, though. | ||
| 63 | </p> | ||
| 64 | |||
| 65 | <!-- getoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 66 | |||
| 67 | <p class="name" id="getoption"> | ||
| 68 | connected:<b>getoption()</b><br> | ||
| 69 | unconnected:<b>getoption()</b> | ||
| 70 | </p> | ||
| 71 | |||
| 72 | <p class="description"> | ||
| 73 | Gets an option value from the UDP object. | ||
| 74 | See <a href="#setoption"><tt>setoption</tt></a> for | ||
| 75 | description of the option names and values. | ||
| 76 | </p> | ||
| 77 | |||
| 78 | <p class="parameters"><tt>Option</tt> is a string with the option name. | ||
| 79 | <ul> | ||
| 80 | <li> '<tt>dontroute</tt>'</li> | ||
| 81 | <li> '<tt>broadcast</tt>'</li> | ||
| 82 | <li> '<tt>reuseaddr</tt>'</li> | ||
| 83 | <li> '<tt>reuseport</tt>'</li> | ||
| 84 | <li> '<tt>ip-multicast-loop</tt>'</li> | ||
| 85 | <li> '<tt>ipv6-v6only</tt>'</li> | ||
| 86 | <li> '<tt>ip-multicast-if</tt>'</li> | ||
| 87 | <li> '<tt>ip-multicast-ttl</tt>'</li> | ||
| 88 | <li> '<tt>ip-add-membership</tt>'</li> | ||
| 89 | <li> '<tt>ip-drop-membership</tt>'</li> | ||
| 90 | </ul> | ||
| 91 | </p> | ||
| 92 | |||
| 93 | <p class="return"> | ||
| 94 | The method returns the option <tt>value</tt> in case of | ||
| 95 | success, or | ||
| 96 | <b><tt>nil</tt></b> followed by an error message otherwise. | ||
| 97 | </p> | ||
| 98 | |||
| 99 | <!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 100 | |||
| 101 | <p class="name" id="getpeername"> | ||
| 102 | connected:<b>getpeername()</b> | ||
| 103 | </p> | ||
| 104 | |||
| 105 | <p class="description"> | ||
| 106 | Retrieves information about the peer | ||
| 107 | associated with a connected UDP object. | ||
| 108 | </p> | ||
| 109 | |||
| 110 | |||
| 111 | <p class="return"> | ||
| 112 | Returns a string with the IP address of the peer, the | ||
| 113 | port number that peer is using for the connection, | ||
| 114 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). | ||
| 115 | In case of error, the method returns <b><tt>nil</tt></b>. | ||
| 116 | </p> | ||
| 117 | |||
| 118 | <p class="note"> | ||
| 119 | Note: It makes no sense to call this method on unconnected objects. | ||
| 120 | </p> | ||
| 121 | |||
| 122 | <!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 123 | |||
| 124 | <p class="name" id="getsockname"> | ||
| 125 | connected:<b>getsockname()</b><br> | ||
| 126 | unconnected:<b>getsockname()</b> | ||
| 127 | </p> | ||
| 128 | |||
| 129 | <p class="description"> | ||
| 130 | Returns the local address information associated to the object. | ||
| 131 | </p> | ||
| 132 | |||
| 133 | |||
| 134 | <p class="return"> | ||
| 135 | The method returns a string with local IP address, a number with | ||
| 136 | the local port, | ||
| 137 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). | ||
| 138 | In case of error, the method returns <b><tt>nil</tt></b>. | ||
| 139 | </p> | ||
| 140 | |||
| 141 | <p class="note"> | ||
| 142 | Note: UDP sockets are not bound to any address | ||
| 143 | until the <a href="#setsockname"><tt>setsockname</tt></a> or the | ||
| 144 | <a href="#sendto"><tt>sendto</tt></a> method is called for the | ||
| 145 | first time (in which case it is bound to an ephemeral port and the | ||
| 146 | wild-card address). | ||
| 147 | </p> | ||
| 148 | |||
| 149 | <!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 150 | |||
| 151 | <p class="name" id="gettimeout"> | ||
| 152 | connected:<b>settimeout(</b>value<b>)</b><br> | ||
| 153 | unconnected:<b>settimeout(</b>value<b>)</b> | ||
| 154 | </p> | ||
| 155 | |||
| 156 | <p class="description"> | ||
| 157 | Returns the current timeout value. | ||
| 158 | </p> | ||
| 159 | |||
| 160 | |||
| 161 | <!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 162 | |||
| 163 | <p class="name" id="receive"> | ||
| 164 | connected:<b>receive(</b>[size]<b>)</b><br> | ||
| 165 | unconnected:<b>receive(</b>[size]<b>)</b> | ||
| 166 | </p> | ||
| 167 | |||
| 168 | <p class="description"> | ||
| 169 | Receives a datagram from the UDP object. If | ||
| 170 | the UDP object is connected, only datagrams coming from the peer | ||
| 171 | are accepted. Otherwise, the returned datagram can come from any | ||
| 172 | host. | ||
| 173 | </p> | ||
| 174 | |||
| 175 | <p class="parameters"> | ||
| 176 | The optional <tt>size</tt> parameter | ||
| 177 | specifies the maximum size of the datagram to be retrieved. If | ||
| 178 | there are more than <tt>size</tt> bytes available in the datagram, | ||
| 179 | the excess bytes are discarded. If there are less then | ||
| 180 | <tt>size</tt> bytes available in the current datagram, the | ||
| 181 | available bytes are returned. | ||
| 182 | If <tt>size</tt> is omitted, the | ||
| 183 | compile-time constant <a href="socket.html#datagramsize"> | ||
| 184 | <tt>socket._DATAGRAMSIZE</tt></a> is used | ||
| 185 | (it defaults to 8192 bytes). Larger sizes will cause a | ||
| 186 | temporary buffer to be allocated for the operation. | ||
| 187 | </p> | ||
| 188 | |||
| 189 | <p class="return"> | ||
| 190 | In case of success, the method returns the | ||
| 191 | received datagram. In case of timeout, the method returns | ||
| 192 | <b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'. | ||
| 193 | </p> | ||
| 194 | |||
| 195 | <!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 196 | |||
| 197 | <p class="name" id="receivefrom"> | ||
| 198 | unconnected:<b>receivefrom(</b>[size]<b>)</b> | ||
| 199 | </p> | ||
| 200 | |||
| 201 | <p class="description"> | ||
| 202 | Works exactly as the <a href="#receive"><tt>receive</tt></a> | ||
| 203 | method, except it returns the IP | ||
| 204 | address and port as extra return values (and is therefore slightly less | ||
| 205 | efficient). | ||
| 206 | </p> | ||
| 207 | |||
| 208 | <!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 209 | |||
| 210 | <p class="name" id="send"> | ||
| 211 | connected:<b>send(</b>datagram<b>)</b> | ||
| 212 | </p> | ||
| 213 | |||
| 214 | <p class="description"> | ||
| 215 | Sends a datagram to the UDP peer of a connected object. | ||
| 216 | </p> | ||
| 217 | |||
| 218 | <p class="parameters"> | ||
| 219 | <tt>Datagram</tt> is a string with the datagram contents. | ||
| 220 | The maximum datagram size for UDP is 64K minus IP layer overhead. | ||
| 221 | However datagrams larger than the link layer packet size will be | ||
| 222 | fragmented, which may deteriorate performance and/or reliability. | ||
| 223 | </p> | ||
| 224 | |||
| 225 | <p class="return"> | ||
| 226 | If successful, the method returns 1. In case of | ||
| 227 | error, the method returns <b><tt>nil</tt></b> followed by an error message. | ||
| 228 | </p> | ||
| 229 | |||
| 230 | <p class="note"> | ||
| 231 | Note: In UDP, the <tt>send</tt> method never blocks | ||
| 232 | and the only way it can fail is if the underlying transport layer | ||
| 233 | refuses to send a message to the specified address (i.e. no | ||
| 234 | interface accepts the address). | ||
| 235 | </p> | ||
| 236 | |||
| 237 | <!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 238 | |||
| 239 | <p class="name" id="sendto"> | ||
| 240 | unconnected:<b>sendto(</b>datagram, ip, port<b>)</b> | ||
| 241 | </p> | ||
| 242 | |||
| 243 | <p class="description"> | ||
| 244 | Sends a datagram to the specified IP address and port number. | ||
| 245 | </p> | ||
| 246 | |||
| 247 | <p class="parameters"> | ||
| 248 | <tt>Datagram</tt> is a string with the | ||
| 249 | datagram contents. | ||
| 250 | The maximum datagram size for UDP is 64K minus IP layer overhead. | ||
| 251 | However datagrams larger than the link layer packet size will be | ||
| 252 | fragmented, which may deteriorate performance and/or reliability. | ||
| 253 | <tt>Ip</tt> is the IP address of the recipient. | ||
| 254 | Host names are <em>not</em> allowed for performance reasons. | ||
| 255 | |||
| 256 | <tt>Port</tt> is the port number at the recipient. | ||
| 257 | </p> | ||
| 258 | |||
| 259 | <p class="return"> | ||
| 260 | If successful, the method returns 1. In case of | ||
| 261 | error, the method returns <b><tt>nil</tt></b> followed by an error message. | ||
| 262 | </p> | ||
| 263 | |||
| 264 | <p class="note"> | ||
| 265 | Note: In UDP, the <tt>send</tt> method never blocks | ||
| 266 | and the only way it can fail is if the underlying transport layer | ||
| 267 | refuses to send a message to the specified address (i.e. no | ||
| 268 | interface accepts the address). | ||
| 269 | </p> | ||
| 270 | |||
| 271 | <!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 272 | |||
| 273 | <p class="name" id="setoption"> | ||
| 274 | connected:<b>setoption(</b>option [, value]<b>)</b><br> | ||
| 275 | unconnected:<b>setoption(</b>option [, value]<b>)</b> | ||
| 276 | </p> | ||
| 277 | |||
| 278 | <p class="description"> | ||
| 279 | Sets options for the UDP object. Options are | ||
| 280 | only needed by low-level or time-critical applications. You should | ||
| 281 | only modify an option if you are sure you need it.</p> | ||
| 282 | <p class="parameters"><tt>Option</tt> is a string with the option | ||
| 283 | name, and <tt>value</tt> depends on the option being set: | ||
| 284 | </p> | ||
| 285 | |||
| 286 | <ul> | ||
| 287 | <li> '<tt>dontroute</tt>': Indicates that outgoing | ||
| 288 | messages should bypass the standard routing facilities. | ||
| 289 | Receives a boolean value;</li> | ||
| 290 | <li> '<tt>broadcast</tt>': Requests permission to send | ||
| 291 | broadcast datagrams on the socket. | ||
| 292 | Receives a boolean value;</li> | ||
| 293 | <li> '<tt>reuseaddr</tt>': Indicates that the rules used in | ||
| 294 | validating addresses supplied in a <tt>bind()</tt> call | ||
| 295 | should allow reuse of local addresses. | ||
| 296 | Receives a boolean value;</li> | ||
| 297 | <li> '<tt>reuseport</tt>': Allows completely duplicate | ||
| 298 | bindings by multiple processes if they all set | ||
| 299 | '<tt>reuseport</tt>' before binding the port. | ||
| 300 | Receives a boolean value;</li> | ||
| 301 | <li> '<tt>ip-multicast-loop</tt>': | ||
| 302 | Specifies whether or not a copy of an outgoing multicast | ||
| 303 | datagram is delivered to the sending host as long as it is a | ||
| 304 | member of the multicast group. | ||
| 305 | Receives a boolean value;</li> | ||
| 306 | <li> '<tt>ipv6-v6only</tt>': | ||
| 307 | Specifies whether to restrict <tt>inet6</tt> sockets to | ||
| 308 | sending and receiving only IPv6 packets. | ||
| 309 | Receive a boolean value;</li> | ||
| 310 | <li> '<tt>ip-multicast-if</tt>': | ||
| 311 | Sets the interface over which outgoing multicast datagrams | ||
| 312 | are sent. | ||
| 313 | Receives an IP address;</li> | ||
| 314 | <li> '<tt>ip-multicast-ttl</tt>': | ||
| 315 | Sets the Time To Live in the IP header for outgoing | ||
| 316 | multicast datagrams. | ||
| 317 | Receives a number;</li> | ||
| 318 | <li> '<tt>ip-add-membership</tt>': | ||
| 319 | Joins the multicast group specified. | ||
| 320 | Receives a table with fields | ||
| 321 | <tt>multiaddr</tt> and <tt>interface</tt>, each containing an | ||
| 322 | IP address;</li> | ||
| 323 | <li> '<tt>ip-drop-membership</tt>': Leaves the multicast | ||
| 324 | group specified. | ||
| 325 | Receives a table with fields | ||
| 326 | <tt>multiaddr</tt> and <tt>interface</tt>, each containing an | ||
| 327 | IP address.</li> | ||
| 328 | </ul> | ||
| 329 | |||
| 330 | <p class="return"> | ||
| 331 | The method returns 1 in case of success, or | ||
| 332 | <b><tt>nil</tt></b> followed by an error message otherwise. | ||
| 333 | </p> | ||
| 334 | |||
| 335 | <p class="note"> | ||
| 336 | Note: The descriptions above come from the man pages. | ||
| 337 | </p> | ||
| 338 | |||
| 339 | |||
| 340 | <!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 341 | |||
| 342 | <p class="name" id="setpeername"> | ||
| 343 | connected:<b>setpeername(</b>'*'<b>)</b><br> | ||
| 344 | unconnected:<b>setpeername(</b>address, port<b>)</b> | ||
| 345 | </p> | ||
| 346 | |||
| 347 | <p class="description"> | ||
| 348 | Changes the peer of a UDP object. This | ||
| 349 | method turns an unconnected UDP object into a connected UDP | ||
| 350 | object or vice versa. | ||
| 351 | </p> | ||
| 352 | |||
| 353 | <p class="description"> | ||
| 354 | For connected objects, outgoing datagrams | ||
| 355 | will be sent to the specified peer, and datagrams received from | ||
| 356 | other peers will be discarded by the OS. Connected UDP objects must | ||
| 357 | use the <a href="#send"><tt>send</tt></a> and | ||
| 358 | <a href="#receive"><tt>receive</tt></a> methods instead of | ||
| 359 | <a href="#sendto"><tt>sendto</tt></a> and | ||
| 360 | <a href="#receivefrom"><tt>receivefrom</tt></a>. | ||
| 361 | </p> | ||
| 362 | |||
| 363 | <p class="parameters"> | ||
| 364 | <tt>Address</tt> can be an IP address or a | ||
| 365 | host name. <tt>Port</tt> is the port number. If <tt>address</tt> is | ||
| 366 | '<tt>*</tt>' and the object is connected, the peer association is | ||
| 367 | removed and the object becomes an unconnected object again. In that | ||
| 368 | case, the <tt>port</tt> argument is ignored. | ||
| 369 | </p> | ||
| 370 | |||
| 371 | <p class="return"> | ||
| 372 | In case of error the method returns | ||
| 373 | <b><tt>nil</tt></b> followed by an error message. In case of success, the | ||
| 374 | method returns 1. | ||
| 375 | </p> | ||
| 376 | |||
| 377 | <p class="note"> | ||
| 378 | Note: Since the address of the peer does not have | ||
| 379 | to be passed to and from the OS, the use of connected UDP objects | ||
| 380 | is recommended when the same peer is used for several transmissions | ||
| 381 | and can result in up to 30% performance gains. | ||
| 382 | </p> | ||
| 383 | |||
| 384 | <p class="note"> | ||
| 385 | Note: Starting with LuaSocket 3.0, the host name resolution | ||
| 386 | depends on whether the socket was created by <a | ||
| 387 | href="#socket.udp"><tt>socket.udp</tt></a> or <a | ||
| 388 | href="#socket.udp6"><tt>socket.udp6</tt></a>. Addresses from | ||
| 389 | the appropriate family are tried in succession until the | ||
| 390 | first success or until the last failure. | ||
| 391 | </p> | ||
| 392 | |||
| 393 | <!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 394 | |||
| 395 | <p class="name" id="setsockname"> | ||
| 396 | unconnected:<b>setsockname(</b>address, port<b>)</b> | ||
| 397 | </p> | ||
| 398 | |||
| 399 | <p class="description"> | ||
| 400 | Binds the UDP object to a local address. | ||
| 401 | </p> | ||
| 402 | |||
| 403 | <p class="parameters"> | ||
| 404 | <tt>Address</tt> can be an IP address or a | ||
| 405 | host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to | ||
| 406 | all local interfaces using the constant <tt>INADDR_ANY</tt>. If | ||
| 407 | <tt>port</tt> is 0, the system chooses an ephemeral port. | ||
| 408 | </p> | ||
| 409 | |||
| 410 | <p class="return"> | ||
| 411 | If successful, the method returns 1. In case of | ||
| 412 | error, the method returns <b><tt>nil</tt></b> followed by an error | ||
| 413 | message. | ||
| 414 | </p> | ||
| 415 | |||
| 416 | <p class="note"> | ||
| 417 | Note: This method can only be called before any | ||
| 418 | datagram is sent through the UDP object, and only once. Otherwise, | ||
| 419 | the system automatically binds the object to all local interfaces | ||
| 420 | and chooses an ephemeral port as soon as the first datagram is | ||
| 421 | sent. After the local address is set, either automatically by the | ||
| 422 | system or explicitly by <tt>setsockname</tt>, it cannot be | ||
| 423 | changed. | ||
| 424 | </p> | ||
| 425 | |||
| 426 | <!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 427 | |||
| 428 | <p class="name" id="settimeout"> | ||
| 429 | connected:<b>settimeout(</b>value<b>)</b><br> | ||
| 430 | unconnected:<b>settimeout(</b>value<b>)</b> | ||
| 431 | </p> | ||
| 432 | |||
| 433 | <p class="description"> | ||
| 434 | Changes the timeout values for the object. By default, the | ||
| 435 | <a href="#receive"><tt>receive</tt></a> and | ||
| 436 | <a href="#receivefrom"><tt>receivefrom</tt></a> | ||
| 437 | operations are blocking. That is, any call to the methods will block | ||
| 438 | indefinitely, until data arrives. The <tt>settimeout</tt> function defines | ||
| 439 | a limit on the amount of time the functions can block. When a timeout is | ||
| 440 | set and the specified amount of time has elapsed, the affected methods | ||
| 441 | give up and fail with an error code. | ||
| 442 | </p> | ||
| 443 | |||
| 444 | <p class="parameters"> | ||
| 445 | The amount of time to wait is specified as | ||
| 446 | the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout | ||
| 447 | <tt>value</tt> allows operations to block indefinitely. Negative | ||
| 448 | timeout values have the same effect. | ||
| 449 | </p> | ||
| 450 | |||
| 451 | <p class="note"> | ||
| 452 | Note: In UDP, the <a href="#send"><tt>send</tt></a> | ||
| 453 | and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the | ||
| 454 | datagram is just passed to the OS and the call returns | ||
| 455 | immediately). Therefore, the <tt>settimeout</tt> method has no | ||
| 456 | effect on them. | ||
| 457 | </p> | ||
| 458 | |||
| 459 | <p class="note"> | ||
| 460 | Note: The old <tt>timeout</tt> method is | ||
| 461 | deprecated. The name has been changed for sake of uniformity, since | ||
| 462 | all other method names already contained verbs making their | ||
| 463 | imperative nature obvious. | ||
| 464 | </p> | ||
| 465 | |||
| 466 | <!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 467 | |||
| 468 | <p class="name" id="socket.udp"> | ||
| 469 | socket.<b>udp()</b> | ||
| 470 | </p> | ||
| 471 | |||
| 472 | <p class="description"> | ||
| 473 | Creates and returns an unconnected UDP object. | ||
| 474 | Unconnected objects support the | ||
| 475 | <a href="#sendto"><tt>sendto</tt></a>, | ||
| 476 | <a href="#receive"><tt>receive</tt></a>, | ||
| 477 | <a href="#receivefrom"><tt>receivefrom</tt></a>, | ||
| 478 | <a href="#getoption"><tt>getoption</tt></a>, | ||
| 479 | <a href="#getsockname"><tt>getsockname</tt></a>, | ||
| 480 | <a href="#setoption"><tt>setoption</tt></a>, | ||
| 481 | <a href="#settimeout"><tt>settimeout</tt></a>, | ||
| 482 | <a href="#setpeername"><tt>setpeername</tt></a>, | ||
| 483 | <a href="#setsockname"><tt>setsockname</tt></a>, and | ||
| 484 | <a href="#close"><tt>close</tt></a>. | ||
| 485 | The <a href="#setpeername"><tt>setpeername</tt></a> | ||
| 486 | is used to connect the object. | ||
| 487 | </p> | ||
| 488 | |||
| 489 | <p class="return"> | ||
| 490 | In case of success, a new unconnected UDP object | ||
| 491 | returned. In case of error, <b><tt>nil</tt></b> is returned, followed by | ||
| 492 | an error message. | ||
| 493 | </p> | ||
| 494 | |||
| 495 | <p class="note"> | ||
| 496 | Note: The choice between IPv4 and IPv6 happens during a call to | ||
| 497 | <a href="#sendto"><tt>sendto</tt></a>, <a | ||
| 498 | href="#setpeername"><tt>setpeername</tt></a>, or <a | ||
| 499 | href="#setsockname"><tt>sockname</tt></a>, depending on the address | ||
| 500 | family obtained from the resolver. | ||
| 501 | </p> | ||
| 502 | |||
| 503 | <p class="note"> | ||
| 504 | Note: Before the choice between IPv4 and IPv6 happens, | ||
| 505 | the internal socket object is invalid and therefore <a | ||
| 506 | href="#setoption"><tt>setoption</tt></a> will fail. | ||
| 507 | </p> | ||
| 508 | |||
| 509 | <!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 510 | |||
| 511 | <p class="name" id="socket.udp4"> | ||
| 512 | socket.<b>udp4()</b> | ||
| 513 | </p> | ||
| 514 | |||
| 515 | <p class="description"> | ||
| 516 | Creates and returns an unconnected IPv4 UDP object. | ||
| 517 | Unconnected objects support the | ||
| 518 | <a href="#sendto"><tt>sendto</tt></a>, | ||
| 519 | <a href="#receive"><tt>receive</tt></a>, | ||
| 520 | <a href="#receivefrom"><tt>receivefrom</tt></a>, | ||
| 521 | <a href="#getoption"><tt>getoption</tt></a>, | ||
| 522 | <a href="#getsockname"><tt>getsockname</tt></a>, | ||
| 523 | <a href="#setoption"><tt>setoption</tt></a>, | ||
| 524 | <a href="#settimeout"><tt>settimeout</tt></a>, | ||
| 525 | <a href="#setpeername"><tt>setpeername</tt></a>, | ||
| 526 | <a href="#setsockname"><tt>setsockname</tt></a>, and | ||
| 527 | <a href="#close"><tt>close</tt></a>. | ||
| 528 | The <a href="#setpeername"><tt>setpeername</tt></a> | ||
| 529 | is used to connect the object. | ||
| 530 | </p> | ||
| 531 | |||
| 532 | <p class="return"> | ||
| 533 | In case of success, a new unconnected UDP object | ||
| 534 | returned. In case of error, <b><tt>nil</tt></b> is returned, followed by | ||
| 535 | an error message. | ||
| 536 | </p> | ||
| 537 | |||
| 538 | <!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 539 | |||
| 540 | <p class="name" id="socket.udp6"> | ||
| 541 | socket.<b>udp6()</b> | ||
| 542 | </p> | ||
| 543 | |||
| 544 | <p class="description"> | ||
| 545 | Creates and returns an unconnected IPv6 UDP object. | ||
| 546 | Unconnected objects support the | ||
| 547 | <a href="#sendto"><tt>sendto</tt></a>, | ||
| 548 | <a href="#receive"><tt>receive</tt></a>, | ||
| 549 | <a href="#receivefrom"><tt>receivefrom</tt></a>, | ||
| 550 | <a href="#getoption"><tt>getoption</tt></a>, | ||
| 551 | <a href="#getsockname"><tt>getsockname</tt></a>, | ||
| 552 | <a href="#setoption"><tt>setoption</tt></a>, | ||
| 553 | <a href="#settimeout"><tt>settimeout</tt></a>, | ||
| 554 | <a href="#setpeername"><tt>setpeername</tt></a>, | ||
| 555 | <a href="#setsockname"><tt>setsockname</tt></a>, and | ||
| 556 | <a href="#close"><tt>close</tt></a>. | ||
| 557 | The <a href="#setpeername"><tt>setpeername</tt></a> | ||
| 558 | is used to connect the object. | ||
| 559 | </p> | ||
| 560 | |||
| 561 | <p class="return"> | ||
| 562 | In case of success, a new unconnected UDP object | ||
| 563 | returned. In case of error, <b><tt>nil</tt></b> is returned, followed by | ||
| 564 | an error message. | ||
| 565 | </p> | ||
| 566 | |||
| 567 | <p class="note"> | ||
| 568 | Note: The TCP object returned will have the option | ||
| 569 | "<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. | ||
| 570 | </p> | ||
| 571 | |||
| 572 | |||
| 573 | |||
| 574 | <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 575 | |||
| 576 | <div class="footer"> | ||
| 577 | <hr> | ||
| 578 | <center> | ||
| 579 | <p class="bar"> | ||
| 580 | <a href="index.html">home</a> · | ||
| 581 | <a href="index.html#download">download</a> · | ||
| 582 | <a href="installation.html">installation</a> · | ||
| 583 | <a href="introduction.html">introduction</a> · | ||
| 584 | <a href="reference.html">reference</a> | ||
| 585 | </p> | ||
| 586 | <p> | ||
| 587 | <small> | ||
| 588 | Last modified by Diego Nehab on <br> | ||
| 589 | Thu Apr 20 00:26:01 EDT 2006 | ||
| 590 | </small> | ||
| 591 | </p> | ||
| 592 | </center> | ||
| 593 | </div> | ||
| 594 | |||
| 595 | </body> | ||
| 596 | </html> | ||
diff --git a/docs/url.html b/docs/url.html new file mode 100644 index 0000000..6ff673d --- /dev/null +++ b/docs/url.html | |||
| @@ -0,0 +1,328 @@ | |||
| 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: URL manipulation"> | ||
| 7 | <meta name="keywords" content="Lua, LuaSocket, URL, Library, Link, Network, Support"> | ||
| 8 | <title>LuaSocket: URL support</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> · | ||
| 28 | <a href="index.html#download">download</a> · | ||
| 29 | <a href="installation.html">installation</a> · | ||
| 30 | <a href="introduction.html">introduction</a> · | ||
| 31 | <a href="reference.html">reference</a> | ||
| 32 | </p> | ||
| 33 | </center> | ||
| 34 | <hr> | ||
| 35 | </div> | ||
| 36 | |||
| 37 | <!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 38 | |||
| 39 | <h2 id="url">URL</h2> | ||
| 40 | |||
| 41 | <p> | ||
| 42 | The <tt>url</tt> namespace provides functions to parse, protect, | ||
| 43 | and build URLs, as well as functions to compose absolute URLs | ||
| 44 | from base and relative URLs, according to | ||
| 45 | <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. | ||
| 46 | </p> | ||
| 47 | |||
| 48 | <p> | ||
| 49 | To obtain the <tt>url</tt> namespace, run: | ||
| 50 | </p> | ||
| 51 | |||
| 52 | <pre class=example> | ||
| 53 | -- loads the URL module | ||
| 54 | local url = require("socket.url") | ||
| 55 | </pre> | ||
| 56 | |||
| 57 | <p> | ||
| 58 | An URL is defined by the following grammar: | ||
| 59 | </p> | ||
| 60 | |||
| 61 | <blockquote> | ||
| 62 | <tt> | ||
| 63 | <url> ::= [<scheme>:][//<authority>][/<path>][;<params>][?<query>][#<fragment>]<br> | ||
| 64 | <authority> ::= [<userinfo>@]<host>[:<port>]<br> | ||
| 65 | <userinfo> ::= <user>[:<password>]<br> | ||
| 66 | <path> ::= {<segment>/}<segment><br> | ||
| 67 | </tt> | ||
| 68 | </blockquote> | ||
| 69 | |||
| 70 | <!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 71 | |||
| 72 | <p class=name id="absolute"> | ||
| 73 | url.<b>absolute(</b>base, relative<b>)</b> | ||
| 74 | </p> | ||
| 75 | |||
| 76 | <p class=description> | ||
| 77 | Builds an absolute URL from a base URL and a relative URL. | ||
| 78 | </p> | ||
| 79 | |||
| 80 | <p class=parameters> | ||
| 81 | <tt>Base</tt> is a string with the base URL or | ||
| 82 | a parsed URL table. <tt>Relative</tt> is a | ||
| 83 | string with the relative URL. | ||
| 84 | </p> | ||
| 85 | |||
| 86 | <p class=return> | ||
| 87 | The function returns a string with the absolute URL. | ||
| 88 | </p> | ||
| 89 | |||
| 90 | <p class=note> | ||
| 91 | Note: The rules that | ||
| 92 | govern the composition are fairly complex, and are described in detail in | ||
| 93 | <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. | ||
| 94 | The example bellow should give an idea of what the rules are. | ||
| 95 | </p> | ||
| 96 | |||
| 97 | <pre class=example> | ||
| 98 | http://a/b/c/d;p?q | ||
| 99 | |||
| 100 | + | ||
| 101 | |||
| 102 | g:h = g:h | ||
| 103 | g = http://a/b/c/g | ||
| 104 | ./g = http://a/b/c/g | ||
| 105 | g/ = http://a/b/c/g/ | ||
| 106 | /g = http://a/g | ||
| 107 | //g = http://g | ||
| 108 | ?y = http://a/b/c/?y | ||
| 109 | g?y = http://a/b/c/g?y | ||
| 110 | #s = http://a/b/c/d;p?q#s | ||
| 111 | g#s = http://a/b/c/g#s | ||
| 112 | g?y#s = http://a/b/c/g?y#s | ||
| 113 | ;x = http://a/b/c/;x | ||
| 114 | g;x = http://a/b/c/g;x | ||
| 115 | g;x?y#s = http://a/b/c/g;x?y#s | ||
| 116 | . = http://a/b/c/ | ||
| 117 | ./ = http://a/b/c/ | ||
| 118 | .. = http://a/b/ | ||
| 119 | ../ = http://a/b/ | ||
| 120 | ../g = http://a/b/g | ||
| 121 | ../.. = http://a/ | ||
| 122 | ../../ = http://a/ | ||
| 123 | ../../g = http://a/g | ||
| 124 | </pre> | ||
| 125 | |||
| 126 | <!-- build ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 127 | |||
| 128 | <p class=name id="build"> | ||
| 129 | url.<b>build(</b>parsed_url<b>)</b> | ||
| 130 | </p> | ||
| 131 | |||
| 132 | <p class=description> | ||
| 133 | Rebuilds an URL from its parts. | ||
| 134 | </p> | ||
| 135 | |||
| 136 | <p class=parameters> | ||
| 137 | <tt>Parsed_url</tt> is a table with same components returned by | ||
| 138 | <a href="#parse"><tt>parse</tt></a>. | ||
| 139 | Lower level components, if specified, | ||
| 140 | take precedence over high level components of the URL grammar. | ||
| 141 | </p> | ||
| 142 | |||
| 143 | <p class=return> | ||
| 144 | The function returns a string with the built URL. | ||
| 145 | </p> | ||
| 146 | |||
| 147 | <!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 148 | |||
| 149 | <p class=name id="build_path"> | ||
| 150 | url.<b>build_path(</b>segments, unsafe<b>)</b> | ||
| 151 | </p> | ||
| 152 | |||
| 153 | <p class=description> | ||
| 154 | Builds a <tt><path></tt> component from a list of | ||
| 155 | <tt><segment></tt> parts. | ||
| 156 | Before composition, any reserved characters found in a segment are escaped into | ||
| 157 | their protected form, so that the resulting path is a valid URL path | ||
| 158 | component. | ||
| 159 | </p> | ||
| 160 | |||
| 161 | <p class=parameters> | ||
| 162 | <tt>Segments</tt> is a list of strings with the <tt><segment></tt> | ||
| 163 | parts. If <tt>unsafe</tt> is anything but <b><tt>nil</tt></b>, reserved | ||
| 164 | characters are left untouched. | ||
| 165 | </p> | ||
| 166 | |||
| 167 | <p class=return> | ||
| 168 | The function returns a string with the | ||
| 169 | built <tt><path></tt> component. | ||
| 170 | </p> | ||
| 171 | |||
| 172 | <!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 173 | |||
| 174 | <p class=name id="escape"> | ||
| 175 | url.<b>escape(</b>content<b>)</b> | ||
| 176 | </p> | ||
| 177 | |||
| 178 | <p class=description> | ||
| 179 | Applies the URL escaping content coding to a string | ||
| 180 | Each byte is encoded as a percent character followed | ||
| 181 | by the two byte hexadecimal representation of its integer | ||
| 182 | value. | ||
| 183 | </p> | ||
| 184 | |||
| 185 | <p class=parameters> | ||
| 186 | <tt>Content</tt> is the string to be encoded. | ||
| 187 | </p> | ||
| 188 | |||
| 189 | <p class=result> | ||
| 190 | The function returns the encoded string. | ||
| 191 | </p> | ||
| 192 | |||
| 193 | <pre class=example> | ||
| 194 | -- load url module | ||
| 195 | url = require("socket.url") | ||
| 196 | |||
| 197 | code = url.escape("/#?;") | ||
| 198 | -- code = "%2f%23%3f%3b" | ||
| 199 | </pre> | ||
| 200 | |||
| 201 | <!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 202 | |||
| 203 | <p class=name id="parse"> | ||
| 204 | url.<b>parse(</b>url, default<b>)</b> | ||
| 205 | </p> | ||
| 206 | |||
| 207 | <p class=description> | ||
| 208 | Parses an URL given as a string into a Lua table with its components. | ||
| 209 | </p> | ||
| 210 | |||
| 211 | <p class=parameters> | ||
| 212 | <tt>Url</tt> is the URL to be parsed. If the <tt>default</tt> table is | ||
| 213 | present, it is used to store the parsed fields. Only fields present in the | ||
| 214 | URL are overwritten. Therefore, this table can be used to pass default | ||
| 215 | values for each field. | ||
| 216 | </p> | ||
| 217 | |||
| 218 | <p class=return> | ||
| 219 | The function returns a table with all the URL components: | ||
| 220 | </p> | ||
| 221 | |||
| 222 | <blockquote><tt> | ||
| 223 | parsed_url = {<br> | ||
| 224 | url = <i>string</i>,<br> | ||
| 225 | scheme = <i>string</i>,<br> | ||
| 226 | authority = <i>string</i>,<br> | ||
| 227 | path = <i>string</i>,<br> | ||
| 228 | params = <i>string</i>,<br> | ||
| 229 | query = <i>string</i>,<br> | ||
| 230 | fragment = <i>string</i>,<br> | ||
| 231 | userinfo = <i>string</i>,<br> | ||
| 232 | host = <i>string</i>,<br> | ||
| 233 | port = <i>string</i>,<br> | ||
| 234 | user = <i>string</i>,<br> | ||
| 235 | password = <i>string</i><br> | ||
| 236 | } | ||
| 237 | </tt></blockquote> | ||
| 238 | |||
| 239 | <pre class=example> | ||
| 240 | -- load url module | ||
| 241 | url = require("socket.url") | ||
| 242 | |||
| 243 | parsed_url = url.parse("http://www.example.com/cgilua/index.lua?a=2#there") | ||
| 244 | -- parsed_url = { | ||
| 245 | -- scheme = "http", | ||
| 246 | -- authority = "www.example.com", | ||
| 247 | -- path = "/cgilua/index.lua" | ||
| 248 | -- query = "a=2", | ||
| 249 | -- fragment = "there", | ||
| 250 | -- host = "www.puc-rio.br", | ||
| 251 | -- } | ||
| 252 | |||
| 253 | parsed_url = url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i") | ||
| 254 | -- parsed_url = { | ||
| 255 | -- scheme = "ftp", | ||
| 256 | -- authority = "root:passwd@unsafe.org", | ||
| 257 | -- path = "/pub/virus.exe", | ||
| 258 | -- params = "type=i", | ||
| 259 | -- userinfo = "root:passwd", | ||
| 260 | -- host = "unsafe.org", | ||
| 261 | -- user = "root", | ||
| 262 | -- password = "passwd", | ||
| 263 | -- } | ||
| 264 | </pre> | ||
| 265 | |||
| 266 | <!-- parse_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 267 | |||
| 268 | <p class=name id="parse_path"> | ||
| 269 | url.<b>parse_path(</b>path<b>)</b> | ||
| 270 | </p> | ||
| 271 | |||
| 272 | <p class=description> | ||
| 273 | Breaks a <tt><path></tt> URL component into all its | ||
| 274 | <tt><segment></tt> parts. | ||
| 275 | </p> | ||
| 276 | |||
| 277 | <p class=description> | ||
| 278 | <tt>Path</tt> is a string with the path to be parsed. | ||
| 279 | </p> | ||
| 280 | |||
| 281 | <p class=return> | ||
| 282 | Since some characters are reserved in URLs, they must be escaped | ||
| 283 | whenever present in a <tt><path></tt> component. Therefore, before | ||
| 284 | returning a list with all the parsed segments, the function removes | ||
| 285 | escaping from all of them. | ||
| 286 | </p> | ||
| 287 | |||
| 288 | <!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 289 | |||
| 290 | <p class=name id="unescape"> | ||
| 291 | url.<b>unescape(</b>content<b>)</b> | ||
| 292 | </p> | ||
| 293 | |||
| 294 | <p class=description> | ||
| 295 | Removes the URL escaping content coding from a string. | ||
| 296 | </p> | ||
| 297 | |||
| 298 | <p class=parameters> | ||
| 299 | <tt>Content</tt> is the string to be decoded. | ||
| 300 | </p> | ||
| 301 | |||
| 302 | <p class=return> | ||
| 303 | The function returns the decoded string. | ||
| 304 | </p> | ||
| 305 | |||
| 306 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
| 307 | |||
| 308 | <div class=footer> | ||
| 309 | <hr> | ||
| 310 | <center> | ||
| 311 | <p class=bar> | ||
| 312 | <a href="index.html">home</a> · | ||
| 313 | <a href="index.html#down">download</a> · | ||
| 314 | <a href="installation.html">installation</a> · | ||
| 315 | <a href="introduction.html">introduction</a> · | ||
| 316 | <a href="reference.html">reference</a> | ||
| 317 | </p> | ||
| 318 | <p> | ||
| 319 | <small> | ||
| 320 | Last modified by Diego Nehab on <br> | ||
| 321 | Thu Apr 20 00:26:05 EDT 2006 | ||
| 322 | </small> | ||
| 323 | </p> | ||
| 324 | </center> | ||
| 325 | </div> | ||
| 326 | |||
| 327 | </body> | ||
| 328 | </html> | ||
