Module net: TCP/IP Networking

This module supports creation of active TCP connections to hosts anywhere on the Internet. Secure connections based on SSL or TLS are also supported, as well as simple host name and IP address resolution.

Listening for incoming (passive) connections is also possible. Keep in mind that this generally only makes sense for local connections to 127.0.0.1, as the phone is usually part of a private network and not visible to the rest of the internet.

This module does not support IPv6.

• Connections Are Streams
• Internet Access Points
• net.accept
• net.adr
• net.cert
• net.conn
• net.iap
• net.iaps
• net.listen
• net.local
• net.name
• net.remote
• net.shut
• net.start
• net.stop
• net.timeout

Connections Are Streams

• io.read, io.readln, and io.readm receive data,
• io.write, io.writeln, io.writem, io.print, and io.println send data,
• io.avail gets the number of bytes which can be read without blocking,
• io.wait waits for data which can be read without blocking, or for an incoming connection,
• io.close closes the connection or listening socket.
• io.ces gets and sets the character encoding scheme. As with files, the default is io.raw.
• io.timeout sets the timeout for send, receive and wait operations.
• io.flush sets the auto flush state. If auto flushing is disabled, io.flush must be called to make sure all data is sent.

Internet Access Points

net.accept

Waits for a new incoming connection on the port defined by pstream, and returns it as a stream.

pstream is a passive stream which is obtained by call to net.listen. See there for a complete example.

net.adr

Resolves a host name to its IP address or addresses. The addresses are returned as an array of strings, each string representing the IP address in the standard dot notation.

print net.adr('www.google.com') → [216.239.59.103,216.239.59.104, 216.239.59.99,216.239.59.147]

See also: net.local, net.remote

net.cert

Gets the X.509 server certificate of the secure connection stream. The certificate identifies and (if it is valid) authenticates the host the connection has been made to.

This function returns null if stream is not secure.

The certificate is returned as an array with the following keys:

Key	Meaning	Type
subject	Certified subject (in X.500 format)	Array
issuer	Certificate issuer (in X.500 format)	Array
version	Certificate version	Number
serial	Certificate serial number	String
start	Start of validity period	Seconds
end	End of validity period	Seconds
md5	Fingerprint of certificate (MD5 hash)	String

subject and issuer are arrays containing key-value pairs, with the keys being hierarchical OID numbers. For instance, the key "2.5.4.3" stands for "Common Name", and "2.5.4.10" for "Organization Name".

start and end define the validity period of the certificate, in seconds since year zero, as used by module time.

serial and md5 encode each byte as a string character; use .code to convert them to single bytes.

// connect to a secure Web server s=net.conn("www.yellownet.ch", 443, net.ssl); // send a request io.write(s, 'GET / HTTP 1.1\r\n\r\n'); // read the first four lines for i=1 to 4 do   print io.readln(s) end → HTTP/1.1 302 Found Date: Tue, 24 May 2005 12:47:08 GMT Server: Stronghold Location: https://www.postfinance.ch/ // look at the certificate c=net.cert(s); print c["subject"]["2.5.4.3"] → www.yellownet.ch print c["subject"]["2.5.4.10"] → Die Schweizerische Post // close the connection io.close(s)

net.conn

Connects to the host host on TCP/IP port port. host can be a host name (e.g. "www.m-shell.net"), or an IP address (e.g. "212.117.205.10").

If secure=null, the connection is unsecure. To secure the connection, use one of the following constants:

• const ssl = "SSL3.0" Use SSL (Secure Sockets Layer) 3.0.
• const tls = "TLS1.0" Use TLS (Transport Layer Security) 1.0.

If silent=false, the user will be prompted when the certificate presented by the server cannot be authenticated or has expired, giving the user the opportunity to accept the certificate for this session.

If silent=true, an invalid certificate will simply throw ErrCertificateUnknown, or some other SSL exception.

authName indicates the expected name authenticated by the certificate. If authName=null, it defaults to host.

Compatibility of Secure Connections Sony Ericsson phones Unreliable, may hang

// connect to airbit's SMTP mail server s=net.conn("mail.airbit.ch", 25); // read the prompt print io.readln(s) → 220 mail.airbit.ch ESMTP ... // immediately logout again io.write(s, "QUIT\r\n"); // read the goodbye message print io.readln(s) → 221 Service closing transmission channel // close the connection io.close(s)

For a secure connection example, see net.cert.

net.iap

Sets and gets the preferred Internet Access Point (IAP) to use. The preferred IAP setting consists of an array with three elements:

Index	Meaning	Type
0	Prompt user for IAP when connecting	Boolean
1	Preferred IAP id	Number
2	Bearer types supported by this setting	Number

The preferred IAP id corresponds to an id of the IAP table in the phone, as returned by net.iaps. The bearer set defines the set of bearer types supported by this setting.

Without arguments, this function returns the current preferred IAP setting. With a single boolean argument, it returns the old setting and sets the "prompt user" flag. With an array argument, it updates the corresponding entries, depending on the length of the array (1 to 3 elements).

// get current setting s=net.iap(); print s → [false,14,3] // change the preferred IAP id to 2 and enable prompting net.iap([true, 2]) // disable prompting net.iap(false) // restore the old setting net.iap(s)

net.iaps

Returns the configured IAPs whose bearer matches one of the flags in bearerMask. The mask bits are the following:

• const csd = 1 circuit switched data: slow dialup connection.
• const wcdma = 2 wide band code division multiple access, a 3G (UMTS) technology; also includes GPRS if 3G is not available.
• const lan = 4 local area network, typically WLAN.
• const cdma2000 = 8 code division multiple access 2000, another 3G technology.
• const virtual = 16 virtual bearer using another transport.
Each array element returned is itself an array with the following fields:

Key	Meaning	Type
id	Internal IAP id	Number
name	IAP name	String

// get all IAPs for p in net.iaps() do   print p end → [1,Easy WLAN] [2,Swisscom GPRS] [3,Swisscom MMS] [4,Swisscom Internet] [5,Airbit WLAN] // get only local network (WLAN) IAPs for p in net.iaps(net.lan) do   print p end → [1,Easy WLAN] [5,Airbit WLAN] // use the last WLAN for further connections net.iap([false,p['id']])

net.listen

Creates a passive stream listening for incoming connections on the given port and address, and returns it. The address 0.0.0.0 allows connections to any valid IP address of the device. queue is the maximum number of queued unaccepted connections.

The passive stream can be passed to the following functions:

• net.accept waits for an incoming connection, and returns it.
• io.wait allows to simultaneously wait for an incoming connection and data being available on established connections or streams. If io.wait returns a passive stream, io.avail on this stream will return 1 afterwards.
• io.close closes the passive stream and stops listening on the given port, freeing it for other processes.

use net, io, array // create a passive stream listening on port 4242 p=net.listen(4242); m=[p]; // the monitored streams while true do // loop forever   // wait for a client   io.print(io.stdout, "Waiting...");   s=io.wait(m);   if s=p then // new connection, accept it     print "got new connection.";     append(m, net.accept(p))   else // data on existing connection     io.print(io.stdout, "reading...");     line=io.readln(s);     if line#null then       print "got", line;       io.writeln(s, reverse(line))     else // EOF, remove connection       print "lost connection.";       io.close(s);       array.remove(m, array.index(m, s))     end   end end → Waiting...got new connection. Waiting...got new connection. Waiting...reading...got Lucky Luke Waiting...reading...got Jolly Jumper Waiting...reading...lost connection. Waiting...

Sample client calls producing the above output are:

s1=net.conn('127.0.0.1', 4242); s2=net.conn('127.0.0.1', 4242); io.write(s1, 'Lucky Luke\n'); io.readln(s1) → ekuL ykcuL io.write(s2, 'Jolly Jumper\n'); io.readln(s2) → repmuJ ylloJ io.close(s1)

net.local

Returns the local (your own) IP address and port of the connection defined by stream as an array:

Key	Meaning	Type
adr	TCP/IP address	String
port	TCP/IP port	Number

Throws ErrBadHandle if stream is not an open connection.

s=net.conn('www.post.ch', 80); print net.local(s) → [10.122.18.7,32803]

net.name

Finds the host names belonging to an IP address. The IP address must be a string in standard dot notation. The names are returned as an array of strings.

Without arguments, returns the local (own) host name.

print net.name('62.65.129.6') → [mail.infowing.ch] print net.name() → [localhost]

net.remote

Returns the remote (the remote host's) IP address and port of the connection defined by stream as an array:

Key	Meaning	Type
adr	TCP/IP address	String
port	TCP/IP port	Number

Throws ErrBadHandle if stream is not an open connection.

p=net.listen(4242); s=net.accept(p); print net.remote(s) → [127.0.0.1,39934]

net.shut

Shuts the connection defined by stream down. If abort=false, shutdown is gracefully, i.e. all pending data is transmitted. If abort=true, sending and receiving is stopped immediately.

io.close also shuts down a connection, but net.shut gives finer control over connection termination, and allows to catch errors.

s=net.conn('mail.airbit.ch', 25); // abort the connection net.shut(s, true)

net.start

Starts the IAP connection.

Without argument, connects using the current IAP settings. This is normally not required, as connections are created on demand.

With argument, connects using the current IAP settings, but overrides the prompt flag: if prompt=false, the user is not prompted to choose an IAP; if prompt=true, the user is always prompted.

// start the connection without prompting for an IAP net.start(false)

net.stop

Stops the current IAP connection. Calling this function is normally not required, as connections are removed when they are no longer needed.

// change the IAP, then stop the connection net.iap([false, 7]); net.stop() // resolving a host name should restart the connection // with the new IAP net.adr('www.m-shell.net') → [62.202.44.142]

net.timeout

Gets or sets the timeout used when looking up names and when connecting. Without arguments, returns the current timeout in milliseconds. With one argument, returns the old timeout, and sets the new timeout to ms. Setting the timeout to zero (the default) or a negative value disables timeouts, i.e. TCP/IP operations can block indefinitely, or use a timeout defined by the underlying system.

Throws ExcValueOutOfRange if ms exceeds 2147483 (35 minutes and 47.483 seconds).

The timeout is used in all following name resolution, connect and shutdown calls: whenever an operation does not complete within the given number of milliseconds, it throws ErrTimedOut.

// give the phone 10 seconds to connect net.timeout(10000); try   s=net.conn("mail.airbit.ch", 25)   // connection successful... catch e by   if index(e, "ErrTimedOut") # 0 then throw e end;   print "Could not connect within 10 seconds" end