Socket Module
#socket:connect boolean socket:connect(string host, number port) false, string errorMessage socket.connect( string host, number port)

Attempts to connect to a server specified by the host and port number. The 'host' can either be an IP address (ie. "127.0.0.1") or a hostname ("www.example.com"). 'port' must be between 1 and 65535, but you should avoid commonly used ports (ie. 21, 80, etc.) unless you know what you're doing.

If the connection succeeds, this function returns true. If it fails, it returns false plus an error string.

Note: TCP only!

 #socket:listen boolean socket:listen(string host, number port) false, string errorMessage socket:listen( string host, number port)

Attempts to set this socket into "listen" mode. That is, it will act like a server and wait for new connections. The 'host' should probably be an empty string (ie. "") in order to accept connections from any incoming network, but you may also specify which network you would like (ie. "127.0.0.1" to only accept connections from localhost, "192.168.1.x" for LAN-only connections, etc.).

If this function succeeds, it will return true. Otherwise, it will return false plus an error string.

In UDP mode, make sure to call listen() before using sendto()! If you call sendto() first, the socket will be set to client-mode and not be able to properly bind to the given host/port.

 #socket:send boolean socket:send(string msg)

Attempts to send information across an already-connected socket. If the message was successfully sent, this function returns true, otherwise it returns false. The message ('msg') is sent as a string but may contain binary and embedded zeroes.

NOTE: TCP only!

 #socket:sendto boolean socket:sendto(string ip, number port, string msg) boolean socket:sendto(sockaddr sockAddr, string msg)

Attempts to send information across a UDP-connected socket. If the message was successfully sent, this function returns true, otherwise it returns false. The message ('msg') is sent as a string but may contain binary and embedded zeroes.

You may either specify an IP/port to send the message to, or (when responding to received messages) supply the sockaddr (see: Events:socketreceived)

NOTE: UDP only!

 #socket:recv string socket:recv() nil socket:recv()

If there are any messages in the input queue, returns the message on the top of the stack and pops it. Otherwise, returns nil.

It is probably a better idea to rely on capturing the socketreceived event rather than using using recv() in your main-loop. Use this function only if you know what you're doing.

 #socket:getRecvQueueSize number socket:getRecvQueueSize()

Returns the number of messages still in the receive queue.

 #socket:flushRecvQueue socket:flushRecvQueue()

Flushes (discards) all messages in the queue on this socket.

 #socket:close socket:close()

Closes a socket and shuts down related network threads. This will happen automatically as a socket object goes out of scope or is set to nil.

 #socket:id socket:id()

Returns the socket's ID. You may use this to uniquely identify the socket, however you should be aware that socket IDs may be recycled.

 #socket:ip socket:ip()

Returns the socket's IP. Generally only useful server-side to find out which IP you're listening on (clients will generally be 0.0.0.0 or "any").

 #socket:port socket:port()

Returns the socket's port. On the server, this will be the port you are 'listening' on, and on the client this will be assigned automatically.

Page last updated at 2018-09-25 20:48:33

Copyright 2024