Socket Class

connect

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

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

listen

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

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!

sendto

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

boolean socket:sendto(userdata 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!

recv

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

getRecvQueueSize

number socket:getRecvQueueSize()

Returns the number of messages still in the receive queue.

flushRecvQueue

socket:flushRecvQueue()

Flushes all messages in the queue on this 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.

id

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

ip

string 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").

port

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