From 982781f1464c9b7a8133130433f83dbf1f59a2c0 Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Sun, 31 Aug 2003 01:00:15 +0000 Subject: [PATCH] LuaSocket 2.0 User's Manual. --- doc/code.html | 202 ++++++++++++++++++++ doc/dns.html | 120 ++++++++++++ doc/ftp.html | 243 +++++++++++++++++++++++++ doc/http.html | 388 +++++++++++++++++++++++++++++++++++++++ doc/index.html | 212 +++++++++++++++++++++ doc/introduction.html | 328 +++++++++++++++++++++++++++++++++ doc/luasocket.png | Bin 0 -> 11732 bytes doc/reference.css | 40 ++++ doc/reference.html | 209 +++++++++++++++++++++ doc/smtp.html | 228 +++++++++++++++++++++++ doc/stream.html | 173 ++++++++++++++++++ doc/tcp.html | 415 ++++++++++++++++++++++++++++++++++++++++++ doc/udp.html | 400 ++++++++++++++++++++++++++++++++++++++++ doc/url.html | 265 +++++++++++++++++++++++++++ 14 files changed, 3223 insertions(+) create mode 100644 doc/code.html create mode 100644 doc/dns.html create mode 100644 doc/ftp.html create mode 100644 doc/http.html create mode 100644 doc/index.html create mode 100644 doc/introduction.html create mode 100644 doc/luasocket.png create mode 100644 doc/reference.css create mode 100644 doc/reference.html create mode 100644 doc/smtp.html create mode 100644 doc/stream.html create mode 100644 doc/tcp.html create mode 100644 doc/udp.html create mode 100644 doc/url.html diff --git a/doc/code.html b/doc/code.html new file mode 100644 index 0000000..45fd21a --- /dev/null +++ b/doc/code.html @@ -0,0 +1,202 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

Code

+ +

+The code.lua module offers routines to convert back and forth +some common types of content encoding, including Base 64 and URL +escaping. Base 64 is described in +RFC +2045, +URL escaping is described in +RFC +2396. +

+ + + +

+socket.code.base64(content, single) +

+ +

+Applies the Base 64 content coding to a string. +

+ +

+Content is the string to be encoded. +If single is set to anything +but nil, the output is returned as a single +line, otherwise the function splits the content into 76 character long +lines after encoding. +

+ +

+The function returns the encoded string. +

+ +
+code = socket.code.base64("diego:password")
+-- code = "ZGllZ286cGFzc3dvcmQ="
+
+ + + +

+socket.code.unbase64(content) +

+ +

+Removes the Base 64 content coding from a string. +

+ +

+Content is the string to be decoded. +

+ +

+The function returns the decoded string. +

+ + + +

+socket.code.escape(content) +

+ +

+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. +

+ +

+Content is the string to be encoded. +

+ +

+The function returns the encoded string. +

+ +
+code = socket.code.escape("/#?;")
+-- code = "%2f%23%3f%3b"
+
+ + + +

+socket.code.unescape(content) +

+ +

+Removes the URL escaping content coding from a string. +

+ +

+Content is the string to be decoded. +

+ +

+The function returns the decoded string. +

+ + + +

+socket.code.hexa(content) +

+ +

+Applies the hexadecimal content coding to a string. +Each byte is encoded as the byte hexadecimal +representation of its integer value.

+

+ +

+Content is the string to be encoded. +

+ +

+The function returns the encoded string. +

+ +
+code = socket.code.hexa("\16\32\255")
+-- code = "1020ff"
+
+ + + +

+socket.code.unhexa(content) +

+ +

+Removes the hexadecimal content coding from a string. +

+ +

+Content is the string to be decoded. +

+ +

+The function returns the decoded string. +

+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + diff --git a/doc/dns.html b/doc/dns.html new file mode 100644 index 0000000..6abf341 --- /dev/null +++ b/doc/dns.html @@ -0,0 +1,120 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

DNS

+ +

+The following functions can be used to convert between host names and IP +addresses. Both functions return all information returned by the +resolver in a table of the form: +

+ +
+resolved = {
+  name = canonic-name,
+  alias = alias-list,
+  ip = ip-address-list
+} +
+ +

+Note that the alias list can be empty. +

+ + + +

+socket.dns.tohostname() +

+ +

+Converts from IP address to host name. +

+ +

+Address can be an IP address or host name. +

+ +

+The function a string with the canonic host name of the given +address, followed by a table with all information returned by +the resolver. In case of error, the function returns nil +followed by an error message. +

+ + + + +

+socket.dns.toip() +

+ +

+Converts from host name to IP address. +

+ +

+Address can be an IP address or host name. +

+ +

+Returns a string with the first IP address found for address, +followed by a table with all information returned by the resolver. +In case of error, the function returns nil followed by an error +message. +

+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + diff --git a/doc/ftp.html b/doc/ftp.html new file mode 100644 index 0000000..8072afe --- /dev/null +++ b/doc/ftp.html @@ -0,0 +1,243 @@ + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

FTP

+ +

+FTP (File Transfer Protocol) is a protocol used to transfer files +between hosts. The module ftp.lua offers simple FTP support, +allowing applications to download and upload files, and list directory +contents. The implementation conforms to +RFC 959. +

+ +

+URLs MUST conform to +RFC +1738, that is, an URL is a string in the form: +

+ +
+ +[ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][type=a|i|d] +
+ + + +

+socket.ftp.get(url)
+socket.ftp.get{
+  url = string,
+  type = string,
+  user = string,
+  password = string
+} +

+ +

+Downloads an URL from a FTP server. +

+ +

+The function can be called either directly with a url +or with a request table. +Fields passed explicitly in the request table override those +present in the url. +

+ +

+The parameter type accepts values 'a' (ASCII, the +default), 'i' (binary) or 'd' (directory listing) and +determines the transfer type. If <path> ends with a +'/' or type is 'd', a directory listing of +<path> is returned. If no user is provided in the +url or explicitly, the function tries to log in as user +'anonymous'. +

+ +

+If successful, the function returns +the file content as a string. In case of error, the function returns +nil and an error message describing the error. +

+ +
+-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
+-- go to directory "pub/lua" and get file "lua.tar.gz" as binary.
+f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
+
+-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
+-- go to director "pub" and retrieve directory listing of directory "lua"
+f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua;type=d")
+
+-- Log as user "diego", password "nehab", on server "ftp.tecgraf.puc-rio.br",
+-- go to directory "tec/luasocket/bin" and retrieve file "luasocket.exe"
+-- (actually, fails because of wrong password, of course)
+f, e = socket.ftp.get{
+  url = "ftp://ftp.tecgraf.puc-rio.br/tec/luasocket/bin/luasocket.exe",
+  user = "diego",
+  password = "nehab",
+  type = "i"
+}
+-- f returns nil, and e returns an appropriate error message
+
+ + + +

+socket.ftp.get_cb{
+  url = string,
+  type = string,
+  content_cb = receive-callback,
+  user = string,
+  password = string
+} +

+ +

+Same as get, but the library returns +the content of the downloaded file to the receive callback +content_cb. +

+ +

+Note: for more information on callbacks, refer to +Streaming with callbacks. +

+ + + +

+socket.ftp.put(url, content)
+socket.ftp.put{
+  url = string,
+  content = string,
+  type = string,
+  user = string,
+  password = string
+} +

+ +

+Upload a file to a FTP server. +

+ +

+The function can be called directly with a +url and content parameters, or with a +request table. +Values passed explicitly in the request table override those present in +the url. The parameter type accept values +'a' (ASCII, the default) or 'i' (binary) and +determines the transfer type. If no user is provided, the +function tries to log in as 'anonymous'. +

+ +

+If successful, the function returns 1. In case of error, the +function returns nil followed by a string describing the error. +

+ +
+-- Log as user "anonymous" on server "ftp.free.org" and store file
+-- "hello" with contents "hello world!", using binary mode for the transfer
+r, e = socket.ftp.put("ftp://ftp.free.org/hello;type=i", "hello world!\n")
+
+-- Does exactly the same, but logging in as diego
+r, e = socket.ftp.put{
+  url = "ftp://ftp.free.org/hello",
+  type = "i",
+  user = "diego",
+  password = "nehab",
+  content = "hello world\n"
+}
+
+ + + + +

+socket.ftp.put_cb{
+  url = string,
+  type = string,
+  content_cb = send-callback,
+  user = string,
+  password = string
+} +

+ +

+Same as put, but the +library obtains the contents of the file to be uploaded using the send +callback content_cb. +

+ +

+Note: for more information on callbacks, refer to +Streaming with callbacks. +

+ +
+-- Log as user "anonymous" on server "ftp.free.org" and store file
+-- "hello" with contents of the same file in the current directory, 
+-- using binary mode for the transfer
+r, e = socket.ftp.put_cb{
+  url = "ftp://ftp.free.org/hello",
+  type = "i",
+  content_cb = socket.callback.send_file(io.open("hello", "r"))
+}
+
+ + + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + diff --git a/doc/http.html b/doc/http.html new file mode 100644 index 0000000..b7469a4 --- /dev/null +++ b/doc/http.html @@ -0,0 +1,388 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

HTTP

+ +

+HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange +information between web-browsers and servers. The http.lua +module offers 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, +RFC +2616. +

+ +

+The module exports functions that provide HTTP functionality in different +levels of abstraction, from a simple get, to the generic, stream oriented + request_cb. +

+ +

+URLs must conform to +RFC +1738, +that is, an URL is a string in the form: +

+ +
+
+[http://][<user>[:<password>]@]<host>[:<port>][/<path>] 
+
+
+ +

+MIME headers are represented as a Lua table in the form: +

+ +
+ + + + +
+headers = {
+  field-1-name = field-1-value,
+  field-2-name = field-2-value,
+  field-3-name = field-3-value, +
+  ... +
+  field-n-name = field-n-value
+} +
+
+ +

+Field names are case insensitive (as specified by the standard) and all +functions work with lowercase field names. +Field values are left unmodified. +

+ +

+Note: MIME headers are independent of order. Therefore, there is no problem +in representing them in a Lua table. +

+ + + +

+socket.http.get(url)
+socket.http.get{
+  url = string,
+  headers = header-table,
+  user = string,
+  password = string,
+  stay = bool,
+} +

+ +

+Performs the HTTP method GET. +

+ +

+The function can be +called either directly with a url or with a request table. +The use of a request table allows complete control over the components of +the request. Values passed explicitly as fields of the request table +override those given by the url. For a description of the fields, +see the request function. +

+ +

+The function returns the response message body, the mime headers, the +status code and an error message (if any). In case of failure, the +function returns all information it managed to gather. +

+ +

+Note: The function is trivially implemented with the use of the +request function. +

+ +
+-- connect to server "www.tecgraf.puc-rio.br" and retrieves this manual
+-- file from "/luasocket/http.html"
+b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html")
+
+-- connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
+-- "~diego/auth/index.html". Fails because authentication is needed.
+b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/~diego/auth/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.
+b, h, c, e = socket.http.get("http://wrong.host/")
+-- b, h, c are nil, and e returns with value "host not found"
+
+ + + +

+socket.http.post(url, body)
+socket.http.post{
+   url = string,
+   headers = header-table,
+   body = string,
+   user = string,
+   password = string,
+   stay = bool,
+} +

+ +

+Same as get, except +that the POST method is used and the request +message body is sent along with the request. +

+ +

+Note: This function is also trivially implemented with the use of the +request function. +

+ + + +

+socket.http.request{
+  method = string,
+  url = string,
+  headers = header-table,
+  body = string,
+  user = string,
+  password = string,
+  stay = string,
+} +

+ +

+Performs the generic HTTP request using. +

+ +

+The request uses method on url +sending the request headers and request body in the +request message. If authentication information is provided, the function +uses the Basic Authentication Scheme (see note) +to retrieve the document. User and password provided +explicitly override those given by the url. The stay +parameter, when set to anything but nil, prevents the function +from automatically following 301 or 302 server redirect messages. +

+ +

+The function returns a table with all components of the response message +it managed to retrieve. The response table has the following form: +

+ +
+response = {
+  body = string,
+  headers = header-table,
+  status = string,
+  code = number,
+  error = string
+} +
+ +

+Even when there was failure (URL not found, for example), the +function may succeed retrieving 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 code. For +a list of the possible values and their meanings, refer to RFC +2616. +

+ +
+-- 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
+response = socket.http.request {
+  method = "HEAD",
+  url = "http://www.tecgraf.puc-rio.br/~diego"
+}
+-- Would return the following headers:
+-- response.headers = {
+--   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"
+-- }
+
+ + +

+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". +

+ +

+The HTTP/1.1 standard defines two authentication methods: the Basic +Authentication Scheme and the Digest Authentication Scheme, both +explained in detail in +RFC 2068. +

+ +

The Basic Authentication Scheme sends +<user> and +<password> 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. +

+ +
+-- Connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
+-- "~diego/auth/index.html", using the provided name and password to
+-- authenticate the request
+response = socket.http.request{
+  url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
+  user = "diego",
+  password = "password"
+}
+
+-- Alternatively, one could fill the appropriate header and authenticate
+-- the request directly.
+headers = {
+  authentication = "Basic " .. socket.code.base64("diego:password")
+}
+response = socket.http.request {
+  url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
+  headers = headers
+}
+
+ + + +

+socket.http.request_cb(request, response) +

+ +

+Performs the generic HTTP request. +

+ +

+The function receives two tables as parameters. The request table +provides information about the request: +

+ +
+request = {
+  method = string,
+  url = string,
+  headers = header-table,
+  body_cb = send-callback,
+  user = string,
+  password = string,
+  stay = string,
+} +
+ +

+The function uses the HTTP method specified in +request.method on the URL request.url, +sending request.headers along with the request. The request +message body is sent via the send callback request.body_cb. +If authentication information is provided, the function uses the Basic +Authentication Scheme (see note) to +retrieve the document. Request.user and +request.password override those given by the +request.url. The request.stay parameter, when set to +anything but nil, prevents the function from automatically +following 301 or 302 server redirect messages. +

+ +

+The response table specifies information about the desired +response: +

+ +
+response = {
+  body_cb = receive-callback
+} +
+ +

+The function returns the same response table as that returned by the +socket.http.request function, except the response message body is +returned to the receive callback given by the +response.body_cb field. +

+ +

+Note: For more information on callbacks, please refer to +Streaming with callbacks. +

+ +

+Note: Method names are case sensitive +

+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..46642d2 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,212 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

What is LuaSocket?

+ +

+LuaSocket is a Lua extension library +that is composed by two parts: a C layer 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. +

+ +

+Network support has been implemented so that it is both efficient and +simple to use. LuaSocket can be used by any Lua application once it has +been properly linked with and initialized by the interpreter running the +Lua application. The code has been tested and runs well on several Windows +and Unix platforms. +

+ +

+The library is available under the same + +terms and conditions 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. +

+ +

+Copyright © 1999-2003 Tecgraf/PUC-Rio. All rights reserved.
+Author: Diego Nehab +

+ + + +

Download

+ +

+LuaSocket version 2.0 alpha is now available for download! It is +compatible with Lua 5.0 and has been tested on +Windows XP, Linux, and Mac OS X. +

+ +

+The library can be downloaded in source code from the following links: +

+ +
+

+luasocket-2.0-alpha.tar.gz
+luasocket-2.0-alpha.zip +

+
+ +

+Besides the full C and Lua source code for the library, the distribution +contains several examples, this user's manual and the test procedures. +

+ +

+I am also providing a Windows binary for those that want to give +LuaSocket a quick try: +

+ +
+

+luasocket-2.0.exe +

+
+ +

+This binary has been compiled with the LUASOCKET_DEBUG +option, and should be able to run the automatic test procedures. +

+ + + +

What's New

+ +

+Most of the changes for 2.0 happened in the C layer, which +has been almost completely rewritten. The code has been ported to Lua 5.0 +and greatly improved. There have also been some API changes +that made the interface simpler and more consistent. Here are some of +the changes that made it into version 2.0: +

+ + + + + +

Incompatibilities with previous versions

+ + + + + +

Old Versions

+ +

+All previous versions of the LuaSocket library can be downloaded +here. Although +these versions are no longer supported, they are still available for +those that have compatibility issues. +

+ + + +
+
+
+

+download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sun Aug 10 01:36:26 PDT 2003 + +

+
+
+ + + diff --git a/doc/introduction.html b/doc/introduction.html new file mode 100644 index 0000000..7adf45b --- /dev/null +++ b/doc/introduction.html @@ -0,0 +1,328 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

Introduction

+ +

+Communication in LuaSocket is performed via I/O objects. These can +represent different network domains. Currently, support is +provided for TCP and UDP, but there is work in progress to implement SSL, +Local Domain, Pipes, File Descriptors etc. I/O objects provide a standard +interface to I/O across different domains and operating systems. +LuaSocket 2.0 has been rewritten from scratch to simplify the future +addition new domains. +

+ +

+The LuaSocket API was designed with 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. +

+ +

+One of the simplifications is the timeout control +mechanism. As in C, all I/O operations are blocking by default. For +example, the send, +receive and +accept methods +of the TCP domain will block the caller application until +the operation is completed (if ever!). However, with a call to the +settimeout +method, an application can specify upper limits on +the time it can be blocked by LuaSocket (the "total" timeout), on +the time LuaSocket can internally be blocked by any OS call (the +"block" timeout) or a combination of the two. Each LuaSocket +call might perform several OS calls, so that the two timeout values are +not equivalent. +

+ +

+Another important difference 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. +

+ +

+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 returned IP address. Note that direct use of IP addresses +is more efficient, of course. The +toip +and tohostname +functions from the DNS module are provided to convert between host names and IP addresses. +

+ +

+Previous versions of LuaSocket provided global functions for operating on +I/O objects. To give the library a Lua 5.0 feel, these have been eliminated +from LuaSocket 2.0. I/O operations are only available as methods of the +corresponding I/O objects. Naturally, different I/O objects accept +different operations. The core functionality for TCP and UDP objects is +introduced in the following sections, following a few words about +initialization. +

+ + + +

Initializing the library

+ +

+Beginning with version 2.0 and following the Lua 5.0 trend, all LuaSocket +functionality is defined inside a table (or rather a namespace) stored with +the global name socket. To have this table created and its +contents made available to a Lua script, the interpreter running the script +must be linked to the LuaSocket library, and to whatever libraries the +host OS requires for network access (Windows requires ws2_32.lib, for +instance). LuaSocket is initialized in the +Lua state given as the argument to the function +luaopen_socket, the only C function exported by the library. +After initialization, the scripts are free to use all LuaSocket API. +

+ + + +

TCP

+ +

+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 granularity: patterns are available for +lines, arbitrary sized blocks or "read up to connection closed", all with +good performance. +

+ +

+The library distinguishes three types of TCP sockets: master, client and server sockets. +

+ +

+Master sockets are newly created TCP sockets returned by the function +socket.tcp. A master socket is +transformed into a server socket +after it is associated with a local address by a call to the +bind method. Conversely, it +can be changed into a client socket with the method +connect, +that associates it with a remote address. +

+ +

+On server sockets, applications can use the +accept 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 +getsockname, +setoption, +settimeout and +close. +

+ +

+Client sockets are used to exchange data between two applications over +the Internet. Applications can call the methods +send and +receive +to send and receive data. The other methods +available for client socket objects are +getsockname, +getpeername, +setoption, +settimeout and +close. +

+ +

+Example: +

+
+

+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 after. You can test it using the telnet +program. +

+ +
+-- create a new TCP object
+server, err = socket.tcp()
+assert(server, err)
+-- bind it to the local host, at any port
+ret, err = server:bind("*", 0)
+assert(ret, err)
+-- find out which port the OS chose for us
+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 conection from any client
+  client, err = server:accept()
+  -- make sure we don't block waiting for this client's line
+  client:settimeout(10)
+  -- receive the line
+  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
+
+
+ + + +

UDP

+ +

+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). +

+ +

+An UDP socket object is created by the +socket.udp function. UDP +sockets do not need to be connected before use. The method +sendto +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 +receive and +receivefrom +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). +

+ +

+When communication is performed repeatedly with a single peer, an +application should call the +setpeername method to specify a +permanent partner. Methods +sendto and +receivefrom +can no longer be used, but the method +send can be used to send data +directly to the peer, and the method +receive +will only return datagrams originating +from that peer. There is about 30% performance gain due to this practice. +

+ +

+To associate an UDP socket with a local address, an application calls the +setsockname +method before 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 +getpeername, +getsockname, +settimeout, +setoption and +close. +

+ +

+Example: +

+
+

+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. +

+ +
+host = "localhost" -- change here to the host you want to contact
+port = port or 13
+-- convert host name to ip address
+ip, err = socket.toip(host)
+assert(ip, err)
+-- create a new UDP object
+udp = socket.udp()
+-- contact daytime host
+nsent, err = udp:sendto("anything", ip, port)
+assert(not err, err)
+-- retrieve the answer
+dgram, err = udp:receive()
+assert(dgram, err)
+-- display to user
+print(dgram)
+
+
+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + diff --git a/doc/luasocket.png b/doc/luasocket.png new file mode 100644 index 0000000000000000000000000000000000000000..d24a95495b55894b96aec1b01d0b7c02cc43f168 GIT binary patch literal 11732 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 * { margin-left: 1em; } + +div.header, div.footer { margin-left: 0em; } +hr, h1, h2, h3, h4 { margin-left: 0em; } +p.name { margin-left: 0em; } + +h2:first-letter, h2:first-letter, h3:first-letter { color: #00007f; } + +blockquote { margin-left: 3em; } + +a[href] { color: #00007f; } + +p.name { + font-size: large; + font-family: monospace; + padding-top: 1em; +} + +pre.example { + background: #ccc; + font-size: small; + padding: 1em; +} + +hr { + 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; } diff --git a/doc/reference.html b/doc/reference.html new file mode 100644 index 0000000..39f6437 --- /dev/null +++ b/doc/reference.html @@ -0,0 +1,209 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

Reference

+ + + + + + + + + +
+ +
+ + + + + + + + + +
+ +
+ + + + + + + + + +
+ +
+ + + + + + +
+ +
+ + + + + + + + + +
+ +
+ + + + + + + + + +
+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Thu Sep 27 16:18:27 EST 2001 + +

+
+
+ + + diff --git a/doc/smtp.html b/doc/smtp.html new file mode 100644 index 0000000..3a30a07 --- /dev/null +++ b/doc/smtp.html @@ -0,0 +1,228 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

SMTP

+ +

+The module smtp.lua provides functionality to send e-mail +messages. The implementation conforms to the Simple Mail Transfer Protocol, +RFC 2821. +The other RFC of interest in this implementation is +RFC 2822, +which governs the Internet Message Format. + +

+ +

+MIME headers are represented as a Lua table in the form: +

+ +
+ + + + +
+headers = {
+  field-1-name = field-1-value,
+  field-2-name = field-2-value,
+  field-3-name = field-3-value, +
+  ... +
+  field-n-name = field-n-value
+} +
+
+ +

+Field names are case insensitive (as specified by the standard) and all +functions work with lowercase field names. +Field values are left unmodified. +

+ +

+Note: MIME headers are independent of order. Therefore, there is no problem +in representing them in a Lua table. +

+ + + +

+socket.smtp.mail{
+  from = string,
+  rcpt = string or string-table,
+  body = string,
+  headers = headers-table,
+  server = string
+} +

+ +

+Sends a message to a recipient list. +

+ +

+Rcpt is a Lua table with one entry for each recipient, or a string +in case there is just one recipient. +The sender is given by the e-mail address from. +The message is composed by the optional MIME Headers headers +and text body. The message is sent using the server +server. +

+ +

+If successful, the function returns 1. Otherwise, the function returns +nil followed by an error message. +

+ +

+Big note: There is a good deal of misconception with the use of the +destination address field headers, i.e., the 'To', 'Cc', +and, more importantly, the 'Bcc' headers. Do not add a +'Bcc' header to your messages because it will probably do the +exact opposite of what you expect. +

+ +

+Only recipients specified in the recipient list will receive a copy of the +message. Each recipient of an SMTP mail message receives a copy of the +message body along with the headers, and nothing more. The headers are +considered as part of the message. The list of recipients is not +part of the message. +

+ +

+RFC 2822 +has two important and short 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: +

+ +
    +
  • To: contains the address(es) of the primary recipient(s) +of the message; +
  • Cc: (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; +
  • Bcc: (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. +
+ +

+The LuaSocket mail function does not interpret the headers you +pass to, but it gives you full control over what is sent and to whom +it is sent: +

+
    +
  • If someone is to receive the message, the e-mail address has +to be in the recipient list. This is the only parameter that controls who +gets a copy of the message; +
  • 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 Bcc field of popular e-mail clients; +
  • It is up to you to add the To header with the list of primary +recipients so that other recipients can see it; +
  • It is also up to you to add the Cc header with the +list of additional recipients so that everyone else sees it; +
  • Adding a header Bcc is nonsense, unless it is +empty. Otherwise, everyone receiving the message will see it and that is +exactly what you don't want to happen! +
+ +

+I hope this clarifies the issue. Otherwise, please refer to +RFC 2821 +and +RFC 2822. +

+ +
+-- Connects to server "localhost" and sends a message to users
+-- "fulano@tecgraf.puc-rio.br",  "beltrano@tecgraf.puc-rio.br", 
+-- and "sicrano@tecgraf.puc-rio.br".
+-- Note that "fulano" is the primary recipient, "beltrano" receives a
+-- carbon copy and neither of them knows that "sicrano" received a blind
+-- carbon copy of the message.
+headers = {
+  to = "fulano@tecgraf.puc-rio.br",
+  cc = "beltrano@tecgraf.puc-rio.br",
+  subject = "LuaSocket test message"
+}
+
+from = "luasocket@tecgraf.puc-rio.br"
+
+rcpt = {
+  "fulano@tecgraf.puc-rio.br",
+  "beltrano@tecgraf.puc-rio.br",
+  "sicrano@tecgraf.puc-rio.br"
+}
+
+body = "This is a test message. Please ignore."
+
+server = "localhost"
+
+r, e = socket.smtp.mail{
+  from = from,
+  rcpt = rcpt, 
+  headers = headers, 
+  body = body, 
+  server = server
+}
+
+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + diff --git a/doc/stream.html b/doc/stream.html new file mode 100644 index 0000000..296ca2e --- /dev/null +++ b/doc/stream.html @@ -0,0 +1,173 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

Streaming with Callbacks

+ +

+HTTP and FTP transfers sometimes involve large amounts of information. +Sometimes an application needs to generate outgoing data in real time, +or needs to process incoming information as it is being received. To +address these problems, LuaSocket allows HTTP message bodies and FTP +file contents to be received or sent through the callback mechanism +outlined below. +

+ +

+Instead of returning the entire contents of a FTP file or HTTP message +body as strings to the Lua application, the library allows the user to +provide a receive callback that will be called with successive +chunks of data, as the data becomes available. Conversely, the send +callbacks should be used when data needed by LuaSocket +is generated incrementally by the application. +

+ + + +

+receive_cb(chunk, err) +

+ +

+The callback provided by the user will be repeatedly called by the +library whenever new data is available. Each time it is called, the +callback receives successive chunks of downloaded data. +

+ +

+Chunk contains the current chunk of data. +When the transmission is over, the function is called with an +empty string (i.e. "") as the chunk. If an error occurs, the +function receives nil as chunk and an error message as +err. +

+ +

+The callback can abort transmission by returning +nil as its first return value. In that case, it can also return +an error message. Any non-nil return value proceeds with the +transmission. +

+ +
+-- The implementation of socket.callback.receive_concat
+function Public.receive_concat(concat)
+    concat = concat or socket.concat.create()
+    local callback = function(chunk, err)
+        -- if not finished, add chunk
+        if chunk and chunk ~= "" then
+            concat:addstring(chunk)
+            return 1
+        end
+    end
+    return callback, concat
+end
+
+ + + +

+send_cb() +

+ +

+The callback provided by the user will be repeatedly called whenever the +library needs more data to be sent. +

+ +

+Each time the callback is called, it +should return the next part of the information the library is expecting, +followed by the total number of bytes to be sent. +The callback can abort +the process at any time by returning nil followed by an +optional error message. +

+ + +

+Note: The need for the second return value comes from the fact that, with +the HTTP protocol for instance, the library needs to know in advance the +total number of bytes that will be sent. +

+ +
+-- The implementation of socket.callback.send_file
+function Public.send_file(file)
+    local callback
+    -- if successfull, return the callback that reads from the file
+    if file then
+        -- get total size
+        local size = file:seek("end") 
+        -- go back to start of file
+        file:seek("set")
+        callback = function()
+            -- send next block of data
+            local chunk = file:read(Public.BLOCKSIZE)
+            if not chunk then file:close() end
+            return chunk, size
+        end
+    -- else, return a callback that just aborts the transfer
+    else
+        callback = function() 
+            -- just abort
+            return nil, "unable to open file"
+        end
+    end
+    return callback, file
+end
+
+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + diff --git a/doc/tcp.html b/doc/tcp.html new file mode 100644 index 0000000..ecbedaa --- /dev/null +++ b/doc/tcp.html @@ -0,0 +1,415 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

TCP

+ + + +

+socket.tcp() +

+ +

+Creates and returns a TCP master object. A master object can +be transformed into a server object with the method +bind or into a client object with the method +connect. The only other method +supported by a master object is the close +method.

+ +

+In case of success, a new master object is returned. In case of error, +nil is returned, followed by an error message. +

+ + + +

+server:accept() +

+ +

+Waits for a remote connection on the server +object and returns a client object representing that connection. +

+ +

+If a connection is successfully initiated, a client object is returned. +If a timeout condition is met, the method returns nil followed +by the error string 'timeout'. +

+ +

+Note: calling socket.select +with a server object in +the receive parameter before a call to accept does +not guarantee accept will return immediately. Use the settimeout method or accept +might block until another client shows up. +

+ + + +

+master:bind(address, port [, backlog]) +

+ +

+Binds a master object to address and port on the +local host, transforming it into a server object. Server +objects support the +accept, +getsockname, +setoption, +settimeout, +and close methods. +

+ +

+Address can be an IP address or a host name. +Port must be an integer number in the range [0..64K]. +If address +is '*', the system binds to all local interfaces +using the INADDR_ANY constant. If port is 0, the system automatically +chooses an ephemeral port. The optional parameter backlog, which +defaults to 1, 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. +

+ +

+In case of success, the method returns 1. In case of error, the +method returns nil followed by an error message. +

+ +

+Note: The function socket.bind is available and is a short +for socket.tcp followed by the bind method. +

+ + + +

+master:close()
+client:close()
+server:close() +

+ +

+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 close method) are allowed on +a closed socket. +

+ +

+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. +

+ + + +

+master:connect(address, port) +

+ +

+Attempts to connect a master object to a remote host, transforming it into a +client object. Client objects support methods +send, +receive, +getsockname, +getpeername, +settimeout, +and close. +

+ +

+Address can be an IP address or a host name. +Port must be an integer number in the range [1..64K]. +

+ +

+In case of error, the method returns nil followed by a string +describing the error. In case of success, the method returns 1. +

+ +

+Note: The function socket.connect is available and is a short +for socket.tcp followed by the connect method. +

+ + + +

+client:getpeername() +

+ +

+Returns information about the remote side of a connected client object. +

+ +

+Returns a string with the IP address of the peer, followed by the +port number that peer is using for the connection. +In case of error, the method returns nil. +

+ +

+Note: It makes no sense to call this method on server objects. +

+ + + +

+client:getsockname()
+server:getsockname() +

+ +

+Returns the local address information associated to the object. +

+ +

+The method returns a string with local IP address and a number with +the port. In case of error, the method returns nil. +

+ +

+Note: Naturally, for a server object, the address and port returned are +those passed to the bind method. If the port value +passed to bind was 0, the OS assigned ephemeral port is returned. For +client objects, both the address and port are ephemeral and these are the +values returned. +

+ + + +

+client:receive([pattern1, pattern2, +... patternN]) +

+ +

+Reads data from a client object, according to the specified read +patterns. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. +

+ +

+The parameters pattern1, pattern2, ... +patternN can be any of the following: +

+ +
    +
  • '*a': reads from the socket until the connection is +closed. No end-of-line translation is performed; +
  • '*l': 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. This is the default pattern; +
  • number: causes the method to read number raw +bytes from the socket. +
+ +

+The method returns one value for each pattern, followed by a single +error code that can be nil in case of success, the string +'closed' in case the connection was closed before the +transmission was completed or the string 'timeout' in case +there was a timeout during the operation. +

+ +

+Note: In case of error, the method always return everything it managed +to download before the error condition was met. +

+ + + +

+client:send(string1 [, +string2, ... stringN]) +

+ +

+Sends data through client object. +

+ +

+All parameters should be strings. For small strings, it is always better to +concatenate them in Lua (with the '..' operator) and pass the +result to LuaSocket instead of passing several independent strings. +

+ +

+The method returns the number of bytes accepted by the transport layer, +followed by an error code. The error code is nil if the operation +completed with no errors, the string 'closed' in case +the connection was closed before the transmission was completed or the +string 'timeout' in case there was a timeout during the +operation. +

+ +

+Note: The return values for the send method have been changed in +LuaSocket 2.0! In previous versions, the method returned only the +error message. Since returning nil in case of success goes +against all other LuaSocket methods and functions, the +send method been changed for the sake of uniformity. +

+ + + +

+client:setoption(option [, value])
+server:setoption(option [, value]) +

+ +

+Sets options for the TCP object. Options are only needed by low-level or +time-critical applications. You should only modify a an option if you +are sure you need it. +

+ +

+Option is a string with the option name, and value +depends on the option being set: + +

    +
  • 'tcp-nodelay': Setting this option to true disables the +Nagle's algorithm for the connection; +
  • 'linger': Controls the action taken when unsent data are +queued on socket and a close is performed. The value is a table with a +boolean entry 'on' and a numeric entry for the time interval +'timeout' in seconds. + If the 'on' field is set to true, +the system will block the process on the close attempt until it is able to +transmit the data or until 'timeout' has passed. If 'on' +is false 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. +
  • 'keepalive': Setting this option to true 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. +
+ +

+The method returns 1 in case of success, or nil otherwise. +

+ +

+Note: The descriptions above come from the man pages. +

+ + + +

+client:settimeout(value [, mode])
+server:settimeout(value [, mode]) +

+ +

+Changes the timeout values for the object. By default, +all I/O operations are blocking. That is, any call to the methods +send, +receive, and +accept +will block indefinitely, until the operation completes. The +settimeout 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. +

+ +

+The amount of time to wait is specified as the +value parameter, in seconds. There are two timeout modes and +both can be used together for fine tuning: +

+ +
    +
  • 'b': block 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;
    • + +
  • 't': total timeout. Specifies the upper limit on +the amount of time LuaSocket can block a Lua script before returning from +a call.
    • +
+ +

+The nil timeout value allows operations to block +indefinitely. Negative timeout values have the same effect. +

+ +

+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. +

+ +

+Note: The old timeout 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. +

+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + diff --git a/doc/udp.html b/doc/udp.html new file mode 100644 index 0000000..235c0c5 --- /dev/null +++ b/doc/udp.html @@ -0,0 +1,400 @@ + + + +LuaSocket: Network support for the Lua language + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

+socket.udp() +

+ +

+Creates and returns an unconnected UDP object. Unconnected objects support the +sendto, +receive, +receivefrom, +getsockname, +setoption, +settimeout, +setpeername, +setsockname, and +close. +The setpeername +is used to connect the object. +

+ +

+In case of success, a new unconnected UDP object +returned. In case of error, nil is returned, followed by +an error message. +

+ + + +

+connected:close()
+unconnected:close() +

+ +

+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 close +method) are allowed on a closed socket. +

+ +

+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. +

+ + + +

+connected:getpeername() +

+ +

+Retrieves information about the peer +associated with a connected UDP object. +

+ +

+Returns the IP address and port number of the peer. +

+ +

+Note: It makes no sense to call this method on unconnected objects. +

+ + + +

+connected:getsockname()
+unconnected:getsockname() +

+ +

+Returns the local address information associated to the object. +

+ +

+The method returns a string with local IP +address and a number with the port. In case of error, the method +returns nil. +

+ +

+Note: UDP sockets are not bound to any address +until the setsockname or the +sendto method is called for the +first time (in which case it is bound to an ephemeral port and the +wild-card address). +

+ + + +

+connected:receive([size])
+unconnected:receive([size]) +

+ +

+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. +

+ +

+The optional size parameter +specifies the maximum size of the datagram to be retrieved. If +there are more than size bytes available in the datagram, +the excess bytes are discarded. If there are less then +size bytes available in the current datagram, the +available bytes are returned. If size is omitted, the +maximum datagram size is used. +

+ +

+In case of success, the method return the +received datagram. In case of timeout, the method returns +nil followed by the string 'timeout'. +

+ + + +

+unconnected:receivefrom([size]) +

+ +

+Works exactly as the receive +method, except it returns the IP +address and port as extra return values (and is therefore slightly less +efficient). +

+ + + +

+connected:send(datagram) +

+ +

+Sends a datagram to the UDP peer of a connected object. +

+ +

+Datagram is a string with the datagram contents. +Beware that the maximum datagram size for UDP is 576 bytes. +

+ +

+If successful, the method returns 1. In case of +error, the method returns nil followed by the +'refused' message. +

+ +

+Note: In UDP, the send 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). +

+ + + +

+unconnected:sendto(datagram, ip, port) +

+ +

+Sends a datagram to the specified IP address and port number. +

+ +

+Datagram is a string with the +datagram contents. Beware that the maximum datagram size for UDP is +576 bytes. Ip is the IP address of the recipient. Host +names are not allowed for performance reasons. +Port is the port number at the recipient. +

+ +

+If successful, the method returns 1. In case of +error, the method returns nil followed by the +'refused' message. +

+ +

+Note: In UDP, the send 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). +

+ + + +

+connected:setpeername('*')
+unconnected:setpeername(address, port) +

+ +

+Changes the peer of a UDP object. This +method turns an unconnected UDP object into a connected UDP +object or vice-versa. +

+ +

+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 send and +receive methods instead of +sendto and +receivefrom. +

+ +

+Address can be an IP address or a +host name. Port is the port number. If address is +'*' and the object is connected, the peer association is +removed and the object becomes an unconnected object again. In that +case, the port argument is ignored. +

+ +

+In case of error the method returns +nil followed by an error message. In case of success, the +method returns 1. +

+ +

+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. +

+ + + +

+unconnected:setsockname(address, port) +

+ +

+Binds the UDP object to a local address. +

+ +

+Address can be an IP address or a +host name. If address is '*' the system binds to +all local interfaces using the constant INADDR_ANY. If +port is 0, the system chooses an ephemeral port. +

+ +

+If successful, the method returns 1. In case of +error, the method returns nil followed by an error +message. +

+ +

+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 setsockname, it cannot be +changed. +

+ + + +

+connected:setoption(option [, value])
+unconnected:setoption(option [, value]) +

+ +

+Sets options for the UDP object. Options are +only needed by low-level or time-critical applications. You should +only modify a an option if you are sure you need it.

+

Option is a string with the option +name, and value depends on the option being set: +

+ +
    +
  • 'dontroute': Setting this option to true +indicates that outgoing messages should bypass the standard routing +facilities;
    • +
  • 'broadcast': Setting this option to true +requests permission to send broadcast datagrams on the +socket.
    • +
+ +

+The method returns 1 in case of success, or +nil followed by an error message otherwise. +

+ +

+Note: The descriptions above come from the man +pages. +

+ + + +

+connected:settimeout(value)
+unconnected:settimeout(value) +

+ +

+Changes the timeout values for the object. By default, the +receive and +receivefrom +operations are blocking. That is, any call to the methods will block +indefinitely, until data arrives. The settimeout 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. +

+ +

+The amount of time to wait is specified as +the value parameter, in seconds. The nil timeout +value allows operations to block indefinitely. Negative +timeout values have the same effect. +

+ +

+Note: In UDP, the send +and sendto methods never block (the +datagram is just passed to the OS and the call returns +immediately). Therefore, the settimeout method has no +effect on them. +

+ +

+Note: The old timeout 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. +

+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + diff --git a/doc/url.html b/doc/url.html new file mode 100644 index 0000000..e67ea13 --- /dev/null +++ b/doc/url.html @@ -0,0 +1,265 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

URL

+ +

+The module url.lua provides functions to parse, protect, +and build URLs, as well as functions to compose absolute URLs +from base and relative URLs, according to +RFC +2396. +

+ +

+An URL is defined by the following grammar: +

+ +
+ +<url> ::= [<scheme>:][//<authority>][/<path>][;<params>][?<query>][#<fragment>]
+<authority> ::= [<userinfo>@]<host>[:<port>]
+<userinfo> ::= <user>[:<password>]
+<path> ::= {<segment>/}<segment>
+ +
+ + + +

+socket.url.absolute(base, relative) +

+ +

+Builds an absolute URL from a base URL and a relative URL. +

+ +

+Base is a string with the base URL and relative is a +string with the relative URL. +

+ +

+The function returns a string with the absolute URL. +

+ +

+Note: The rules that +govern the composition are fairly complex, and are described in detail in +RFC 2396. +The example bellow should give an idea of what are the rules. +

+ +
+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
+
+ + + +

+socket.url.build(parsed_url) +

+ +

+Rebuilds an URL from its parts. +

+ +

+Parsed_url is a table with same components returned by +parse. +Lower level components, if specified, +take precedence over hight level components of the URL grammar. +

+ +

+The function returns a string with the built URL. +

+ + + +

+socket.url.build_path(segments, unsafe) +

+ +

+Builds a <path> component from a list of +<segment> 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. +

+ +

+Segments is a list of strings with the <segment> +parts. If unsafe is anything but nil, reserved +characters are left untouched. +

+ +

+The function returns a string with the +built <path> component. +

+ + + +

+socket.url.parse(url, default) +

+ +

+Parses an URL given as a string into a Lua table with its components. +

+ +

+Url is the URL to be parsed. If the default 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. +

+ +

+The function returns a table with all the URL components: +

+ +
+parsed_url = {
+  url = string,
+  scheme = string,
+  authority = string,
+  path = string,
+  params = string,
+  query = string,
+  fragment = string,
+  userinfo = string,
+  host = string,
+  port = string,
+  user = string,
+  password = string
+} +
+ +
+parsed_url = socket.url.parse("http://www.puc-rio.br/~diego/index.lua?a=2#there")
+-- parsed_url = {
+--   scheme = "http",
+--   authority = "www.puc-rio.br",
+--   path = "/~diego/index.lua"
+--   query = "a=2",
+--   fragment = "there",
+--   host = "www.puc-rio.br",
+-- }
+
+parsed_url = socket.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",
+-- }
+
+ + + +

+socket.url.parse_path(path) +

+ +

+Breaks a <path> URL component into all its +<segment> parts. +

+ +

+Path is a string with the path to be parsed. +

+ +

+Since some characters are reserved in URLs, they must be escaped +whenever present in a <path> component. Therefore, before +returning a list with all the parsed segments, the function unescapes all +of them. +

+ + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + +