diff options
Diffstat (limited to 'ThirdParty/luasocket/doc')
| -rw-r--r-- | ThirdParty/luasocket/doc/dns.html | 183 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/ftp.html | 288 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/http.html | 337 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/index.html | 215 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/installation.html | 127 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/introduction.html | 333 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/ltn12.html | 440 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/lua05.ppt | bin | 0 -> 304128 bytes | |||
| -rw-r--r-- | ThirdParty/luasocket/doc/luasocket.png | bin | 0 -> 11732 bytes | |||
| -rw-r--r-- | ThirdParty/luasocket/doc/mime.html | 477 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/reference.css | 55 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/reference.html | 261 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/smtp.html | 418 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/socket.html | 479 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/tcp.html | 727 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/udp.html | 596 | ||||
| -rw-r--r-- | ThirdParty/luasocket/doc/url.html | 328 |
17 files changed, 5264 insertions, 0 deletions
diff --git a/ThirdParty/luasocket/doc/dns.html b/ThirdParty/luasocket/doc/dns.html new file mode 100644 index 0000000..c4a0472 --- /dev/null +++ b/ThirdParty/luasocket/doc/dns.html @@ -0,0 +1,183 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: DNS support"> +<meta name="keywords" content="Lua, LuaSocket, DNS, Network, Library, Support"> +<title>LuaSocket: DNS support</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=dns>DNS</h2> + +<p> +IPv4 name resolution functions +<a href=#toip><tt>dns.toip</tt></a> +and +<a href=#tohostname><tt>dns.tohostname</tt></a> +return <em>all</em> information obtained from +the resolver in a table of the form: +</p> + +<blockquote><tt> +resolved4 = {<br> + name = <i>canonic-name</i>,<br> + alias = <i>alias-list</i>,<br> + ip = <i>ip-address-list</i><br> +} +</tt> </blockquote> + +<p> +Note that the <tt>alias</tt> list can be empty. +</p> + +<p> +The more general name resolution function +<a href=#getaddrinfo><tt>dns.getaddrinfo</tt></a>, which +supports both IPv6 and IPv4, +returns <em>all</em> information obtained from +the resolver in a table of the form: +</p> + +<blockquote><tt> +resolved6 = {<br> + [1] = {<br> + family = <i>family-name-1</i>,<br> + addr = <i>address-1</i><br> + },<br> + ...<br> + [n] = {<br> + family = <i>family-name-n</i>,<br> + addr = <i>address-n</i><br> + }<br> +} +</tt> </blockquote> + +<p> +Here, <tt>family</tt> contains the string <tt>"inet"</tt> for IPv4 +addresses, and <tt>"inet6"</tt> for IPv6 addresses. +</p> + +<!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=getaddrinfo> +socket.dns.<b>getaddrinfo(</b>address<b>)</b> +</p> + +<p class=description> +Converts from host name to address. +</p> + +<p class=parameters> +<tt>Address</tt> can be an IPv4 or IPv6 address or host name. +</p> + +<p class=return> +The function returns a table with all information returned by +the resolver. In case of error, the function returns <b><tt>nil</tt></b> +followed by an error message. +</p> + +<!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=gethostname> +socket.dns.<b>gethostname()</b> +</p> + +<p class=description> +Returns the standard host name for the machine as a string. +</p> + +<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=tohostname> +socket.dns.<b>tohostname(</b>address<b>)</b> +</p> + +<p class=description> +Converts from IPv4 address to host name. +</p> + +<p class=parameters> +<tt>Address</tt> can be an IP address or host name. +</p> + +<p class=return> +The function returns a string with the canonic host name of the given +<tt>address</tt>, followed by a table with all information returned by +the resolver. In case of error, the function returns <b><tt>nil</tt></b> +followed by an error message. +</p> + +<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=toip> +socket.dns.<b>toip(</b>address<b>)</b> +</p> + +<p class=description> +Converts from host name to IPv4 address. +</p> + +<p class=parameters> +<tt>Address</tt> can be an IP address or host name. +</p> + +<p class=return> +Returns a string with the first IP address found for <tt>address</tt>, +followed by a table with all information returned by the resolver. +In case of error, the function returns <b><tt>nil</tt></b> followed by an error +message. +</p> + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:25:07 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/ftp.html b/ThirdParty/luasocket/doc/ftp.html new file mode 100644 index 0000000..091c88f --- /dev/null +++ b/ThirdParty/luasocket/doc/ftp.html @@ -0,0 +1,288 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: FTP support"> +<meta name="keywords" content="Lua, LuaSocket, FTP, Network, Library, Support"> +<title>LuaSocket: FTP support</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=ftp>FTP</h2> + +<p> +FTP (File Transfer Protocol) is a protocol used to transfer files +between hosts. The <tt>ftp</tt> namespace offers thorough support +to FTP, under a simple interface. The implementation conforms to +<a href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</a>. +</p> + +<p> +High level functions are provided supporting the most common operations. +These high level functions are implemented on top of a lower level +interface. Using the low-level interface, users can easily create their +own functions to access <em>any</em> operation supported by the FTP +protocol. For that, check the implementation. +</p> + +<p> +To really benefit from this module, a good understanding of +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> +LTN012, Filters sources and sinks</a> is necessary. +</p> + +<p> +To obtain the <tt>ftp</tt> namespace, run: +</p> + +<pre class=example> +-- loads the FTP module and any libraries it requires +local ftp = require("socket.ftp") +</pre> + +<p> +URLs MUST conform to +<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, +that is, an URL is a string in the form: +</p> + +<blockquote> +<tt> +[ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][<i>type</i>=a|i]</tt> +</blockquote> + +<p> +The following constants in the namespace can be set to control the default behavior of +the FTP module: +</p> + +<ul> +<li> <tt>PASSWORD</tt>: default anonymous password. +<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; +<li> <tt>USER</tt>: default anonymous user; +</ul> + + +<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=get> +ftp.<b>get(</b>url<b>)</b><br> +ftp.<b>get{</b><br> + host = <i>string</i>,<br> + sink = <i>LTN12 sink</i>,<br> + argument <i>or</i> path = <i>string</i>,<br> + [user = <i>string</i>,]<br> + [password = <i>string</i>]<br> + [command = <i>string</i>,]<br> + [port = <i>number</i>,]<br> + [type = <i>string</i>,]<br> + [step = <i>LTN12 pump step</i>,]<br> + [create = <i>function</i>]<br> +<b>}</b> +</p> + +<p class=description> +The <tt>get</tt> function has two forms. The simple form has fixed +functionality: it downloads the contents of a URL and returns it as a +string. The generic form allows a <em>lot</em> more control, as explained +below. +</p> + +<p class=parameters> +If the argument of the <tt>get</tt> function is a table, the function +expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of +<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes +precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is +the <em>simple</em> +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +sink that will receive the downloaded data. <tt>Argument</tt> or +<tt>path</tt> give the target path to the resource in the server. The +optional arguments are the following: +</p> +<ul> +<li><tt>user</tt>, <tt>password</tt>: User name and password used for +authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; +<li><tt>command</tt>: The FTP command used to obtain data. Defaults to +"<tt>retr</tt>", but see example below; +<li><tt>port</tt>: The port to used for the control connection. Defaults to 21; +<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or +"<tt>a</tt>". Defaults to whatever is the server default; +<li><tt>step</tt>: +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +pump step function used to pass data from the +server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; +<li><tt>create</tt>: An optional function to be used instead of +<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. +</ul> + +<p class=return> +If successful, the simple version returns the URL contents as a +string, and the generic function returns 1. In case of error, both +functions return <b><tt>nil</tt></b> and an error message describing the +error. +</p> + +<pre class=example> +-- load the ftp support +local ftp = require("socket.ftp") + +-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br", +-- and get file "lua.tar.gz" from directory "pub/lua" as binary. +f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i") +</pre> + +<pre class=example> +-- load needed modules +local ftp = require("socket.ftp") +local ltn12 = require("ltn12") +local url = require("socket.url") + +-- a function that returns a directory listing +function nlst(u) + local t = {} + local p = url.parse(u) + p.command = "nlst" + p.sink = ltn12.sink.table(t) + local r, e = ftp.get(p) + return r and table.concat(t), e +end +</pre> + +<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=put> +ftp.<b>put(</b>url, content<b>)</b><br> +ftp.<b>put{</b><br> + host = <i>string</i>,<br> + source = <i>LTN12 sink</i>,<br> + argument <i>or</i> path = <i>string</i>,<br> + [user = <i>string</i>,]<br> + [password = <i>string</i>]<br> + [command = <i>string</i>,]<br> + [port = <i>number</i>,]<br> + [type = <i>string</i>,]<br> + [step = <i>LTN12 pump step</i>,]<br> + [create = <i>function</i>]<br> +<b>}</b> +</p> + +<p class=description> +The <tt>put</tt> function has two forms. The simple form has fixed +functionality: it uploads a string of content into a URL. The generic form +allows a <em>lot</em> more control, as explained below. +</p> + +<p class=parameters> +If the argument of the <tt>put</tt> function is a table, the function +expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of +<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes +precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is +the <em>simple</em> +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +source that will provide the contents to be uploaded. +<tt>Argument</tt> or +<tt>path</tt> give the target path to the resource in the server. The +optional arguments are the following: +</p> +<ul> +<li><tt>user</tt>, <tt>password</tt>: User name and password used for +authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; +<li><tt>command</tt>: The FTP command used to send data. Defaults to +"<tt>stor</tt>", but see example below; +<li><tt>port</tt>: The port to used for the control connection. Defaults to 21; +<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or +"<tt>a</tt>". Defaults to whatever is the server default; +<li><tt>step</tt>: +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +pump step function used to pass data from the +server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; +<li><tt>create</tt>: An optional function to be used instead of +<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. +</ul> + +<p class=return> +Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error +message describing the reason for failure. +</p> + +<pre class=example> +-- load the ftp support +local ftp = require("socket.ftp") + +-- Log as user "fulano" on server "ftp.example.com", +-- using password "silva", and store a file "README" with contents +-- "wrong password, of course" +f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README", + "wrong password, of course") +</pre> + +<pre class=example> +-- load the ftp support +local ftp = require("socket.ftp") +local ltn12 = require("ltn12") + +-- Log as user "fulano" on server "ftp.example.com", +-- using password "silva", and append to the remote file "LOG", sending the +-- contents of the local file "LOCAL-LOG" +f, e = ftp.put{ + host = "ftp.example.com", + user = "fulano", + password = "silva", + command = "appe", + argument = "LOG", + source = ltn12.source.file(io.open("LOCAL-LOG", "r")) +} +</pre> + + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:25:18 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/http.html b/ThirdParty/luasocket/doc/http.html new file mode 100644 index 0000000..78f785a --- /dev/null +++ b/ThirdParty/luasocket/doc/http.html @@ -0,0 +1,337 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: HTTP support"> +<meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support"> +<title>LuaSocket: HTTP support</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="introduction.html">introduction</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id="http">HTTP</h2> + +<p> +HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange +information between web-browsers and servers. The <tt>http</tt> +namespace offers full support for the client side of the HTTP +protocol (i.e., +the facilities that would be used by a web-browser implementation). The +implementation conforms to the HTTP/1.1 standard, +<a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>. +</p> + +<p> +The module exports functions that provide HTTP functionality in different +levels of abstraction. From the simple +string oriented requests, through generic +<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. +</p> + +<p> +To obtain the <tt>http</tt> namespace, run: +</p> + +<pre class=example> +-- loads the HTTP module and any libraries it requires +local http = require("socket.http") +</pre> + +<p> +URLs must conform to +<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, +that is, an URL is a string in the form: +</p> + +<blockquote> +<pre> +[http://][<user>[:<password>]@]<host>[:<port>][/<path>] +</pre> +</blockquote> + +<p> +MIME headers are represented as a Lua table in the form: +</p> + +<blockquote> +<table summary="MIME headers in Lua table"> +<tr><td><tt> +headers = {<br> + field-1-name = <i>field-1-value</i>,<br> + field-2-name = <i>field-2-value</i>,<br> + field-3-name = <i>field-3-value</i>,<br> + ...<br> + field-n-name = <i>field-n-value</i><br> +} +</tt></td></tr> +</table> +</blockquote> + +<p> +Field names are case insensitive (as specified by the standard) and all +functions work with lowercase field names (but see +<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). +Field values are left unmodified. +</p> + +<p class=note> +Note: MIME headers are independent of order. Therefore, there is no problem +in representing them in a Lua table. +</p> + +<p> +The following constants can be set to control the default behavior of +the HTTP module: +</p> + +<ul> +<li> <tt>PROXY</tt>: default proxy used for connections; +<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; +<li> <tt>USERAGENT</tt>: default user agent reported to server. +</ul> + +<p class=note id="post"> +Note: These constants are global. Changing them will also +change the behavior other code that might be using LuaSocket. +</p> + +<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="request"> +http.<b>request(</b>url [, body]<b>)</b><br> +http.<b>request{</b><br> + url = <i>string</i>,<br> + [sink = <i>LTN12 sink</i>,]<br> + [method = <i>string</i>,]<br> + [headers = <i>header-table</i>,]<br> + [source = <i>LTN12 source</i>],<br> + [step = <i>LTN12 pump step</i>,]<br> + [proxy = <i>string</i>,]<br> + [redirect = <i>boolean</i>,]<br> + [create = <i>function</i>,]<br> + [maxredirects = <i>number</i>]<br> +<b>}</b> +</p> + +<p class=description> +The request function has two forms. The simple form downloads +a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based +on strings. The generic form performs any HTTP method and is +<a href=http://lua-users.org/wiki/FiltersSourcesAndSinks>LTN12</a> based. +</p> + +<p class=parameters> +If the first argument of the <tt>request</tt> function is a string, it +should be an <tt>url</tt>. In that case, if a <tt>body</tt> +is provided as a string, the function will perform a <tt>POST</tt> method +in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the +<tt>url</tt> +</p> + +<p class=parameters> +If the first argument is instead a table, the most important fields are +the <tt>url</tt> and the <em>simple</em> +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +<tt>sink</tt> that will receive the downloaded content. +Any part of the <tt>url</tt> can be overridden by including +the appropriate field in the request table. +If authentication information is provided, the function +uses the Basic Authentication Scheme (see <a href="#authentication">note</a>) +to retrieve the document. If <tt>sink</tt> is <tt><b>nil</b></tt>, the +function discards the downloaded data. The optional parameters are the +following: +</p> +<ul> +<li><tt>method</tt>: The HTTP request method. Defaults to "GET"; +<li><tt>headers</tt>: Any additional HTTP headers to send with the request; +<li><tt>source</tt>: <em>simple</em> +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +source to provide the request body. If there +is a body, you need to provide an appropriate "<tt>content-length</tt>" +request header field, or the function will attempt to send the body as +"<tt>chunked</tt>" (something few servers support). Defaults to the empty source; +<li><tt>step</tt>: +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +pump step function used to move data. +Defaults to the LTN12 <tt>pump.step</tt> function. +<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy; +<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the +function from automatically following 301 or 302 server redirect messages; +<li><tt>create</tt>: An optional function to be used instead of +<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. +<li><tt>maxredirects</tt>: An optional number specifying the maximum number of redirects to follow. Defaults to <tt>5</tt> if not specified. A boolean <tt>false</tt> value means no maximum (unlimited). +</ul> + +<p class=return> +In case of failure, the function returns <tt><b>nil</b></tt> followed by an +error message. If successful, the simple form returns the response +body as a string, followed by the response status code, the response +headers and the response status line. The generic function returns the same +information, except the first return value is just the number 1 (the body +goes to the <tt>sink</tt>). +</p> + +<p class=return> +Even when the server fails to provide the contents of the requested URL (URL not found, for example), +it usually returns a message body (a web page informing the +URL was not found or some other useless page). To make sure the +operation was successful, check the returned status <tt>code</tt>. For +a list of the possible values and their meanings, refer to <a +href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>. +</p> + +<p class=description> +Here are a few examples with the simple interface: +</p> + +<pre class=example> +-- load the http module +local io = require("io") +local http = require("socket.http") +local ltn12 = require("ltn12") + +-- connect to server "www.cs.princeton.edu" and retrieves this manual +-- file from "~diego/professional/luasocket/http.html" and print it to stdout +http.request{ + url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html", + sink = ltn12.sink.file(io.stdout) +} + +-- connect to server "www.example.com" and tries to retrieve +-- "/private/index.html". Fails because authentication is needed. +b, c, h = http.request("http://www.example.com/private/index.html") +-- b returns some useless page telling about the denied access, +-- h returns authentication information +-- and c returns with value 401 (Authentication Required) + +-- tries to connect to server "wrong.host" to retrieve "/" +-- and fails because the host does not exist. +r, e = http.request("http://wrong.host/") +-- r is nil, and e returns with value "host not found" +</pre> + +<p class=description> +And here is an example using the generic interface: +</p> + +<pre class=example> +-- load the http module +http = require("socket.http") + +-- Requests information about a document, without downloading it. +-- Useful, for example, if you want to display a download gauge and need +-- to know the size of the document in advance +r, c, h = http.request { + method = "HEAD", + url = "http://www.tecgraf.puc-rio.br/~diego" +} +-- r is 1, c is 200, and h would return the following headers: +-- h = { +-- date = "Tue, 18 Sep 2001 20:42:21 GMT", +-- server = "Apache/1.3.12 (Unix) (Red Hat/Linux)", +-- ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT", +-- ["content-length"] = 15652, +-- ["connection"] = "close", +-- ["content-Type"] = "text/html" +-- } +</pre> + +<p class=note id="post"> +Note: When sending a POST request, simple interface adds a +"<tt>Content-type: application/x-www-form-urlencoded</tt>" +header to the request. This is the type used by +HTML forms. If you need another type, use the generic +interface. +</p> + +<p class=note id="authentication"> +Note: Some URLs are protected by their +servers from anonymous download. For those URLs, the server must receive +some sort of authentication along with the request or it will deny +download and return status "401 Authentication Required". +</p> + +<p class=note> +The HTTP/1.1 standard defines two authentication methods: the Basic +Authentication Scheme and the Digest Authentication Scheme, both +explained in detail in +<a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>. +</p> + +<p class=note>The Basic Authentication Scheme sends +<tt><user></tt> and +<tt><password></tt> unencrypted to the server and is therefore +considered unsafe. Unfortunately, by the time of this implementation, +the wide majority of servers and browsers support the Basic Scheme only. +Therefore, this is the method used by the toolkit whenever +authentication is required. +</p> + +<pre class=example> +-- load required modules +http = require("socket.http") +mime = require("mime") + +-- Connect to server "www.example.com" and tries to retrieve +-- "/private/index.html", using the provided name and password to +-- authenticate the request +b, c, h = http.request("http://fulano:silva@www.example.com/private/index.html") + +-- Alternatively, one could fill the appropriate header and authenticate +-- the request directly. +r, c = http.request { + url = "http://www.example.com/private/index.html", + headers = { authorization = "Basic " .. (mime.b64("fulano:silva")) } +} +</pre> + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Eric Westbrook on <br> +Sat Feb 23 19:09:42 UTC 2019 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/index.html b/ThirdParty/luasocket/doc/index.html new file mode 100644 index 0000000..7d81b41 --- /dev/null +++ b/ThirdParty/luasocket/doc/index.html @@ -0,0 +1,215 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="The LuaSocket Homepage"> +<meta name="keywords" content="Lua, LuaSocket, Network, Library, Support, Internet"> +<title>LuaSocket: Network support for the Lua language </title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=whatis>What is LuaSocket?</h2> + +<p> +LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library +that is composed by two parts: a C core that provides support for the TCP +and UDP transport layers, and a set of Lua modules that add support for +functionality commonly needed by applications that deal with the Internet. +</p> + +<p> +The core support has been implemented so that it is both efficient and +simple to use. It is available to any Lua application once it has been +properly initialized by the interpreter in use. The code has been tested +and runs well on several Windows and UNIX platforms. </p> + +<p> +Among the support modules, the most commonly used implement the +<a href=smtp.html>SMTP</a> +(sending e-mails), +<a href=http.html>HTTP</a> +(WWW access) and +<a href=ftp.html>FTP</a> +(uploading and downloading files) client +protocols. These provide a very natural and generic interface to the +functionality defined by each protocol. +In addition, you will find that the +<a href=mime.html>MIME</a> (common encodings), +<a href=url.html>URL</a> +(anything you could possible want to do with one) and +<a href=ltn12.html>LTN12</a> +(filters, sinks, sources and pumps) modules can be very handy. +</p> + +<p> +The library is available under the same +<a href="http://www.lua.org/copyright.html"> +terms and conditions</a> as the Lua language, the MIT license. The idea is +that if you can use Lua in a project, you should also be able to use +LuaSocket. +</p> + +<p> +Copyright © 1999-2013 Diego Nehab. All rights reserved. <br> +Author: <A href="http://www.impa.br/~diego">Diego Nehab</a> +</p> + +<!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=download>Download</h2> + +<p> +LuaSocket version 3.0-rc1 is now available for download! +It is compatible with Lua 5.1 and 5.2, and has +been tested on Windows XP, Linux, and Mac OS X. Chances +are it works well on most UNIX distributions and Windows flavors. +</p> + +<p> +The current version of the library can be found at +the <a href="https://github.com/diegonehab/luasocket">LuaSocket +project page</a> on GitHub. Besides the full C and Lua source code +for the library, the distribution contains several examples, +this user's manual and basic test procedures. +</p> + +<p> Take a look at the <a +href=installation.html>installation</a> section of the +manual to find out how to properly install the library. +</p> + +<!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=thanks>Special thanks</h2> + +<p> +This marks the first release of LuaSocket that +wholeheartedly embraces the open-source development +philosophy. After a long hiatus, Matthew Wild finally +convinced me it was time for a release including IPv6 and +Lua 5.2 support. It was more work than we anticipated. +Special thanks to Sam Roberts, Florian Zeitz, and Paul +Aurich, Liam Devine, Alexey Melnichuk, and everybody else +that has helped bring this library back to life. +</p> + +<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=new>What's New</h2> + +<p> +Main changes for LuaSocket 3.0-rc1 are IPv6 support +and Lua 5.2 compatibility. +</p> + +<ul> +<li> Added: Compatible with Lua 5.2 +<ul> +<li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>, +package tables will <em>not</em> be exported as globals! +</ul> +<li> Added: IPv6 support; +<ul> +<li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses; +<li> <tt>Getpeername</tt> and <tt>getsockname</tt> support +IPv6 addresses, and return the socket family as a third value; +<li> URL module updated to support IPv6 host names; +<li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions; +<li> New <tt>socket.dns.getaddrinfo</tt> and + <tt>socket.dns.getnameinfo</tt> functions; +</ul> +<li> Added: <tt>getoption</tt> method; +<li> Fixed: <tt>url.unescape</tt> was returning additional values; +<li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>, + <tt>mime.b64</tt>, and <tt>mime.unb64</tt> could + mistaking their own stack slots for functions arguments; +<li> Fixed: Receiving zero-length datagram is now possible; +<li> Improved: Hidden all internal library symbols; +<li> Improved: Better error messages; +<li> Improved: Better documentation of socket options. +<li> Fixed: manual sample of HTTP authentication now uses correct + "authorization" header (Alexandre Ittner); +<li> Fixed: failure on bind() was destroying the socket (Sam Roberts); +<li> Fixed: receive() returns immediatelly if prefix can satisfy + bytes requested (M Joonas Pihlaja); +<li> Fixed: multicast didn't work on Windows, or anywhere + else for that matter (Herbert Leuwer, Adrian Sietsma); +<li> Fixed: select() now reports an error when called with more + sockets than FD_SETSIZE (Lorenzo Leonini); +<li> Fixed: manual links to home.html changed to index.html +(Robert Hahn); +<li> Fixed: mime.unb64() would return an empty string on results that started + with a null character (Robert Raschke); +<li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray); +<li> Fixed: calling sleep() with negative numbers could + block forever, wasting CPU. Now it returns immediately (MPB); +<li> Improved: FTP commands are now sent in upper case to + help buggy servers (Anders Eurenius); +<li> Improved: known headers now sent in canonic + capitalization to help buggy servers (Joseph Stewart); +<li> Improved: Clarified tcp:receive() in the manual (MPB); +<li> Improved: Decent makefiles (LHF). +<li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei). +</ul> + +<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=old>Old Versions</h2> + +<p> +All previous versions of the LuaSocket library can be downloaded <a +href="http://www.impa.br/~diego/software/luasocket/old"> +here</a>. Although these versions are no longer supported, they are +still available for those that have compatibility issues. +</p> + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Tue Jun 11 18:50:23 HKT 2013 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/installation.html b/ThirdParty/luasocket/doc/installation.html new file mode 100644 index 0000000..28a9fbb --- /dev/null +++ b/ThirdParty/luasocket/doc/installation.html @@ -0,0 +1,127 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: Introduction to the core"> +<meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network, Support, +Installation"> +<title>LuaSocket: Installation</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- installation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2>Installation</h2> + +<p> Here we describe the standard distribution. If the +standard doesn't meet your needs, we refer you to the Lua +discussion list, where any question about the package scheme +will likely already have been answered. </p> + +<h3>Directory structure</h3> + +<p> On Unix systems, the standard distribution uses two base +directories, one for system dependent files, and another for system +independent files. Let's call these directories <tt><CDIR></tt> +and <tt><LDIR></tt>, respectively. +For example, in my laptp, Lua 5.1 is configured to +use '<tt>/usr/local/lib/lua/5.1</tt>' for +<tt><CDIR></tt> and '<tt>/usr/local/share/lua/5.1</tt>' for +<tt><LDIR></tt>. On Windows, <tt><CDIR></tt> +usually points to the directory where the Lua executable is +found, and <tt><LDIR></tt> points to a +<tt>lua/</tt> directory inside <tt><CDIR></tt>. (These +settings can be overridden by environment variables +<tt>LUA_PATH</tt> and <tt>LUA_CPATH</tt>. See the Lua +documentation for details.) Here is the standard LuaSocket +distribution directory structure:</p> + +<pre class=example> +<LDIR>/ltn12.lua +<LDIR>/socket.lua +<CDIR>/socket/core.dll +<LDIR>/socket/http.lua +<LDIR>/socket/tp.lua +<LDIR>/socket/ftp.lua +<LDIR>/socket/smtp.lua +<LDIR>/socket/url.lua +<LDIR>/mime.lua +<CDIR>/mime/core.dll +</pre> + +<p> Naturally, on Unix systems, <tt>core.dll</tt> +would be replaced by <tt>core.so</tt>. +</p> + +<h3>Using LuaSocket</h3> + +<p> With the above setup, and an interpreter with shared library support, +it should be easy to use LuaSocket. Just fire the interpreter and use the +<tt>require</tt> function to gain access to whatever module you need:</p> + +<pre class=example> +Lua 5.2.2 Copyright (C) 1994-2013 Lua.org, PUC-Rio +> socket = require("socket") +> print(socket._VERSION) +--> LuaSocket 3.0-rc1 +</pre> + +<p> Each module loads their dependencies automatically, so you only need to +load the modules you directly depend upon: </p> + +<pre class=example> +Lua 5.2.2 Copyright (C) 1994-2013 Lua.org, PUC-Rio +> http = require("socket.http") +> print(http.request("http://www.impa.br/~diego/software/luasocket")) +--> homepage gets dumped to terminal +</pre> + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Tue Jun 11 19:06:14 HKT 2013 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/introduction.html b/ThirdParty/luasocket/doc/introduction.html new file mode 100644 index 0000000..fd22f48 --- /dev/null +++ b/ThirdParty/luasocket/doc/introduction.html @@ -0,0 +1,333 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: Introduction to the core"> +<meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network, +Library, Support"> +<title>LuaSocket: Introduction to the core</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2>Introduction</h2> + +<p> +LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library +that is composed by two parts: a C core that provides support for the TCP +and UDP transport layers, and a set of Lua modules that add support for +the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and +downloading files) protocols and other functionality commonly needed by +applications that deal with the Internet. This introduction is about the C +core. +</p> + +<p> +Communication in LuaSocket is performed via I/O objects. These can +represent different network domains. Currently, support is provided for TCP +and UDP, but nothing prevents other developers from implementing SSL, Local +Domain, Pipes, File Descriptors etc. I/O objects provide a standard +interface to I/O across different domains and operating systems. +</p> + +<p> +The API design had two goals in mind. First, users +experienced with the C API to sockets should feel comfortable using LuaSocket. +Second, the simplicity and the feel of the Lua language should be +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. +</p> + + +<p> +One of the simplifications is the receive pattern capability. +Applications can read data from stream domains (such as TCP) +line by line, block by block, or until the connection is closed. +All I/O reads are buffered and the performance differences between +different receive patterns are negligible. +</p> + +<p> +Another advantage is the flexible timeout control +mechanism. As in C, all I/O operations are blocking by default. For +example, the <a href=tcp.html#send><tt>send</tt></a>, +<a href=tcp.html#receive><tt>receive</tt></a> and +<a href=tcp.html#accept><tt>accept</tt></a> methods +of the TCP domain will block the caller application until +the operation is completed (if ever!). However, with a call to the +<a href=tcp.html#settimeout><tt>settimeout</tt></a> +method, an application can specify upper limits on +the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on +the time LuaSocket can internally be blocked by any OS call (the +"<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket +call might perform several OS calls, so that the two timeout values are +<em>not</em> equivalent. +</p> + +<p> +Finally, the host name resolution is transparent, meaning that most +functions and methods accept both IP addresses and host names. In case a +host name is given, the library queries the system's resolver and +tries the main IP address returned. Note that direct use of IP addresses +is more efficient, of course. The +<a href=dns.html#toip><tt>toip</tt></a> +and <a href=dns.html#tohostname><tt>tohostname</tt></a> +functions from the DNS module are provided to convert between host names and IP addresses. +</p> + +<p> +Together, these changes make network programming in LuaSocket much simpler +than it is in C, as the following sections will show. +</p> + +<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h3 id=tcp>TCP</h3> + +<p> +TCP (Transfer Control Protocol) is reliable stream protocol. In other +words, applications communicating through TCP can send and receive data as +an error free stream of bytes. Data is split in one end and +reassembled transparently on the other end. There are no boundaries in +the data transfers. The library allows users to read data from the +sockets in several different granularities: patterns are available for +lines, arbitrary sized blocks or "read up to connection closed", all with +good performance. +</p> + +<p> +The library distinguishes three types of TCP sockets: <em>master</em>, +<em>client</em> and <em>server</em> sockets. +</p> + +<p> +Master sockets are newly created TCP sockets returned by the function +<a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is +transformed into a server socket +after it is associated with a <em>local</em> address by a call to the +<a href=tcp.html#bind><tt>bind</tt></a> method followed by a call to the +<a href=tcp.html#listen><tt>listen</tt></a>. Conversely, a master socket +can be changed into a client socket with the method +<a href=tcp.html#connect><tt>connect</tt></a>, +which associates it with a <em>remote</em> address. +</p> + +<p> +On server sockets, applications can use the +<a href=tcp.html#accept><tt>accept</tt></a> method +to wait for a client connection. Once a connection is established, a +client socket object is returned representing this connection. The +other methods available for server socket objects are +<a href=tcp.html#getsockname><tt>getsockname</tt></a>, +<a href=tcp.html#setoption><tt>setoption</tt></a>, +<a href=tcp.html#settimeout><tt>settimeout</tt></a>, and +<a href=tcp.html#close><tt>close</tt></a>. +</p> + +<p> +Client sockets are used to exchange data between two applications over +the Internet. Applications can call the methods +<a href=tcp.html#send><tt>send</tt></a> and +<a href=tcp.html#receive><tt>receive</tt></a> +to send and receive data. The other methods +available for client socket objects are +<a href=tcp.html#getsockname><tt>getsockname</tt></a>, +<a href=tcp.html#getpeername><tt>getpeername</tt></a>, +<a href=tcp.html#setoption><tt>setoption</tt></a>, +<a href=tcp.html#settimeout><tt>settimeout</tt></a>, +<a href=tcp.html#shutdown><tt>shutdown</tt></a>, and +<a href=tcp.html#close><tt>close</tt></a>. +</p> + +<p> +Example: +</p> +<blockquote> +<p> +A simple echo server, using LuaSocket. The program binds to an ephemeral +port (one that is chosen by the operating system) on the local host and +awaits client connections on that port. When a connection is established, +the program reads a line from the remote end and sends it back, closing +the connection immediately. You can test it using the telnet +program. +</p> + +<pre class=example> +-- load namespace +local socket = require("socket") +-- create a TCP socket and bind it to the local host, at any port +local server = assert(socket.bind("*", 0)) +-- find out which port the OS chose for us +local ip, port = server:getsockname() +-- print a message informing what's up +print("Please telnet to localhost on port " .. port) +print("After connecting, you have 10s to enter a line to be echoed") +-- loop forever waiting for clients +while 1 do + -- wait for a connection from any client + local client = server:accept() + -- make sure we don't block waiting for this client's line + client:settimeout(10) + -- receive the line + local line, err = client:receive() + -- if there was no error, send it back to the client + if not err then client:send(line .. "\n") end + -- done with client, close the object + client:close() +end +</pre> +</blockquote> + +<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h3 id=udp>UDP</h3> + +<p> +UDP (User Datagram Protocol) is a non-reliable datagram protocol. In +other words, applications communicating through UDP send and receive +data as independent blocks, which are not guaranteed to reach the other +end. Even when they do reach the other end, they are not guaranteed to be +error free. Data transfers are atomic, one datagram at a time. Reading +only part of a datagram discards the rest, so that the following read +operation will act on the next datagram. The advantages are in +simplicity (no connection setup) and performance (no error checking or +error correction). +</p> + +<p> +Note that although no guarantees are made, these days +networks are so good that, under normal circumstances, few errors +happen in practice. +</p> + +<p> +An UDP socket object is created by the +<a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP +sockets do not need to be connected before use. The method +<a href=udp.html#sendto><tt>sendto</tt></a> +can be used immediately after creation to +send a datagram to IP address and port. Host names are not allowed +because performing name resolution for each packet would be forbiddingly +slow. Methods +<a href=udp.html#receive><tt>receive</tt></a> and +<a href=udp.html#receivefrom><tt>receivefrom</tt></a> +can be used to retrieve datagrams, the latter returning the IP and port of +the sender as extra return values (thus being slightly less +efficient). +</p> + +<p> +When communication is performed repeatedly with a single peer, an +application should call the +<a href=udp.html#setpeername><tt>setpeername</tt></a> method to specify a +permanent partner. Methods +<a href=udp.html#sendto><tt>sendto</tt></a> and +<a href=udp.html#receivefrom><tt>receivefrom</tt></a> +can no longer be used, but the method +<a href=udp.html#send><tt>send</tt></a> can be used to send data +directly to the peer, and the method +<a href=udp.html#receive><tt>receive</tt></a> +will only return datagrams originating +from that peer. There is about 30% performance gain due to this practice. +</p> + +<p> +To associate an UDP socket with a local address, an application calls the +<a href=udp.html#setsockname><tt>setsockname</tt></a> +method <em>before</em> sending any datagrams. Otherwise, the socket is +automatically bound to an ephemeral address before the first data +transmission and once bound the local address cannot be changed. +The other methods available for UDP sockets are +<a href=udp.html#getpeername><tt>getpeername</tt></a>, +<a href=udp.html#getsockname><tt>getsockname</tt></a>, +<a href=udp.html#settimeout><tt>settimeout</tt></a>, +<a href=udp.html#setoption><tt>setoption</tt></a> and +<a href=udp.html#close><tt>close</tt></a>. +</p> + +<p> +Example: +</p> +<blockquote> +<p> +A simple daytime client, using LuaSocket. The program connects to a remote +server and tries to retrieve the daytime, printing the answer it got or an +error message. +</p> + +<pre class=example> +-- change here to the host an port you want to contact +local host, port = "localhost", 13 +-- load namespace +local socket = require("socket") +-- convert host name to ip address +local ip = assert(socket.dns.toip(host)) +-- create a new UDP object +local udp = assert(socket.udp()) +-- contact daytime host +assert(udp:sendto("anything", ip, port)) +-- retrieve the answer and print results +io.write(assert(udp:receive())) +</pre> +</blockquote> + +<!-- More +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h3 id=more>Support modules</h3> + +<p> Although not covered in the introduction, LuaSocket offers +much more than TCP and UDP functionality. As the library +evolved, support for <a href=http.html>HTTP</a>, <a href=ftp.html>FTP</a>, +and <a href=smtp.html>SMTP</a> were built on top of these. These modules +and many others are covered by the <a href=reference.html>reference manual</a>. +</p> + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:25:36 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/ltn12.html b/ThirdParty/luasocket/doc/ltn12.html new file mode 100644 index 0000000..ee2502f --- /dev/null +++ b/ThirdParty/luasocket/doc/ltn12.html @@ -0,0 +1,440 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: LTN12 support"> +<meta name="keywords" content="Lua, LuaSocket, Filters, Source, Sink, +Pump, Support, Library"> +<title>LuaSocket: LTN12 module</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=ltn12>LTN12</h2> + +<p> The <tt>ltn12</tt> namespace implements the ideas described in +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> +LTN012, Filters sources and sinks</a>. This manual simply describes the +functions. Please refer to the LTN for a deeper explanation of the +functionality provided by this module. +</p> + +<p> +To obtain the <tt>ltn12</tt> namespace, run: +</p> + +<pre class=example> +-- loads the LTN21 module +local ltn12 = require("ltn12") +</pre> + +<!-- filters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h3 id="filter">Filters</h3> + +<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="filter.chain"> +ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub> +[, ... filter<sub>N</sub>]<b>)</b> +</p> + +<p class=description> +Returns a filter that passes all data it receives through each of a +series of given filters. +</p> + +<p class=parameters> +<tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple +filters. +</p> + +<p class=return> +The function returns the chained filter. +</p> + +<p class=note> +The nesting of filters can be arbitrary. For instance, the useless filter +below doesn't do anything but return the data that was passed to it, +unaltered. +</p> + +<pre class=example> +-- load required modules +local ltn12 = require("ltn12") +local mime = require("mime") + +-- create a silly identity filter +id = ltn12.filter.chain( + mime.encode("quoted-printable"), + mime.encode("base64"), + mime.decode("base64"), + mime.decode("quoted-printable") +) +</pre> + +<!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="filter.cycle"> +ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b> +</p> + +<p class=description> +Returns a high-level filter that cycles though a low-level filter by +passing it each chunk and updating a context between calls. +</p> + +<p class=parameters> +<tt>Low</tt> is the low-level filter to be cycled, +<tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra +argument the low-level filter might take. +</p> + +<p class=return> +The function returns the high-level filter. +</p> + +<pre class=example> +-- load the ltn12 module +local ltn12 = require("ltn12") + +-- the base64 mime filter factory +encodet['base64'] = function() + return ltn12.filter.cycle(b64, "") +end +</pre> + +<!-- pumps ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h3 id="pump">Pumps</h3> + +<!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="pump.all"> +ltn12.pump.<b>all(</b>source, sink<b>)</b> +</p> + +<p class=description> +Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>. +</p> + +<p class=return> +If successful, the function returns a value that evaluates to +<b><tt>true</tt></b>. In case +of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. +</p> + +<!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="pump.step"> +ltn12.pump.<b>step(</b>source, sink<b>)</b> +</p> + +<p class=description> +Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>. +</p> + +<p class=return> +If successful, the function returns a value that evaluates to +<b><tt>true</tt></b>. In case +of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. +</p> + +<!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h3 id="sink">Sinks</h3> + +<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="sink.chain"> +ltn12.sink.<b>chain(</b>filter, sink<b>)</b> +</p> + +<p class=description> +Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>. +</p> + +<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="sink.error"> +ltn12.sink.<b>error(</b>message<b>)</b> +</p> + +<p class=description> +Creates and returns a sink that aborts transmission with the error +<tt>message</tt>. +</p> + +<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="sink.file"> +ltn12.sink.<b>file(</b>handle, message<b>)</b> +</p> + +<p class=description> +Creates a sink that sends data to a file. +</p> + +<p class=parameters> +<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, +<tt>message</tt> should give the reason for failure. +</p> + +<p class=return> +The function returns a sink that sends all data to the given <tt>handle</tt> +and closes the file when done, or a sink that aborts the transmission with +the error <tt>message</tt> +</p> + +<p class=note> +In the following example, notice how the prototype is designed to +fit nicely with the <tt>io.open</tt> function. +</p> + +<pre class=example> +-- load the ltn12 module +local ltn12 = require("ltn12") + +-- copy a file +ltn12.pump.all( + ltn12.source.file(io.open("original.png", "rb")), + ltn12.sink.file(io.open("copy.png", "wb")) +) +</pre> + +<!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="sink.null"> +ltn12.sink.<b>null()</b> +</p> + +<p class=description> +Returns a sink that ignores all data it receives. +</p> + +<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="sink.simplify"> +ltn12.sink.<b>simplify(</b>sink<b>)</b> +</p> + +<p class=description> +Creates and returns a simple sink given a fancy <tt>sink</tt>. +</p> + +<!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="sink.table"> +ltn12.sink.<b>table(</b>[table]<b>)</b> +</p> + +<p class=description> +Creates a sink that stores all chunks in a table. The chunks can later be +efficiently concatenated into a single string. +</p> + +<p class=parameters> +<tt>Table</tt> is used to hold the chunks. If +<tt><b>nil</b></tt>, the function creates its own table. +</p> + +<p class=return> +The function returns the sink and the table used to store the chunks. +</p> + +<pre class=example> +-- load needed modules +local http = require("socket.http") +local ltn12 = require("ltn12") + +-- a simplified http.get function +function http.get(u) + local t = {} + local respt = request{ + url = u, + sink = ltn12.sink.table(t) + } + return table.concat(t), respt.headers, respt.code +end +</pre> + +<!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h3 id="source">Sources</h3> + +<!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="source.cat"> +ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ..., +source<sub>N</sub>]<b>)</b> +</p> + +<p class=description> +Creates a new source that produces the concatenation of the data produced +by a number of sources. +</p> + +<p class=parameters> +<tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original +sources. +</p> + +<p class=return> +The function returns the new source. +</p> + +<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="source.chain"> +ltn12.source.<b>chain(</b>source, filter<b>)</b> +</p> + +<p class=description> +Creates a new <tt>source</tt> that passes data through a <tt>filter</tt> +before returning it. +</p> + +<p class=return> +The function returns the new source. +</p> + +<!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="source.empty"> +ltn12.source.<b>empty()</b> +</p> + +<p class=description> +Creates and returns an empty source. +</p> + +<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="source.error"> +ltn12.source.<b>error(</b>message<b>)</b> +</p> + +<p class=description> +Creates and returns a source that aborts transmission with the error +<tt>message</tt>. +</p> + +<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="source.file"> +ltn12.source.<b>file(</b>handle, message<b>)</b> +</p> + +<p class=description> +Creates a source that produces the contents of a file. +</p> + +<p class=parameters> +<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, +<tt>message</tt> should give the reason for failure. +</p> + +<p class=return> +The function returns a source that reads chunks of data from +given <tt>handle</tt> and returns it to the user, +closing the file when done, or a source that aborts the transmission with +the error <tt>message</tt> +</p> + +<p class=note> +In the following example, notice how the prototype is designed to +fit nicely with the <tt>io.open</tt> function. +</p> + +<pre class=example> +-- load the ltn12 module +local ltn12 = require("ltn12") + +-- copy a file +ltn12.pump.all( + ltn12.source.file(io.open("original.png", "rb")), + ltn12.sink.file(io.open("copy.png", "wb")) +) +</pre> + +<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="source.simplify"> +ltn12.source.<b>simplify(</b>source<b>)</b> +</p> + +<p class=description> +Creates and returns a simple source given a fancy <tt>source</tt>. +</p> + +<!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="source.string"> +ltn12.source.<b>string(</b>string<b>)</b> +</p> + +<p class=description> +Creates and returns a source that produces the contents of a +<tt>string</tt>, chunk by chunk. +</p> + +<!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="source.table"> +ltn12.source.<b>table(</b>table<b>)</b> +</p> + +<p class=description> +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. +</p> + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:25:41 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/lua05.ppt b/ThirdParty/luasocket/doc/lua05.ppt Binary files differnew file mode 100644 index 0000000..e2b7ab4 --- /dev/null +++ b/ThirdParty/luasocket/doc/lua05.ppt diff --git a/ThirdParty/luasocket/doc/luasocket.png b/ThirdParty/luasocket/doc/luasocket.png Binary files differnew file mode 100644 index 0000000..d24a954 --- /dev/null +++ b/ThirdParty/luasocket/doc/luasocket.png diff --git a/ThirdParty/luasocket/doc/mime.html b/ThirdParty/luasocket/doc/mime.html new file mode 100644 index 0000000..8cb3507 --- /dev/null +++ b/ThirdParty/luasocket/doc/mime.html @@ -0,0 +1,477 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: MIME support"> +<meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support"> +<title>LuaSocket: MIME module</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=mime>MIME</h2> + +<p> +The <tt>mime</tt> namespace offers filters that apply and remove common +content transfer encodings, such as Base64 and Quoted-Printable. +It also provides functions to break text into lines and change +the end-of-line convention. +MIME is described mainly in +<a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>, +<a href="http://www.ietf.org/rfc/rfc2046.txt">2046</a>, +<a href="http://www.ietf.org/rfc/rfc2047.txt">2047</a>, +<a href="http://www.ietf.org/rfc/rfc2047.txt">2048</a>, and +<a href="http://www.ietf.org/rfc/rfc2048.txt">2049</a>. +</p> + +<p> +All functionality provided by the MIME module +follows the ideas presented in +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> +LTN012, Filters sources and sinks</a>. +</p> + +<p> +To obtain the <tt>mime</tt> namespace, run: +</p> + +<pre class=example> +-- loads the MIME module and everything it requires +local mime = require("mime") +</pre> + + +<!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h3 id=high>High-level filters</h3> + + +<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="decode"> +mime.<b>decode(</b>"base64"<b>)</b><br> +mime.<b>decode(</b>"quoted-printable"<b>)</b> +</p> + +<p class=description> +Returns a filter that decodes data from a given transfer content +encoding. +</p> + +<!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="encode"> +mime.<b>encode(</b>"base64"<b>)</b><br> +mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b> +</p> + +<p class=description> +Returns a filter that encodes data according to a given transfer content +encoding. +</p> + +<p class=parameters> +In the Quoted-Printable case, the user can specify whether the data is +textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or +"<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>". +</p> + +<p class=note> +Although both transfer content encodings specify a limit for the line +length, the encoding filters do <em>not</em> break text into lines (for +added flexibility). +Below is a filter that converts binary data to the Base64 transfer content +encoding and breaks it into lines of the correct size. +</p> + +<pre class=example> +base64 = ltn12.filter.chain( + mime.encode("base64"), + mime.wrap("base64") +) +</pre> + +<p class=note> +Note: Text data <em>has</em> to be converted to canonic form +<em>before</em> being encoded. +</p> + +<pre class=example> +base64 = ltn12.filter.chain( + mime.normalize(), + mime.encode("base64"), + mime.wrap("base64") +) +</pre> + +<!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="normalize"> +mime.<b>normalize(</b>[marker]<b>)</b> +</p> + +<p class=description> +Converts most common end-of-line markers to a specific given marker. +</p> + +<p class=parameters> +<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic +end-of-line marker defined by the MIME standard. +</p> + +<p class=return> +The function returns a filter that performs the conversion. +</p> + +<p class=note> +Note: There is no perfect solution to this problem. Different end-of-line +markers are an evil that will probably plague developers forever. +This function, however, will work perfectly for text created with any of +the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF), +or the DOS (CRLF) conventions. Even if the data has mixed end-of-line +markers, the function will still work well, although it doesn't +guarantee that the number of empty lines will be correct. +</p> + +<!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="stuff"> +mime.<b>stuff()</b><br> +</p> + +<p class=description> +Creates and returns a filter that performs stuffing of SMTP messages. +</p> + +<p class=note> +Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function +uses this filter automatically. You don't need to chain it with your +source, or apply it to your message body. +</p> + +<!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="wrap"> +mime.<b>wrap(</b>"text" [, length]<b>)</b><br> +mime.<b>wrap(</b>"base64"<b>)</b><br> +mime.<b>wrap(</b>"quoted-printable"<b>)</b> +</p> + +<p class=description> +Returns a filter that breaks data into lines. +</p> + +<p class=parameters> +The "<tt>text</tt>" line-wrap filter simply breaks text into lines by +inserting CRLF end-of-line markers at appropriate positions. +<tt>Length</tt> defaults 76. +The "<tt>base64</tt>" line-wrap filter works just like the default +"<tt>text</tt>" line-wrap filter with default length. +The function can also wrap "<tt>quoted-printable</tt>" lines, taking care +not to break lines in the middle of an escaped character. In that case, the +line length is fixed at 76. +</p> + +<p class=note> +For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following: +</p> + +<pre class=example> +qp = ltn12.filter.chain( + mime.normalize(), + mime.encode("quoted-printable"), + mime.wrap("quoted-printable") +) +</pre> + +<p class=note> +Note: To break into lines with a different end-of-line convention, apply +a normalization filter after the line break filter. +</p> + +<!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h3 id=low>Low-level filters</h3> + +<!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="b64"> +A, B = mime.<b>b64(</b>C [, D]<b>)</b> +</p> + +<p class=description> +Low-level filter to perform Base64 encoding. +</p> + +<p class=description> +<tt>A</tt> is the encoded version of the largest prefix of +<tt>C..D</tt> +that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of +<tt>C..D</tt>, <em>before</em> encoding. +If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with +the encoding of the remaining bytes of <tt>C</tt>. +</p> + +<p class=note> +Note: The simplest use of this function is to encode a string into it's +Base64 transfer content encoding. Notice the extra parenthesis around the +call to <tt>mime.b64</tt>, to discard the second return value. +</p> + +<pre class=example> +print((mime.b64("diego:password"))) +--> ZGllZ286cGFzc3dvcmQ= +</pre> + +<!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> +<p class=name id="dot"> +A, n = mime.<b>dot(</b>m [, B]<b>)</b> +</p> + +<p class=description> +Low-level filter to perform SMTP stuffing and enable transmission of +messages containing the sequence "CRLF.CRLF". +</p> + +<p class=parameters> +<tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the +number of characters from the sequence CRLF seen in the end of <tt>B</tt>. +'<tt>m</tt>' should tell the same, but for the previous chunk. +</p> + +<p class=note>Note: The message body is defined to begin with +an implicit CRLF. Therefore, to stuff a message correctly, the +first <tt>m</tt> should have the value 2. +</p> + +<pre class=example> +print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n"))) +--> ..\nStuffing the message.\n..\n.. +</pre> + +<p class=note> +Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function +uses this filter automatically. You don't need to +apply it again. +</p> + +<!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="eol"> +A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b> +</p> + +<p class=description> +Low-level filter to perform end-of-line marker translation. +For each chunk, the function needs to know if the last character of the +previous chunk could be part of an end-of-line marker or not. This is the +context the function receives besides the chunk. An updated version of +the context is returned after each new chunk. +</p> + +<p class=parameters> +<tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the +ASCII value of the last character of the previous chunk, if it was a +candidate for line break, or 0 otherwise. +<tt>B</tt> is the same as <tt>C</tt>, but for the current +chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF. +</p> + +<pre class=example> +-- translates the end-of-line marker to UNIX +unix = mime.eol(0, dos, "\n") +</pre> + +<!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="qp"> +A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b> +</p> + +<p class=description> +Low-level filter to perform Quoted-Printable encoding. +</p> + +<p class=parameters> +<tt>A</tt> is the encoded version of the largest prefix of +<tt>C..D</tt> +that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of +<tt>C..D</tt>, <em>before</em> encoding. +If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with +the encoding of the remaining bytes of <tt>C</tt>. +Throughout encoding, occurrences of CRLF are replaced by the +<tt>marker</tt>, which itself defaults to CRLF. +</p> + +<p class=note> +Note: The simplest use of this function is to encode a string into it's +Quoted-Printable transfer content encoding. +Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value. +</p> + +<pre class=example> +print((mime.qp("maçã"))) +--> ma=E7=E3= +</pre> + +<!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="qpwrp"> +A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b> +</p> + +<p class=description> +Low-level filter to break Quoted-Printable text into lines. +</p> + +<p class=parameters> +<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most +<tt>length</tt> bytes (defaults to 76). +'<tt>n</tt>' should tell how many bytes are left for the first +line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes +left in the last line of <tt>A</tt>. +</p> + +<p class=note> +Note: Besides breaking text into lines, this function makes sure the line +breaks don't fall in the middle of an escaped character combination. Also, +this function only breaks lines that are bigger than <tt>length</tt> bytes. +</p> + +<!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="unb64"> +A, B = mime.<b>unb64(</b>C [, D]<b>)</b> +</p> + +<p class=description> +Low-level filter to perform Base64 decoding. +</p> + +<p class=parameters> +<tt>A</tt> is the decoded version of the largest prefix of +<tt>C..D</tt> +that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of +<tt>C..D</tt>, <em>before</em> decoding. +If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string +and <tt>B</tt> returns whatever couldn't be decoded. +</p> + +<p class=note> +Note: The simplest use of this function is to decode a string from it's +Base64 transfer content encoding. +Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. +</p> + +<pre class=example> +print((mime.unb64("ZGllZ286cGFzc3dvcmQ="))) +--> diego:password +</pre> + +<!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="unqp"> +A, B = mime.<b>unqp(</b>C [, D]<b>)</b> +</p> + +<p class=description> +Low-level filter to remove the Quoted-Printable transfer content encoding +from data. +</p> + +<p class=parameters> +<tt>A</tt> is the decoded version of the largest prefix of +<tt>C..D</tt> +that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of +<tt>C..D</tt>, <em>before</em> decoding. +If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with +the encoding of the remaining bytes of <tt>C</tt>. +</p> + +<p class=note> +Note: The simplest use of this function is to decode a string from it's +Quoted-Printable transfer content encoding. +Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. +</p> + +<pre class=example> +print((mime.qp("ma=E7=E3="))) +--> maçã +</pre> + +<!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="wrp"> +A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b> +</p> + +<p class=description> +Low-level filter to break text into lines with CRLF marker. +Text is assumed to be in the <a href=#normalize><tt>normalize</tt></a> form. +</p> + +<p class=parameters> +<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most +<tt>length</tt> bytes (defaults to 76). +'<tt>n</tt>' should tell how many bytes are left for the first +line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes +left in the last line of <tt>A</tt>. +</p> + +<p class=note> +Note: This function only breaks lines that are bigger than +<tt>length</tt> bytes. The resulting line length does not include the CRLF +marker. +</p> + + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Fri Mar 4 15:19:17 BRT 2016 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/reference.css b/ThirdParty/luasocket/doc/reference.css new file mode 100644 index 0000000..04e38cf --- /dev/null +++ b/ThirdParty/luasocket/doc/reference.css @@ -0,0 +1,55 @@ +body { + margin-left: 1em; + margin-right: 1em; + font-family: "Verdana", sans-serif; + background: #ffffff; +} + +tt { + font-family: "Andale Mono", monospace; +} + +h1, h2, h3, h4 { margin-left: 0em; } + + +h3 { padding-top: 1em; } + +p { margin-left: 1em; } + +p.name { + font-family: "Andale Mono", monospace; + padding-top: 1em; + margin-left: 0em; +} + +a[href] { color: #00007f; } + +blockquote { margin-left: 3em; } + +pre.example { + background: #ccc; + padding: 1em; + margin-left: 1em; + font-family: "Andale Mono", monospace; + font-size: small; +} + +hr { + margin-left: 0em; + background: #00007f; + border: 0px; + height: 1px; +} + +ul { list-style-type: disc; } + +table.index { border: 1px #00007f; } +table.index td { text-align: left; vertical-align: top; } +table.index ul { padding-top: 0em; margin-top: 0em; } + +h1:first-letter, +h2:first-letter, +h2:first-letter, +h3:first-letter { color: #00007f; } + +div.header, div.footer { margin-left: 0em; } diff --git a/ThirdParty/luasocket/doc/reference.html b/ThirdParty/luasocket/doc/reference.html new file mode 100644 index 0000000..163a8a2 --- /dev/null +++ b/ThirdParty/luasocket/doc/reference.html @@ -0,0 +1,261 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: Index to reference manual"> +<meta name="keywords" content="Lua, LuaSocket, Index, Manual, Network, Library, +Support, Manual"> +<title>LuaSocket: Index to reference manual</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- reference +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2>Reference</h2> + +<blockquote> +<a href="dns.html">DNS (in socket)</a> +<blockquote> +<a href="dns.html#getaddrinfo">getaddrinfo</a>, +<a href="dns.html#gethostname">gethostname</a>, +<a href="dns.html#tohostname">tohostname</a>, +<a href="dns.html#toip">toip</a>. +</blockquote> +</blockquote> + +<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<blockquote> +<a href="ftp.html">FTP</a> +<blockquote> +<a href="ftp.html#get">get</a>, +<a href="ftp.html#put">put</a>. +</blockquote> +</blockquote> + +<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<blockquote> +<a href="http.html">HTTP</a> +<blockquote> +<a href="http.html#request">request</a>. +</blockquote> +</blockquote> + +<!-- ltn12 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<blockquote> +<a href="ltn12.html">LTN12</a> +<blockquote> +<a href="ltn12.html#filter">filter</a>: +<a href="ltn12.html#filter.chain">chain</a>, +<a href="ltn12.html#filter.cycle">cycle</a>. +</blockquote> +<blockquote> +<a href="ltn12.html#pump">pump</a>: +<a href="ltn12.html#pump.all">all</a>, +<a href="ltn12.html#pump.step">step</a>. +</blockquote> +<blockquote> +<a href="ltn12.html#sink">sink</a>: +<a href="ltn12.html#sink.chain">chain</a>, +<a href="ltn12.html#sink.error">error</a>, +<a href="ltn12.html#sink.file">file</a>, +<a href="ltn12.html#sink.null">null</a>, +<a href="ltn12.html#sink.simplify">simplify</a>, +<a href="ltn12.html#sink.table">table</a>. +</blockquote> +<blockquote> +<a href="ltn12.html#source">source</a>: +<a href="ltn12.html#source.cat">cat</a>, +<a href="ltn12.html#source.chain">chain</a>, +<a href="ltn12.html#source.empty">empty</a>, +<a href="ltn12.html#source.error">error</a>, +<a href="ltn12.html#source.file">file</a>, +<a href="ltn12.html#source.simplify">simplify</a>, +<a href="ltn12.html#source.string">string</a>, +<a href="ltn12.html#source.table">table</a>. +</blockquote> +</blockquote> + +<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<blockquote> +<a href="mime.html">MIME</a> +<blockquote> +<a href="mime.html#high">high-level</a>: +<a href="mime.html#decode">decode</a>, +<a href="mime.html#encode">encode</a>, +<a href="mime.html#normalize">normalize</a>, +<a href="mime.html#stuff">stuff</a>, +<a href="mime.html#wrap">wrap</a>. +</blockquote> +<blockquote> +<a href="mime.html#low">low-level</a>: +<a href="mime.html#b64">b64</a>, +<a href="mime.html#dot">dot</a>, +<a href="mime.html#eol">eol</a>, +<a href="mime.html#qp">qp</a>, +<a href="mime.html#qpwrp">qpwrp</a>, +<a href="mime.html#unb64">unb64</a>, +<a href="mime.html#unqp">unqp</a>, +<a href="mime.html#wrp">wrp</a>. +</blockquote> +</blockquote> + +<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<blockquote> +<a href="smtp.html">SMTP</a> +<blockquote> +<a href="smtp.html#message">message</a>, +<a href="smtp.html#send">send</a>. +</blockquote> +</blockquote> + +<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<blockquote> +<a href="socket.html">Socket</a> +<blockquote> +<a href="socket.html#bind">bind</a>, +<a href="socket.html#connect">connect</a>, +<a href="socket.html#connect">connect4</a>, +<a href="socket.html#connect">connect6</a>, +<a href="socket.html#datagramsize">_DATAGRAMSIZE</a>, +<a href="socket.html#debug">_DEBUG</a>, +<a href="dns.html#dns">dns</a>, +<a href="socket.html#gettime">gettime</a>, +<a href="socket.html#headers.canonic">headers.canonic</a>, +<a href="socket.html#newtry">newtry</a>, +<a href="socket.html#protect">protect</a>, +<a href="socket.html#select">select</a>, +<a href="socket.html#sink">sink</a>, +<a href="socket.html#skip">skip</a>, +<a href="socket.html#sleep">sleep</a>, +<a href="socket.html#setsize">_SETSIZE</a>, +<a href="socket.html#socketinvalid">_SOCKETINVALID</a>, +<a href="socket.html#source">source</a>, +<a href="tcp.html#socket.tcp">tcp</a>, +<a href="tcp.html#socket.tcp4">tcp4</a>, +<a href="tcp.html#socket.tcp6">tcp6</a>, +<a href="socket.html#try">try</a>, +<a href="udp.html#socket.udp">udp</a>, +<a href="udp.html#socket.udp4">udp4</a>, +<a href="udp.html#socket.udp6">udp6</a>, +<a href="socket.html#version">_VERSION</a>. +</blockquote> +</blockquote> + +<!-- tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<blockquote> +<a href="tcp.html">TCP (in socket)</a> +<blockquote> +<a href="tcp.html#accept">accept</a>, +<a href="tcp.html#bind">bind</a>, +<a href="tcp.html#close">close</a>, +<a href="tcp.html#connect">connect</a>, +<a href="tcp.html#dirty">dirty</a>, +<a href="tcp.html#getfd">getfd</a>, +<a href="tcp.html#getoption">getoption</a>, +<a href="tcp.html#getpeername">getpeername</a>, +<a href="tcp.html#getsockname">getsockname</a>, +<a href="tcp.html#getstats">getstats</a>, +<a href="tcp.html#gettimeout">gettimeout</a>, +<a href="tcp.html#listen">listen</a>, +<a href="tcp.html#receive">receive</a>, +<a href="tcp.html#send">send</a>, +<a href="tcp.html#setfd">setfd</a>, +<a href="tcp.html#setoption">setoption</a>, +<a href="tcp.html#setstats">setstats</a>, +<a href="tcp.html#settimeout">settimeout</a>, +<a href="tcp.html#shutdown">shutdown</a>. +</blockquote> +</blockquote> + +<!-- udp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<blockquote> +<a href="udp.html">UDP (in socket)</a> +<blockquote> +<a href="udp.html#close">close</a>, +<a href="udp.html#getoption">getoption</a>, +<a href="udp.html#getpeername">getpeername</a>, +<a href="udp.html#getsockname">getsockname</a>, +<a href="udp.html#gettimeout">gettimeout</a>, +<a href="udp.html#receive">receive</a>, +<a href="udp.html#receivefrom">receivefrom</a>, +<a href="udp.html#send">send</a>, +<a href="udp.html#sendto">sendto</a>, +<a href="udp.html#setpeername">setpeername</a>, +<a href="udp.html#setsockname">setsockname</a>, +<a href="udp.html#setoption">setoption</a>, +<a href="udp.html#settimeout">settimeout</a>. +</blockquote> +</blockquote> + +<!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<blockquote> +<a href="url.html">URL</a> +<blockquote> +<a href="url.html#absolute">absolute</a>, +<a href="url.html#build">build</a>, +<a href="url.html#build_path">build_path</a>, +<a href="url.html#escape">escape</a>, +<a href="url.html#parse">parse</a>, +<a href="url.html#parse_path">parse_path</a>, +<a href="url.html#unescape">unescape</a>. +</blockquote> +</blockquote> + +<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:25:47 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/smtp.html b/ThirdParty/luasocket/doc/smtp.html new file mode 100644 index 0000000..600ec37 --- /dev/null +++ b/ThirdParty/luasocket/doc/smtp.html @@ -0,0 +1,418 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: SMTP support"> +<meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart, +Library, Support"> +<title>LuaSocket: SMTP support</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=smtp>SMTP</h2> + +<p> The <tt>smtp</tt> namespace provides functionality to send e-mail +messages. The high-level API consists of two functions: one to +define an e-mail message, and another to actually send the message. +Although almost all users will find that these functions provide more than +enough functionality, the underlying implementation allows for even more +control (if you bother to read the code). +</p> + +<p>The implementation conforms to the Simple Mail Transfer Protocol, +<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a>. +Another RFC of interest is <a +href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>, +which governs the Internet Message Format. +Multipart messages (those that contain attachments) are part +of the MIME standard, but described mainly +in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a> + +<p> In the description below, good understanding of <a +href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters +sources and sinks</a> and the <a href=mime.html>MIME</a> module is +assumed. In fact, the SMTP module was the main reason for their +creation. </p> + +<p> +To obtain the <tt>smtp</tt> namespace, run: +</p> + +<pre class=example> +-- loads the SMTP module and everything it requires +local smtp = require("socket.smtp") +</pre> + +<p> +MIME headers are represented as a Lua table in the form: +</p> + +<blockquote> +<table summary="MIME headers in Lua table"> +<tr><td><tt> +headers = {<br> + field-1-name = <i>field-1-value</i>,<br> + field-2-name = <i>field-2-value</i>,<br> + field-3-name = <i>field-3-value</i>,<br> + ...<br> + field-n-name = <i>field-n-value</i><br> +} +</tt></td></tr> +</table> +</blockquote> + +<p> +Field names are case insensitive (as specified by the standard) and all +functions work with lowercase field names (but see +<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). +Field values are left unmodified. +</p> + +<p class=note> +Note: MIME headers are independent of order. Therefore, there is no problem +in representing them in a Lua table. +</p> + +<p> +The following constants can be set to control the default behavior of +the SMTP module: +</p> + +<ul> +<li> <tt>DOMAIN</tt>: domain used to greet the server; +<li> <tt>PORT</tt>: default port used for the connection; +<li> <tt>SERVER</tt>: default server used for the connection; +<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations; +<li> <tt>ZONE</tt>: default time zone. +</ul> + +<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=message> +smtp.<b>message(</b>mesgt<b>)</b> +</p> + +<p class=description> +Returns a <em>simple</em> +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep). +</p> + +<p class=parameters> +The only parameter of the function is a table describing the message. +<tt>Mesgt</tt> has the following form (notice the recursive structure): +</p> + +<blockquote> +<table summary="Mesgt table structure"> +<tr><td><tt> +mesgt = {<br> + headers = <i>header-table</i>,<br> + body = <i>LTN12 source</i> or <i>string</i> or +<i>multipart-mesgt</i><br> +}<br> + <br> +multipart-mesgt = {<br> + [preamble = <i>string</i>,]<br> + [1] = <i>mesgt</i>,<br> + [2] = <i>mesgt</i>,<br> + ...<br> + [<i>n</i>] = <i>mesgt</i>,<br> + [epilogue = <i>string</i>,]<br> +}<br> +</tt></td></tr> +</table> +</blockquote> + +<p class=parameters> +For a simple message, all that is needed is a set of <tt>headers</tt> +and the <tt>body</tt>. The message <tt>body</tt> can be given as a string +or as a <em>simple</em> +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +source. For multipart messages, the body is a table that +recursively defines each part as an independent message, plus an optional +<tt>preamble</tt> and <tt>epilogue</tt>. +</p> + +<p class=return> +The function returns a <em>simple</em> +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +source that produces the +message contents as defined by <tt>mesgt</tt>, chunk by chunk. +Hopefully, the following +example will make things clear. When in doubt, refer to the appropriate RFC +as listed in the introduction. </p> + +<pre class=example> +-- load the smtp support and its friends +local smtp = require("socket.smtp") +local mime = require("mime") +local ltn12 = require("ltn12") + +-- creates a source to send a message with two parts. The first part is +-- plain text, the second part is a PNG image, encoded as base64. +source = smtp.message{ + headers = { + -- Remember that headers are *ignored* by smtp.send. + from = "Sicrano de Oliveira <sicrano@example.com>", + to = "Fulano da Silva <fulano@example.com>", + subject = "Here is a message with attachments" + }, + body = { + preamble = "If your client doesn't understand attachments, \r\n" .. + "it will still display the preamble and the epilogue.\r\n" .. + "Preamble will probably appear even in a MIME enabled client.", + -- first part: no headers means plain text, us-ascii. + -- The mime.eol low-level filter normalizes end-of-line markers. + [1] = { + body = mime.eol(0, [[ + Lines in a message body should always end with CRLF. + The smtp module will *NOT* perform translation. However, the + send function *DOES* perform SMTP stuffing, whereas the message + function does *NOT*. + ]]) + }, + -- second part: headers describe content to be a png image, + -- sent under the base64 transfer content encoding. + -- notice that nothing happens until the message is actually sent. + -- small chunks are loaded into memory right before transmission and + -- translation happens on the fly. + [2] = { + headers = { + ["content-type"] = 'image/png; name="image.png"', + ["content-disposition"] = 'attachment; filename="image.png"', + ["content-description"] = 'a beautiful image', + ["content-transfer-encoding"] = "BASE64" + }, + body = ltn12.source.chain( + ltn12.source.file(io.open("image.png", "rb")), + ltn12.filter.chain( + mime.encode("base64"), + mime.wrap() + ) + ) + }, + epilogue = "This might also show up, but after the attachments" + } +} + +-- finally send it +r, e = smtp.send{ + from = "<sicrano@example.com>", + rcpt = "<fulano@example.com>", + source = source, +} +</pre> + + +<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=send> +smtp.<b>send{</b><br> + from = <i>string</i>,<br> + rcpt = <i>string</i> or <i>string-table</i>,<br> + source = <i>LTN12 source</i>,<br> + [user = <i>string</i>,]<br> + [password = <i>string</i>,]<br> + [server = <i>string</i>,]<br> + [port = <i>number</i>,]<br> + [domain = <i>string</i>,]<br> + [step = <i>LTN12 pump step</i>,]<br> + [create = <i>function</i>]<br> +<b>}</b> +</p> + +<p class=description> +Sends a message to a recipient list. Since sending messages is not as +simple as downloading an URL from a FTP or HTTP server, this function +doesn't have a simple interface. However, see the +<a href=#message><tt>message</tt></a> source factory for +a very powerful way to define the message contents. +</p> + + +<p class=parameters> +The sender is given by the e-mail address in the <tt>from</tt> field. +<tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail +address, or a string +in case there is just one recipient. +The contents of the message are given by a <em>simple</em> +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +<tt>source</tt>. Several arguments are optional: +</p> +<ul> +<li> <tt>user</tt>, <tt>password</tt>: User and password for +authentication. The function will attempt LOGIN and PLAIN authentication +methods if supported by the server (both are unsafe); +<li> <tt>server</tt>: Server to connect to. Defaults to "localhost"; +<li> <tt>port</tt>: Port to connect to. Defaults to 25; +<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the +local machine host name; +<li> <tt>step</tt>: +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +pump step function used to pass data from the +source to the server. Defaults to the LTN12 <tt>pump.step</tt> function; +<li><tt>create</tt>: An optional function to be used instead of +<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. +</ul> + +<p class=return> +If successful, the function returns 1. Otherwise, the function returns +<b><tt>nil</tt></b> followed by an error message. +</p> + +<p class=note> +Note: SMTP servers can be very picky with the format of e-mail +addresses. To be safe, use only addresses of the form +"<tt><fulano@example.com></tt>" in the <tt>from</tt> and +<tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail +addresses can take whatever form you like. </p> + +<p class=note> +Big note: There is a good deal of misconception with the use of the +destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>', +and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a +'<tt>Bcc</tt>' header to your messages because it will probably do the +exact opposite of what you expect. +</p> + +<p class=note> +Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the +message. Each recipient of an SMTP mail message receives a copy of the +message body along with the headers, and nothing more. The headers +<em>are</em> part of the message and should be produced by the +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +<tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em> +part of the message and will not be sent to anyone. +</p> + +<p class=note> +<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a> +has two <em>important and short</em> sections, "3.6.3. Destination address +fields" and "5. Security considerations", explaining the proper +use of these headers. Here is a summary of what it says: +</p> + +<ul> +<li> <tt>To</tt>: contains the address(es) of the primary recipient(s) +of the message; +<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of +making a copy on a typewriter using carbon paper) contains the +addresses of others who are to receive the message, though the +content of the message may not be directed at them; +<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon +Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message. +</ul> + +<p class=note> +The LuaSocket <tt>send</tt> function does not care or interpret the +headers you send, but it gives you full control over what is sent and +to whom it is sent: +</p> +<ul> +<li> If someone is to receive the message, the e-mail address <em>has</em> +to be in the recipient list. This is the only parameter that controls who +gets a copy of the message; +<li> If there are multiple recipients, none of them will automatically +know that someone else got that message. That is, the default behavior is +similar to the <tt>Bcc</tt> field of popular e-mail clients; +<li> It is up to you to add the <tt>To</tt> header with the list of primary +recipients so that other recipients can see it; +<li> It is also up to you to add the <tt>Cc</tt> header with the +list of additional recipients so that everyone else sees it; +<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is +empty. Otherwise, everyone receiving the message will see it and that is +exactly what you <em>don't</em> want to happen! +</ul> + +<p class=note> +I hope this clarifies the issue. Otherwise, please refer to +<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a> +and +<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>. +</p> + +<pre class=example> +-- load the smtp support +local smtp = require("socket.smtp") + +-- Connects to server "localhost" and sends a message to users +-- "fulano@example.com", "beltrano@example.com", +-- and "sicrano@example.com". +-- Note that "fulano" is the primary recipient, "beltrano" receives a +-- carbon copy and neither of them knows that "sicrano" received a blind +-- carbon copy of the message. +from = "<luasocket@example.com>" + +rcpt = { + "<fulano@example.com>", + "<beltrano@example.com>", + "<sicrano@example.com>" +} + +mesgt = { + headers = { + to = "Fulano da Silva <fulano@example.com>", + cc = '"Beltrano F. Nunes" <beltrano@example.com>', + subject = "My first message" + }, + body = "I hope this works. If it does, I can send you another 1000 copies." +} + +r, e = smtp.send{ + from = from, + rcpt = rcpt, + source = smtp.message(mesgt) +} +</pre> + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:25:51 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/socket.html b/ThirdParty/luasocket/doc/socket.html new file mode 100644 index 0000000..35f8391 --- /dev/null +++ b/ThirdParty/luasocket/doc/socket.html @@ -0,0 +1,479 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: The core namespace"> +<meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support"> +<title>LuaSocket: The socket namespace</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=socket>The socket namespace</h2> + +<p> +The <tt>socket</tt> namespace contains the core functionality of LuaSocket. +</p> + +<p> +To obtain the <tt>socket</tt> namespace, run: +</p> + +<pre class=example> +-- loads the socket module +local socket = require("socket") +</pre> + +<!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="headers.canonic"> +socket.headers.<b>canonic</b></p> + +<p> The <tt>socket.headers.canonic</tt> table +is used by the HTTP and SMTP modules to translate from +lowercase field names back into their canonic +capitalization. When a lowercase field name exists as a key +in this table, the associated value is substituted in +whenever the field name is sent out. +</p> + +<p> +You can obtain the <tt>headers</tt> namespace if case run-time +modifications are required by running: +</p> + +<pre class=example> +-- loads the headers module +local headers = require("headers") +</pre> + + +<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=bind> +socket.<b>bind(</b>address, port [, backlog]<b>)</b> +</p> + +<p class=description> +This function is a shortcut that creates and returns a TCP server object +bound to a local <tt>address</tt> and <tt>port</tt>, ready to +accept client connections. Optionally, +user can also specify the <tt>backlog</tt> argument to the +<a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32). +</p> + +<p class=note> +Note: The server object returned will have the option "<tt>reuseaddr</tt>" +set to <tt><b>true</b></tt>. +</p> + +<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=connect> +socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b> +</p> + +<p class=description> +This function is a shortcut that creates and returns a TCP client object +connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally, +the user can also specify the local address and port to bind +(<tt>locaddr</tt> and <tt>locport</tt>), or restrict the socket family +to "<tt>inet</tt>" or "<tt>inet6</tt>". +Without specifying <tt>family</tt> to <tt>connect</tt>, whether a tcp or tcp6 +connection is created depends on your system configuration. Two variations +of connect are defined as simple helper functions that restrict the +<tt>family</tt>, <tt>socket.connect4</tt> and <tt>socket.connect6</tt>. +</p> + +<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=debug> +socket.<b>_DEBUG</b> +</p> + +<p class=description> +This constant is set to <tt><b>true</b></tt> if the library was compiled +with debug support. +</p> + +<!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=debug> +socket.<b>_DATAGRAMSIZE</b> +</p> + +<p class=description> +Default datagram size used by calls to +<a href="udp.html#receive"<tt>receive</tt></a> and +<a href="udp.html#receivefrom"><tt>receivefrom</tt></a>. +(Unless changed in compile time, the value is 8192.) +</p> + +<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=gettime> +socket.<b>gettime()</b> +</p> + +<p class=description> +Returns the UNIX time in seconds. You should subtract the values returned by this function +to get meaningful values. +</p> + +<pre class=example> +t = socket.gettime() +-- do stuff +print(socket.gettime() - t .. " seconds elapsed") +</pre> + +<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=newtry> +socket.<b>newtry(</b>finalizer<b>)</b> +</p> + +<p class=description> +Creates and returns a <em>clean</em> +<a href="#try"><tt>try</tt></a> +function that allows for cleanup before the exception +is raised. +</p> + +<p class=parameters> +<tt>Finalizer</tt> is a function that will be called before +<tt>try</tt> throws the exception. +</p> + +<p class=return> +The function returns your customized <tt>try</tt> function. +</p> + +<p class=note> +Note: This idea saved a <em>lot</em> of work with the +implementation of protocols in LuaSocket: +</p> + +<pre class=example> +foo = socket.protect(function() + -- connect somewhere + local c = socket.try(socket.connect("somewhere", 42)) + -- create a try function that closes 'c' on error + local try = socket.newtry(function() c:close() end) + -- do everything reassured c will be closed + try(c:send("hello there?\r\n")) + local answer = try(c:receive()) + ... + try(c:send("good bye\r\n")) + c:close() +end) +</pre> + + +<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=protect> +socket.<b>protect(</b>func<b>)</b> +</p> + +<p class=description> +Converts a function that throws exceptions into a safe function. This +function only catches exceptions thrown by the <a href=#try><tt>try</tt></a> +and <a href=#newtry><tt>newtry</tt></a> functions. It does not catch normal +Lua errors. +</p> + +<p class=parameters> +<tt>Func</tt> is a function that calls +<a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>) +to throw exceptions. +</p> + +<p class=return> +Returns an equivalent function that instead of throwing exceptions in case of +a failed <a href=#try><tt>try</tt></a> call, returns <tt><b>nil</b></tt> +followed by an error message. +</p> + +<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=select> +socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b> +</p> + +<p class=description> +Waits for a number of sockets to change status. +</p> + +<p class=parameters> +<tt>Recvt</tt> is an array with the sockets to test for characters +available for reading. Sockets in the <tt>sendt</tt> array are watched to +see if it is OK to immediately write on them. <tt>Timeout</tt> is the +maximum amount of time (in seconds) to wait for a change in status. A +<tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the +function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also +be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with +non-numeric indices) in the arrays will be silently ignored. +</p> + +<p class=return> The function returns a list with the sockets ready for +reading, a list with the sockets ready for writing and an error message. +The error message is "<tt>timeout</tt>" if a timeout +condition was met, "<tt>select failed</tt>" if the call +to <tt>select</tt> failed, and +<tt><b>nil</b></tt> otherwise. The returned tables are +doubly keyed both by integers and also by the sockets +themselves, to simplify the test if a specific socket has +changed status. +</p> + +<p class=note> +<b>Note:</b> <tt>select</tt> can monitor a limited number +of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This +number may be as high as 1024 or as low as 64 by default, +depending on the system. It is usually possible to change this +at compile time. Invoking <tt>select</tt> with a larger +number of sockets will raise an error. +</p> + +<p class=note> +<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail +on non-blocking TCP sockets. The function may return a socket as +writable even though the socket is <em>not</em> ready for sending. +</p> + +<p class=note> +<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 +<a href=tcp.html#accept><tt>accept</tt></a> will return immediately. +Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a> +method or <tt>accept</tt> might block forever. +</p> + +<p class=note> +<b>Yet another note</b>: If you close a socket and pass +it to <tt>select</tt>, it will be ignored. +</p> + +<p class=note> +<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. +</p> + +<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=setsize> +socket.<b>_SETSIZE</b> +</p> + +<p class=description> +The maximum number of sockets that the <a +href=#select><tt>select</tt></a> function can handle. +</p> + + +<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=sink> +socket.<b>sink(</b>mode, socket<b>)</b> +</p> + +<p class=description> +Creates an +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +sink from a stream socket object. +</p> + +<p class=parameters> +<tt>Mode</tt> defines the behavior of the sink. The following +options are available: +</p> +<ul> +<li> <tt>"http-chunked"</tt>: sends data through socket after applying the +<em>chunked transfer coding</em>, closing the socket when done; +<li> <tt>"close-when-done"</tt>: sends all received data through the +socket, closing the socket when done; +<li> <tt>"keep-open"</tt>: sends all received data through the +socket, leaving it open when done. +</ul> +<p> +<tt>Socket</tt> is the stream socket object used to send the data. +</p> + +<p class=return> +The function returns a sink with the appropriate behavior. +</p> + +<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=skip> +socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> +</p> + +<p class=description> +Drops a number of arguments and returns the remaining. +</p> + +<p class=parameters> +<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to +<tt>ret<sub>N</sub></tt> are the arguments. +</p> + +<p class=return> +The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>. +</p> + +<p class=note> +Note: This function is useful to avoid creation of dummy variables: +</p> + +<pre class=example> +-- get the status code and separator from SMTP server reply +local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)")) +</pre> + +<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=sleep> +socket.<b>sleep(</b>time<b>)</b> +</p> + +<p class=description> +Freezes the program execution during a given amount of time. +</p> + +<p class=parameters> +<tt>Time</tt> is the number of seconds to sleep for. If +<tt>time</tt> is negative, the function returns immediately. +</p> + +<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=source> +socket.<b>source(</b>mode, socket [, length]<b>)</b> +</p> + +<p class=description> +Creates an +<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> +source from a stream socket object. +</p> + +<p class=parameters> +<tt>Mode</tt> defines the behavior of the source. The following +options are available: +</p> +<ul> +<li> <tt>"http-chunked"</tt>: receives data from socket and removes the +<em>chunked transfer coding</em> before returning the data; +<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the +socket. This mode requires the extra argument <tt>length</tt>; +<li> <tt>"until-closed"</tt>: receives data from a socket until the other +side closes the connection. +</ul> +<p> +<tt>Socket</tt> is the stream socket object used to receive the data. +</p> + +<p class=return> +The function returns a source with the appropriate behavior. +</p> + +<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=socketinvalid> +socket.<b>_SOCKETINVALID</b> +</p> + +<p class=description> +The OS value for an invalid socket. +</p> + +<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=try> +socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> +</p> + +<p class=description> +Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using +<tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught +by a <a href=#protect><tt>protect</tt></a>ed function only. +</p> + +<p class=parameters> +<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary +arguments, but are usually the return values of a function call +nested with <tt>try</tt>. +</p> + +<p class=return> +The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if +<tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>. +Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub> wrapped +in a table with metatable used by <a href=#protect><tt>protect</tt></a> to +distinguish exceptions from runtime errors. +</p> + +<pre class=example> +-- connects or throws an exception with the appropriate error message +c = socket.try(socket.connect("localhost", 80)) +</pre> + +<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id=version> +socket.<b>_VERSION</b> +</p> + +<p class=description> +This constant has a string describing the current LuaSocket version. +</p> + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:25:54 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/tcp.html b/ThirdParty/luasocket/doc/tcp.html new file mode 100644 index 0000000..6050a5f --- /dev/null +++ b/ThirdParty/luasocket/doc/tcp.html @@ -0,0 +1,727 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: The TCP/IP support"> +<meta name="keywords" content="Lua, LuaSocket, Socket, TCP, Library, Network, Support"> +<title>LuaSocket: TCP/IP support</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id="tcp">TCP</h2> + +<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="accept"> +server:<b>accept()</b> +</p> + +<p class=description> +Waits for a remote connection on the server +object and returns a client object representing that connection. +</p> + +<p class=return> +If a connection is successfully initiated, a client object is returned. +If a timeout condition is met, the method returns <b><tt>nil</tt></b> +followed by the error string '<tt>timeout</tt>'. Other errors are +reported by <b><tt>nil</tt></b> followed by a message describing the error. +</p> + +<p class=note> +Note: calling <a href=socket.html#select><tt>socket.select</tt></a> +with a server object in +the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does +<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a +href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt> +might block until <em>another</em> client shows up. +</p> + +<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="bind"> +master:<b>bind(</b>address, port<b>)</b> +</p> + +<p class=description> +Binds a master object to <tt>address</tt> and <tt>port</tt> on the +local host. + +<p class=parameters> +<tt>Address</tt> can be an IP address or a host name. +<tt>Port</tt> must be an integer number in the range [0..64K). +If <tt>address</tt> +is '<tt>*</tt>', the system binds to all local interfaces +using the <tt>INADDR_ANY</tt> constant or +<tt>IN6ADDR_ANY_INIT</tt>, according to the family. +If <tt>port</tt> is 0, the system automatically +chooses an ephemeral port. +</p> + +<p class=return> +In case of success, the method returns 1. In case of error, the +method returns <b><tt>nil</tt></b> followed by an error message. +</p> + +<p class=note> +Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a> +is available and is a shortcut for the creation of server sockets. +</p> + +<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="close"> +master:<b>close()</b><br> +client:<b>close()</b><br> +server:<b>close()</b> +</p> + +<p class=description> +Closes a TCP object. The internal socket used by the object is closed +and the local address to which the object was +bound is made available to other applications. No further operations +(except for further calls to the <tt>close</tt> method) are allowed on +a closed socket. +</p> + +<p class=note> +Note: It is important to close all used sockets once they are not +needed, since, in many systems, each socket uses a file descriptor, +which are limited system resources. Garbage-collected objects are +automatically closed before destruction, though. +</p> + +<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="connect"> +master:<b>connect(</b>address, port<b>)</b> +</p> + +<p class=description> +Attempts to connect a master object to a remote host, transforming it into a +client object. +Client objects support methods +<a href=#send><tt>send</tt></a>, +<a href=#receive><tt>receive</tt></a>, +<a href=#getsockname><tt>getsockname</tt></a>, +<a href=#getpeername><tt>getpeername</tt></a>, +<a href=#settimeout><tt>settimeout</tt></a>, +and <a href=#close><tt>close</tt></a>. +</p> + +<p class=parameters> +<tt>Address</tt> can be an IP address or a host name. +<tt>Port</tt> must be an integer number in the range [1..64K). +</p> + +<p class=return> +In case of error, the method returns <b><tt>nil</tt></b> followed by a string +describing the error. In case of success, the method returns 1. +</p> + +<p class=note> +Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a> +is available and is a shortcut for the creation of client sockets. +</p> + +<p class=note> +Note: Starting with LuaSocket 2.0, +the <a href=#settimeout><tt>settimeout</tt></a> +method affects the behavior of <tt>connect</tt>, causing it to return +with an error in case of a timeout. If that happens, you can still call <a +href=socket.html#select><tt>socket.select</tt></a> with the socket in the +<tt>sendt</tt> table. The socket will be writable when the connection is +established. +</p> + +<p class=note> +Note: Starting with LuaSocket 3.0, the host name resolution +depends on whether the socket was created by +<a href=#socket.tcp><tt>socket.tcp</tt></a>, +<a href=#socket.tcp4><tt>socket.tcp4</tt></a> or +<a href=#socket.tcp6><tt>socket.tcp6</tt></a>. Addresses from +the appropriate family (or both) are tried in the order +returned by the resolver until the +first success or until the last failure. If the timeout was +set to zero, only the first address is tried. +</p> + +<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="dirty"> +master:<b>dirty()</b><br> +client:<b>dirty()</b><br> +server:<b>dirty()</b> +</p> + +<p class=description> +Check the read buffer status. +</p> + +<p class=return> +Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise. +</p> + +<p class=note> +Note: <b>This is an internal method, use at your own risk.</b> +</p> + + +<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="getfd"> +master:<b>getfd()</b><br> +client:<b>getfd()</b><br> +server:<b>getfd()</b> +</p> + +<p class=description> +Returns the underling socket descriptor or handle associated to the object. +</p> + +<p class=return> +The descriptor or handle. In case the object has been closed, the return will be -1. +</p> + +<p class=note> +Note: <b>This is an internal method. Unlikely to be +portable. Use at your own risk. </b> +</p> + + +<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="getoption"> +client:<b>getoption(</b>option)</b><br> +server:<b>getoption(</b>option)</b> +</p> + +<p class=description> +Gets options for the TCP object. +See <a href=#setoption><tt>setoption</tt></a> for description of the +option names and values. +</p> + +<p class=parameters> +<tt>Option</tt> is a string with the option name. +<ul> + +<li> '<tt>keepalive</tt>' +<li> '<tt>linger</tt>' +<li> '<tt>reuseaddr</tt>' +<li> '<tt>tcp-nodelay</tt>' +</ul> + +<p class=return> +The method returns the option <tt>value</tt> in case of success, or +<b><tt>nil</tt></b> followed by an error message otherwise. +</p> + + +<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="getpeername"> +client:<b>getpeername()</b> +</p> + +<p class=description> +Returns information about the remote side of a connected client object. +</p> + +<p class=return> +Returns a string with the IP address of the peer, the +port number that peer is using for the connection, +and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). +In case of error, the method returns <b><tt>nil</tt></b>. +</p> + +<p class=note> +Note: It makes no sense to call this method on server objects. +</p> + +<!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="getsockname"> +master:<b>getsockname()</b><br> +client:<b>getsockname()</b><br> +server:<b>getsockname()</b> +</p> + +<p class=description> +Returns the local address information associated to the object. +</p> + +<p class=return> +The method returns a string with local IP address, a number with +the local port, +and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). +In case of error, the method returns <b><tt>nil</tt></b>. +</p> + +<!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="getstats"> +master:<b>getstats()</b><br> +client:<b>getstats()</b><br> +server:<b>getstats()</b><br> +</p> + +<p class=description> +Returns accounting information on the socket, useful for throttling +of bandwidth. +</p> + +<p class=return> +The method returns the number of bytes received, the number of bytes sent, +and the age of the socket object in seconds. +</p> + +<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="gettimeout"> +master:<b>gettimeout()</b><br> +client:<b>gettimeout()</b><br> +server:<b>gettimeout()</b> +</p> + +<p class=description> +Returns the current block timeout followed by the curent +total timeout. +</p> + + +<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="listen"> +master:<b>listen(</b>backlog<b>)</b> +</p> + +<p class=description> +Specifies the socket is willing to receive connections, transforming the +object into a server object. Server objects support the +<a href=#accept><tt>accept</tt></a>, +<a href=#getsockname><tt>getsockname</tt></a>, +<a href=#setoption><tt>setoption</tt></a>, +<a href=#settimeout><tt>settimeout</tt></a>, +and <a href=#close><tt>close</tt></a> methods. +</p> + +<p class=parameters> +The parameter <tt>backlog</tt> specifies the number of client +connections that can +be queued waiting for service. If the queue is full and another client +attempts connection, the connection is refused. +</p> + +<p class=return> +In case of success, the method returns 1. In case of error, the +method returns <b><tt>nil</tt></b> followed by an error message. +</p> + +<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="receive"> +client:<b>receive(</b>[pattern [, prefix]]<b>)</b> +</p> + +<p class=description> +Reads data from a client object, according to the specified <em>read +pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. +</p> + +<p class=parameters> +<tt>Pattern</tt> can be any of the following: +</p> + +<ul> +<li> '<tt>*a</tt>': reads from the socket until the connection is +closed. No end-of-line translation is performed; +<li> '<tt>*l</tt>': reads a line of text from the socket. The line is +terminated by a LF character (ASCII 10), optionally preceded by a +CR character (ASCII 13). The CR and LF characters are not included in +the returned line. In fact, <em>all</em> CR characters are +ignored by the pattern. This is the default pattern; +<li> <tt>number</tt>: causes the method to read a specified <tt>number</tt> +of bytes from the socket. +</ul> + +<p class=parameters> +<tt>Prefix</tt> is an optional string to be concatenated to the beginning +of any received data before return. +</p> + +<p class=return> +If successful, the method returns the received pattern. In case of error, +the method returns <tt><b>nil</b></tt> followed by an error +message, followed by a (possibly empty) string containing +the partial that was received. The error message can be +the string '<tt>closed</tt>' in case the connection was +closed before the transmission was completed or the string +'<tt>timeout</tt>' in case there was a timeout during the operation. +</p> + +<p class=note> +<b>Important note</b>: This function was changed <em>severely</em>. It used +to support multiple patterns (but I have never seen this feature used) and +now it doesn't anymore. Partial results used to be returned in the same +way as successful results. This last feature violated the idea that all +functions should return <tt><b>nil</b></tt> on error. Thus it was changed +too. +</p> + +<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="send"> +client:<b>send(</b>data [, i [, j]]<b>)</b> +</p> + +<p class=description> +Sends <tt>data</tt> through client object. +</p> + +<p class=parameters> +<tt>Data</tt> is the string to be sent. The optional arguments +<tt>i</tt> and <tt>j</tt> work exactly like the standard +<tt>string.sub</tt> Lua function to allow the selection of a +substring to be sent. +</p> + +<p class=return> +If successful, the method returns the index of the last byte +within <tt>[i, j]</tt> that has been sent. Notice that, if +<tt>i</tt> is 1 or absent, this is effectively the total +number of bytes sent. In case of error, the method returns +<b><tt>nil</tt></b>, followed by an error message, followed +by the index of the last byte within <tt>[i, j]</tt> that +has been sent. You might want to try again from the byte +following that. The error message can be '<tt>closed</tt>' +in case the connection was closed before the transmission +was completed or the string '<tt>timeout</tt>' in case +there was a timeout during the operation. +</p> + +<p class=note> +Note: Output is <em>not</em> buffered. For small strings, +it is always better to concatenate them in Lua +(with the '<tt>..</tt>' operator) and send the result in one call +instead of calling the method several times. +</p> + +<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="setoption"> +client:<b>setoption(</b>option [, value]<b>)</b><br> +server:<b>setoption(</b>option [, value]<b>)</b> +</p> + +<p class=description> +Sets options for the TCP object. Options are only needed by low-level or +time-critical applications. You should only modify an option if you +are sure you need it. +</p> + +<p class=parameters> +<tt>Option</tt> is a string with the option name, and <tt>value</tt> +depends on the option being set: + +<ul> + +<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables +the periodic transmission of messages on a connected socket. Should the +connected party fail to respond to these messages, the connection is +considered broken and processes using the socket are notified; + +<li> '<tt>linger</tt>': Controls the action taken when unsent data are +queued on a socket and a close is performed. The value is a table with a +boolean entry '<tt>on</tt>' and a numeric entry for the time interval +'<tt>timeout</tt>' in seconds. If the '<tt>on</tt>' field is set to +<tt>true</tt>, the system will block the process on the close attempt until +it is able to transmit the data or until '<tt>timeout</tt>' has passed. If +'<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will +process the close in a manner that allows the process to continue as +quickly as possible. I do not advise you to set this to anything other than +zero; + +<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules +used in validating addresses supplied in a call to +<a href=#bind><tt>bind</tt></a> should allow reuse of local addresses; + +<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> +disables the Nagle's algorithm for the connection; + +<li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!! + +<li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!! + +<li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!! + +<li> '<tt>ipv6-v6only</tt>': +Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to +sending and receiving only IPv6 packets. +</ul> + +<p class=return> +The method returns 1 in case of success, or <b><tt>nil</tt></b> +followed by an error message otherwise. +</p> + +<p class=note> +Note: The descriptions above come from the man pages. +</p> + +<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="setstats"> +master:<b>setstats(</b>received, sent, age<b>)</b><br> +client:<b>setstats(</b>received, sent, age<b>)</b><br> +server:<b>setstats(</b>received, sent, age<b>)</b><br> +</p> + +<p class=description> +Resets accounting information on the socket, useful for throttling +of bandwidth. +</p> + +<p class=parameters> +<tt>Received</tt> is a number with the new number of bytes received. +<tt>Sent</tt> is a number with the new number of bytes sent. +<tt>Age</tt> is the new age in seconds. +</p> + +<p class=return> +The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise. +</p> + +<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="settimeout"> +master:<b>settimeout(</b>value [, mode]<b>)</b><br> +client:<b>settimeout(</b>value [, mode]<b>)</b><br> +server:<b>settimeout(</b>value [, mode]<b>)</b> +</p> + +<p class=description> +Changes the timeout values for the object. By default, +all I/O operations are blocking. That is, any call to the methods +<a href=#send><tt>send</tt></a>, +<a href=#receive><tt>receive</tt></a>, and +<a href=#accept><tt>accept</tt></a> +will block indefinitely, until the operation completes. The +<tt>settimeout</tt> method defines a limit on the amount of time the +I/O methods can block. When a timeout is set and the specified amount of +time has elapsed, the affected methods give up and fail with an error code. +</p> + +<p class=parameters> +The amount of time to wait is specified as the +<tt>value</tt> parameter, in seconds. There are two timeout modes and +both can be used together for fine tuning: +</p> + +<ul> +<li> '<tt>b</tt>': <em>block</em> timeout. Specifies the upper limit on +the amount of time LuaSocket can be blocked by the operating system +while waiting for completion of any single I/O operation. This is the +default mode;</li> + +<li> '<tt>t</tt>': <em>total</em> timeout. Specifies the upper limit on +the amount of time LuaSocket can block a Lua script before returning from +a call.</li> +</ul> + +<p class=parameters> +The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block +indefinitely. Negative timeout values have the same effect. +</p> + +<p class=note> +Note: although timeout values have millisecond precision in LuaSocket, +large blocks can cause I/O functions not to respect timeout values due +to the time the library takes to transfer blocks to and from the OS +and to and from the Lua interpreter. Also, function that accept host names +and perform automatic name resolution might be blocked by the resolver for +longer than the specified timeout value. +</p> + +<p class=note> +Note: The old <tt>timeout</tt> method is deprecated. The name has been +changed for sake of uniformity, since all other method names already +contained verbs making their imperative nature obvious. +</p> + +<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="shutdown"> +client:<b>shutdown(</b>mode<b>)</b><br> +</p> + +<p class=description> +Shuts down part of a full-duplex connection. +</p> + +<p class=parameters> +Mode tells which way of the connection should be shut down and can +take the value: +<ul> +<li>"<tt>both</tt>": disallow further sends and receives on the object. +This is the default mode; +<li>"<tt>send</tt>": disallow further sends on the object; +<li>"<tt>receive</tt>": disallow further receives on the object. +</ul> + +<p class=return> +This function returns 1. +</p> + +<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="setfd"> +master:<b>setfd(</b>fd<b>)</b><br> +client:<b>setfd(</b>fd<b>)</b><br> +server:<b>setfd(</b>fd<b>)</b> +</p> + +<p class=description> +Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made. +</p> + +<p class=return> +No return value. +</p> + +<p class=note> +Note: <b>This is an internal method. Unlikely to be +portable. Use at your own risk. </b> +</p> + +<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="socket.tcp"> +socket.<b>tcp()</b> +</p> + +<p class=description> +Creates and returns an TCP master object. A master object can +be transformed into a server object with the method +<a href=#listen><tt>listen</tt></a> (after a call to <a +href=#bind><tt>bind</tt></a>) or into a client object with +the method <a href=#connect><tt>connect</tt></a>. The only other +method supported by a master object is the +<a href=#close><tt>close</tt></a> method.</p> + +<p class=return> +In case of success, a new master object is returned. In case of error, +<b><tt>nil</tt></b> is returned, followed by an error message. +</p> + +<p class=note> +Note: The choice between IPv4 and IPv6 happens during a call to +<a href=#bind><tt>bind</tt></a> or <a +href=#bind><tt>connect</tt></a>, depending on the address +family obtained from the resolver. +</p> + +<p class=note> +Note: Before the choice between IPv4 and IPv6 happens, +the internal socket object is invalid and therefore <a +href=#setoption><tt>setoption</tt></a> will fail. +</p> + +<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="socket.tcp4"> +socket.<b>tcp4()</b> +</p> + +<p class=description> +Creates and returns an IPv4 TCP master object. A master object can +be transformed into a server object with the method +<a href=#listen><tt>listen</tt></a> (after a call to <a +href=#bind><tt>bind</tt></a>) or into a client object with +the method <a href=#connect><tt>connect</tt></a>. The only other +method supported by a master object is the +<a href=#close><tt>close</tt></a> method.</p> + +<p class=return> +In case of success, a new master object is returned. In case of error, +<b><tt>nil</tt></b> is returned, followed by an error message. +</p> + +<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="socket.tcp6"> +socket.<b>tcp6()</b> +</p> + +<p class=description> +Creates and returns an IPv6 TCP master object. A master object can +be transformed into a server object with the method +<a href=#listen><tt>listen</tt></a> (after a call to <a +href=#bind><tt>bind</tt></a>) or into a client object with +the method <a href=#connect><tt>connect</tt></a>. The only other +method supported by a master object is the +<a href=#close><tt>close</tt></a> method.</p> + +<p class=return> +In case of success, a new master object is returned. In case of error, +<b><tt>nil</tt></b> is returned, followed by an error message. +</p> + +<p class=note> +Note: The TCP object returned will have the option +"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. +</p> + + + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:25:57 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/udp.html b/ThirdParty/luasocket/doc/udp.html new file mode 100644 index 0000000..4618aad --- /dev/null +++ b/ThirdParty/luasocket/doc/udp.html @@ -0,0 +1,596 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: The UDP support"> +<meta name="keywords" content="Lua, LuaSocket, Socket, UDP, Library, Network, Support"> +<title>LuaSocket: UDP support</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + + +<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id="udp">UDP</h2> + +<!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="close"> +connected:<b>close()</b><br> +unconnected:<b>close()</b> +</p> + +<p class="description"> +Closes a UDP object. The internal socket +used by the object is closed and the local address to which the +object was bound is made available to other applications. No +further operations (except for further calls to the <tt>close</tt> +method) are allowed on a closed socket. +</p> + +<p class="note"> +Note: It is important to close all used sockets +once they are not needed, since, in many systems, each socket uses +a file descriptor, which are limited system resources. +Garbage-collected objects are automatically closed before +destruction, though. +</p> + +<!-- getoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="getoption"> +connected:<b>getoption()</b><br> +unconnected:<b>getoption()</b> +</p> + +<p class="description"> +Gets an option value from the UDP object. +See <a href=#setoption><tt>setoption</tt></a> for +description of the option names and values. +</p> + +<p class="parameters"><tt>Option</tt> is a string with the option name. +<ul> +<li> '<tt>dontroute</tt>' +<li> '<tt>broadcast</tt>' +<li> '<tt>reuseaddr</tt>' +<li> '<tt>reuseport</tt>' +<li> '<tt>ip-multicast-loop</tt>' +<li> '<tt>ipv6-v6only</tt>' +<li> '<tt>ip-multicast-if</tt>' +<li> '<tt>ip-multicast-ttl</tt>' +<li> '<tt>ip-add-membership</tt>' +<li> '<tt>ip-drop-membership</tt>' +</ul> +</p> + +<p class=return> +The method returns the option <tt>value</tt> in case of +success, or +<b><tt>nil</tt></b> followed by an error message otherwise. +</p> + +<!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="getpeername"> +connected:<b>getpeername()</b> +</p> + +<p class="description"> +Retrieves information about the peer +associated with a connected UDP object. +</p> + + +<p class=return> +Returns a string with the IP address of the peer, the +port number that peer is using for the connection, +and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). +In case of error, the method returns <b><tt>nil</tt></b>. +</p> + +<p class="note"> +Note: It makes no sense to call this method on unconnected objects. +</p> + +<!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="getsockname"> +connected:<b>getsockname()</b><br> +unconnected:<b>getsockname()</b> +</p> + +<p class="description"> +Returns the local address information associated to the object. +</p> + + +<p class=return> +The method returns a string with local IP address, a number with +the local port, +and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). +In case of error, the method returns <b><tt>nil</tt></b>. +</p> + +<p class="note"> +Note: UDP sockets are not bound to any address +until the <a href="#setsockname"><tt>setsockname</tt></a> or the +<a href="#sendto"><tt>sendto</tt></a> method is called for the +first time (in which case it is bound to an ephemeral port and the +wild-card address). +</p> + +<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="gettimeout"> +connected:<b>settimeout(</b>value<b>)</b><br> +unconnected:<b>settimeout(</b>value<b>)</b> +</p> + +<p class=description> +Returns the current timeout value. +</p> + + +<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="receive"> +connected:<b>receive(</b>[size]<b>)</b><br> +unconnected:<b>receive(</b>[size]<b>)</b> +</p> + +<p class="description"> +Receives a datagram from the UDP object. If +the UDP object is connected, only datagrams coming from the peer +are accepted. Otherwise, the returned datagram can come from any +host. +</p> + +<p class="parameters"> +The optional <tt>size</tt> parameter +specifies the maximum size of the datagram to be retrieved. If +there are more than <tt>size</tt> bytes available in the datagram, +the excess bytes are discarded. If there are less then +<tt>size</tt> bytes available in the current datagram, the +available bytes are returned. +If <tt>size</tt> is omitted, the +compile-time constant <a +href=socket.html#datagramsize><tt>socket._DATAGRAMSIZE</tt></a> is used +(it defaults to 8192 bytes). Larger sizes will cause a +temporary buffer to be allocated for the operation. +</p> + +<p class="return"> +In case of success, the method returns the +received datagram. In case of timeout, the method returns +<b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'. +</p> + +<!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="receivefrom"> +unconnected:<b>receivefrom(</b>[size]<b>)</b> +</p> + +<p class="description"> +Works exactly as the <a href="#receive"><tt>receive</tt></a> +method, except it returns the IP +address and port as extra return values (and is therefore slightly less +efficient). +</p> + +<!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="send"> +connected:<b>send(</b>datagram<b>)</b> +</p> + +<p class="description"> +Sends a datagram to the UDP peer of a connected object. +</p> + +<p class="parameters"> +<tt>Datagram</tt> is a string with the datagram contents. +The maximum datagram size for UDP is 64K minus IP layer overhead. +However datagrams larger than the link layer packet size will be +fragmented, which may deteriorate performance and/or reliability. +</p> + +<p class="return"> +If successful, the method returns 1. In case of +error, the method returns <b><tt>nil</tt></b> followed by an error message. +</p> + +<p class="note"> +Note: In UDP, the <tt>send</tt> method never blocks +and the only way it can fail is if the underlying transport layer +refuses to send a message to the specified address (i.e. no +interface accepts the address). +</p> + +<!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="sendto"> +unconnected:<b>sendto(</b>datagram, ip, port<b>)</b> +</p> + +<p class="description"> +Sends a datagram to the specified IP address and port number. +</p> + +<p class="parameters"> +<tt>Datagram</tt> is a string with the +datagram contents. +The maximum datagram size for UDP is 64K minus IP layer overhead. +However datagrams larger than the link layer packet size will be +fragmented, which may deteriorate performance and/or reliability. +<tt>Ip</tt> is the IP address of the recipient. +Host names are <em>not</em> allowed for performance reasons. + +<tt>Port</tt> is the port number at the recipient. +</p> + +<p class="return"> +If successful, the method returns 1. In case of +error, the method returns <b><tt>nil</tt></b> followed by an error message. +</p> + +<p class="note"> +Note: In UDP, the <tt>send</tt> method never blocks +and the only way it can fail is if the underlying transport layer +refuses to send a message to the specified address (i.e. no +interface accepts the address). +</p> + +<!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="setoption"> +connected:<b>setoption(</b>option [, value]<b>)</b><br> +unconnected:<b>setoption(</b>option [, value]<b>)</b> +</p> + +<p class="description"> +Sets options for the UDP object. Options are +only needed by low-level or time-critical applications. You should +only modify an option if you are sure you need it.</p> +<p class="parameters"><tt>Option</tt> is a string with the option +name, and <tt>value</tt> depends on the option being set: +</p> + +<ul> +<li> '<tt>dontroute</tt>': Indicates that outgoing +messages should bypass the standard routing facilities. +Receives a boolean value; +<li> '<tt>broadcast</tt>': Requests permission to send +broadcast datagrams on the socket. +Receives a boolean value; +<li> '<tt>reuseaddr</tt>': Indicates that the rules used in +validating addresses supplied in a <tt>bind()</tt> call +should allow reuse of local addresses. +Receives a boolean value; +<li> '<tt>reuseport</tt>': Allows completely duplicate +bindings by multiple processes if they all set +'<tt>reuseport</tt>' before binding the port. +Receives a boolean value; +<li> '<tt>ip-multicast-loop</tt>': +Specifies whether or not a copy of an outgoing multicast +datagram is delivered to the sending host as long as it is a +member of the multicast group. +Receives a boolean value; +<li> '<tt>ipv6-v6only</tt>': +Specifies whether to restrict <tt>inet6</tt> sockets to +sending and receiving only IPv6 packets. +Receive a boolean value; +<li> '<tt>ip-multicast-if</tt>': +Sets the interface over which outgoing multicast datagrams +are sent. +Receives an IP address; +<li> '<tt>ip-multicast-ttl</tt>': +Sets the Time To Live in the IP header for outgoing +multicast datagrams. +Receives a number; +<li> '<tt>ip-add-membership</tt>': +Joins the multicast group specified. +Receives a table with fields +<tt>multiaddr</tt> and <tt>interface</tt>, each containing an +IP address; +<li> '<tt>ip-drop-membership</tt>': Leaves the multicast +group specified. +Receives a table with fields +<tt>multiaddr</tt> and <tt>interface</tt>, each containing an +IP address. +</ul> + +<p class="return"> +The method returns 1 in case of success, or +<b><tt>nil</tt></b> followed by an error message otherwise. +</p> + +<p class=note> +Note: The descriptions above come from the man pages. +</p> + + +<!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="setpeername"> +connected:<b>setpeername(</b>'*'<b>)</b><br> +unconnected:<b>setpeername(</b>address, port<b>)</b> +</p> + +<p class="description"> +Changes the peer of a UDP object. This +method turns an unconnected UDP object into a connected UDP +object or vice versa. +</p> + +<p class="description"> +For connected objects, outgoing datagrams +will be sent to the specified peer, and datagrams received from +other peers will be discarded by the OS. Connected UDP objects must +use the <a href="#send"><tt>send</tt></a> and +<a href="#receive"><tt>receive</tt></a> methods instead of +<a href="#sendto"><tt>sendto</tt></a> and +<a href="#receivefrom"><tt>receivefrom</tt></a>. +</p> + +<p class="parameters"> +<tt>Address</tt> can be an IP address or a +host name. <tt>Port</tt> is the port number. If <tt>address</tt> is +'<tt>*</tt>' and the object is connected, the peer association is +removed and the object becomes an unconnected object again. In that +case, the <tt>port</tt> argument is ignored. +</p> + +<p class="return"> +In case of error the method returns +<b><tt>nil</tt></b> followed by an error message. In case of success, the +method returns 1. +</p> + +<p class="note"> +Note: Since the address of the peer does not have +to be passed to and from the OS, the use of connected UDP objects +is recommended when the same peer is used for several transmissions +and can result in up to 30% performance gains. +</p> + +<p class=note> +Note: Starting with LuaSocket 3.0, the host name resolution +depends on whether the socket was created by <a +href=#socket.udp><tt>socket.udp</tt></a> or <a +href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from +the appropriate family are tried in succession until the +first success or until the last failure. +</p> + +<!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="setsockname"> +unconnected:<b>setsockname(</b>address, port<b>)</b> +</p> + +<p class="description"> +Binds the UDP object to a local address. +</p> + +<p class="parameters"> +<tt>Address</tt> can be an IP address or a +host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to +all local interfaces using the constant <tt>INADDR_ANY</tt>. If +<tt>port</tt> is 0, the system chooses an ephemeral port. +</p> + +<p class="return"> +If successful, the method returns 1. In case of +error, the method returns <b><tt>nil</tt></b> followed by an error +message. +</p> + +<p class="note"> +Note: This method can only be called before any +datagram is sent through the UDP object, and only once. Otherwise, +the system automatically binds the object to all local interfaces +and chooses an ephemeral port as soon as the first datagram is +sent. After the local address is set, either automatically by the +system or explicitly by <tt>setsockname</tt>, it cannot be +changed. +</p> + +<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="settimeout"> +connected:<b>settimeout(</b>value<b>)</b><br> +unconnected:<b>settimeout(</b>value<b>)</b> +</p> + +<p class="description"> +Changes the timeout values for the object. By default, the +<a href="#receive"><tt>receive</tt></a> and +<a href="#receivefrom"><tt>receivefrom</tt></a> +operations are blocking. That is, any call to the methods will block +indefinitely, until data arrives. The <tt>settimeout</tt> function defines +a limit on the amount of time the functions can block. When a timeout is +set and the specified amount of time has elapsed, the affected methods +give up and fail with an error code. +</p> + +<p class="parameters"> +The amount of time to wait is specified as +the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout +<tt>value</tt> allows operations to block indefinitely. Negative +timeout values have the same effect. +</p> + +<p class="note"> +Note: In UDP, the <a href="#send"><tt>send</tt></a> +and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the +datagram is just passed to the OS and the call returns +immediately). Therefore, the <tt>settimeout</tt> method has no +effect on them. +</p> + +<p class="note"> +Note: The old <tt>timeout</tt> method is +deprecated. The name has been changed for sake of uniformity, since +all other method names already contained verbs making their +imperative nature obvious. +</p> + +<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="socket.udp"> +socket.<b>udp()</b> +</p> + +<p class="description"> +Creates and returns an unconnected UDP object. +Unconnected objects support the +<a href="#sendto"><tt>sendto</tt></a>, +<a href="#receive"><tt>receive</tt></a>, +<a href="#receivefrom"><tt>receivefrom</tt></a>, +<a href="#getoption"><tt>getoption</tt></a>, +<a href="#getsockname"><tt>getsockname</tt></a>, +<a href="#setoption"><tt>setoption</tt></a>, +<a href="#settimeout"><tt>settimeout</tt></a>, +<a href="#setpeername"><tt>setpeername</tt></a>, +<a href="#setsockname"><tt>setsockname</tt></a>, and +<a href="#close"><tt>close</tt></a>. +The <a href="#setpeername"><tt>setpeername</tt></a> +is used to connect the object. +</p> + +<p class="return"> +In case of success, a new unconnected UDP object +returned. In case of error, <b><tt>nil</tt></b> is returned, followed by +an error message. +</p> + +<p class=note> +Note: The choice between IPv4 and IPv6 happens during a call to +<a href=#sendto><tt>sendto</tt></a>, <a +href=#setpeername><tt>setpeername</tt></a>, or <a +href=#setsockname><tt>sockname</tt></a>, depending on the address +family obtained from the resolver. +</p> + +<p class=note> +Note: Before the choice between IPv4 and IPv6 happens, +the internal socket object is invalid and therefore <a +href=#setoption><tt>setoption</tt></a> will fail. +</p> + +<!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="socket.udp"> +socket.<b>udp4()</b> +</p> + +<p class="description"> +Creates and returns an unconnected IPv4 UDP object. +Unconnected objects support the +<a href="#sendto"><tt>sendto</tt></a>, +<a href="#receive"><tt>receive</tt></a>, +<a href="#receivefrom"><tt>receivefrom</tt></a>, +<a href="#getoption"><tt>getoption</tt></a>, +<a href="#getsockname"><tt>getsockname</tt></a>, +<a href="#setoption"><tt>setoption</tt></a>, +<a href="#settimeout"><tt>settimeout</tt></a>, +<a href="#setpeername"><tt>setpeername</tt></a>, +<a href="#setsockname"><tt>setsockname</tt></a>, and +<a href="#close"><tt>close</tt></a>. +The <a href="#setpeername"><tt>setpeername</tt></a> +is used to connect the object. +</p> + +<p class="return"> +In case of success, a new unconnected UDP object +returned. In case of error, <b><tt>nil</tt></b> is returned, followed by +an error message. +</p> + +<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="socket.udp6"> +socket.<b>udp6()</b> +</p> + +<p class="description"> +Creates and returns an unconnected IPv6 UDP object. +Unconnected objects support the +<a href="#sendto"><tt>sendto</tt></a>, +<a href="#receive"><tt>receive</tt></a>, +<a href="#receivefrom"><tt>receivefrom</tt></a>, +<a href="#getoption"><tt>getoption</tt></a>, +<a href="#getsockname"><tt>getsockname</tt></a>, +<a href="#setoption"><tt>setoption</tt></a>, +<a href="#settimeout"><tt>settimeout</tt></a>, +<a href="#setpeername"><tt>setpeername</tt></a>, +<a href="#setsockname"><tt>setsockname</tt></a>, and +<a href="#close"><tt>close</tt></a>. +The <a href="#setpeername"><tt>setpeername</tt></a> +is used to connect the object. +</p> + +<p class="return"> +In case of success, a new unconnected UDP object +returned. In case of error, <b><tt>nil</tt></b> is returned, followed by +an error message. +</p> + +<p class=note> +Note: The TCP object returned will have the option +"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. +</p> + + + +<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:26:01 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> diff --git a/ThirdParty/luasocket/doc/url.html b/ThirdParty/luasocket/doc/url.html new file mode 100644 index 0000000..6ff673d --- /dev/null +++ b/ThirdParty/luasocket/doc/url.html @@ -0,0 +1,328 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: URL manipulation"> +<meta name="keywords" content="Lua, LuaSocket, URL, Library, Link, Network, Support"> +<title>LuaSocket: URL support</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + +<!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id="url">URL</h2> + +<p> +The <tt>url</tt> namespace provides functions to parse, protect, +and build URLs, as well as functions to compose absolute URLs +from base and relative URLs, according to +<a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. +</p> + +<p> +To obtain the <tt>url</tt> namespace, run: +</p> + +<pre class=example> +-- loads the URL module +local url = require("socket.url") +</pre> + +<p> +An URL is defined by the following grammar: +</p> + +<blockquote> +<tt> +<url> ::= [<scheme>:][//<authority>][/<path>][;<params>][?<query>][#<fragment>]<br> +<authority> ::= [<userinfo>@]<host>[:<port>]<br> +<userinfo> ::= <user>[:<password>]<br> +<path> ::= {<segment>/}<segment><br> +</tt> +</blockquote> + +<!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="absolute"> +url.<b>absolute(</b>base, relative<b>)</b> +</p> + +<p class=description> +Builds an absolute URL from a base URL and a relative URL. +</p> + +<p class=parameters> +<tt>Base</tt> is a string with the base URL or +a parsed URL table. <tt>Relative</tt> is a +string with the relative URL. +</p> + +<p class=return> +The function returns a string with the absolute URL. +</p> + +<p class=note> +Note: The rules that +govern the composition are fairly complex, and are described in detail in +<a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>. +The example bellow should give an idea of what the rules are. +</p> + +<pre class=example> +http://a/b/c/d;p?q + ++ + +g:h = g:h +g = http://a/b/c/g +./g = http://a/b/c/g +g/ = http://a/b/c/g/ +/g = http://a/g +//g = http://g +?y = http://a/b/c/?y +g?y = http://a/b/c/g?y +#s = http://a/b/c/d;p?q#s +g#s = http://a/b/c/g#s +g?y#s = http://a/b/c/g?y#s +;x = http://a/b/c/;x +g;x = http://a/b/c/g;x +g;x?y#s = http://a/b/c/g;x?y#s +. = http://a/b/c/ +./ = http://a/b/c/ +.. = http://a/b/ +../ = http://a/b/ +../g = http://a/b/g +../.. = http://a/ +../../ = http://a/ +../../g = http://a/g +</pre> + +<!-- build ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="build"> +url.<b>build(</b>parsed_url<b>)</b> +</p> + +<p class=description> +Rebuilds an URL from its parts. +</p> + +<p class=parameters> +<tt>Parsed_url</tt> is a table with same components returned by +<a href="#parse"><tt>parse</tt></a>. +Lower level components, if specified, +take precedence over high level components of the URL grammar. +</p> + +<p class=return> +The function returns a string with the built URL. +</p> + +<!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="build_path"> +url.<b>build_path(</b>segments, unsafe<b>)</b> +</p> + +<p class=description> +Builds a <tt><path></tt> component from a list of +<tt><segment></tt> parts. +Before composition, any reserved characters found in a segment are escaped into +their protected form, so that the resulting path is a valid URL path +component. +</p> + +<p class=parameters> +<tt>Segments</tt> is a list of strings with the <tt><segment></tt> +parts. If <tt>unsafe</tt> is anything but <b><tt>nil</tt></b>, reserved +characters are left untouched. +</p> + +<p class=return> +The function returns a string with the +built <tt><path></tt> component. +</p> + +<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="escape"> +url.<b>escape(</b>content<b>)</b> +</p> + +<p class=description> +Applies the URL escaping content coding to a string +Each byte is encoded as a percent character followed +by the two byte hexadecimal representation of its integer +value. +</p> + +<p class=parameters> +<tt>Content</tt> is the string to be encoded. +</p> + +<p class=result> +The function returns the encoded string. +</p> + +<pre class=example> +-- load url module +url = require("socket.url") + +code = url.escape("/#?;") +-- code = "%2f%23%3f%3b" +</pre> + +<!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="parse"> +url.<b>parse(</b>url, default<b>)</b> +</p> + +<p class=description> +Parses an URL given as a string into a Lua table with its components. +</p> + +<p class=parameters> +<tt>Url</tt> is the URL to be parsed. If the <tt>default</tt> table is +present, it is used to store the parsed fields. Only fields present in the +URL are overwritten. Therefore, this table can be used to pass default +values for each field. +</p> + +<p class=return> +The function returns a table with all the URL components: +</p> + +<blockquote><tt> +parsed_url = {<br> + url = <i>string</i>,<br> + scheme = <i>string</i>,<br> + authority = <i>string</i>,<br> + path = <i>string</i>,<br> + params = <i>string</i>,<br> + query = <i>string</i>,<br> + fragment = <i>string</i>,<br> + userinfo = <i>string</i>,<br> + host = <i>string</i>,<br> + port = <i>string</i>,<br> + user = <i>string</i>,<br> + password = <i>string</i><br> +} +</tt></blockquote> + +<pre class=example> +-- load url module +url = require("socket.url") + +parsed_url = url.parse("http://www.example.com/cgilua/index.lua?a=2#there") +-- parsed_url = { +-- scheme = "http", +-- authority = "www.example.com", +-- path = "/cgilua/index.lua" +-- query = "a=2", +-- fragment = "there", +-- host = "www.puc-rio.br", +-- } + +parsed_url = url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i") +-- parsed_url = { +-- scheme = "ftp", +-- authority = "root:passwd@unsafe.org", +-- path = "/pub/virus.exe", +-- params = "type=i", +-- userinfo = "root:passwd", +-- host = "unsafe.org", +-- user = "root", +-- password = "passwd", +-- } +</pre> + +<!-- parse_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="parse_path"> +url.<b>parse_path(</b>path<b>)</b> +</p> + +<p class=description> +Breaks a <tt><path></tt> URL component into all its +<tt><segment></tt> parts. +</p> + +<p class=description> +<tt>Path</tt> is a string with the path to be parsed. +</p> + +<p class=return> +Since some characters are reserved in URLs, they must be escaped +whenever present in a <tt><path></tt> component. Therefore, before +returning a list with all the parsed segments, the function removes +escaping from all of them. +</p> + +<!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class=name id="unescape"> +url.<b>unescape(</b>content<b>)</b> +</p> + +<p class=description> +Removes the URL escaping content coding from a string. +</p> + +<p class=parameters> +<tt>Content</tt> is the string to be decoded. +</p> + +<p class=return> +The function returns the decoded string. +</p> + +<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="index.html">home</a> · +<a href="index.html#down">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:26:05 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html> |
