socket package
socket contains no utilities.
License
The socket package is marked as Compatible, which means any game can use it.
Classes
Socket
All other classes in the socket package are subclasses of Socket.
- table = socket:GetAddressParts()
- Returns a table enumerating all the components this Socket needs for an address, along with their values (if they have been set) or false (if they haven't). IP-based sockets would return a table with "Host" and "Port" members, other protocols may return differently.
- Using this function and SetAddressPart, you can build a protocol-independent configuration dialog for setting up networked servers or clients. Exactly what address is referred to depends on whether the socket is a ListenSocket or a ConnectedSocket; a ListenSocket's address is the address to listen on, while a ConnectedSocket's address is the address to connect to.
- It is an error to call this function on a Socket that already has an address, whether by calling ApplyAddress or by originating from a ListenSocket.
- socket:SetAddressPart(part, value)
- Sets part of the address to value. A value that is a string will always be accepted, but other appropriate types may also be accepted, depending on the protocol. A IP-based sockets would expect parts "Host" and "Port", other protocols may expect more, fewer, or different parts.
- Using this function and GetAddressParts, you can build a protocol-independent configuration dialog for setting up networked servers or clients. Exactly what address is referred to depends on whether the socket is a ListenSocket or a ConnectedSocket; a ListenSocket's address is the address to listen on, while a ConnectedSocket's address is the address to connect to.
- It is an error to call this function on a Socket that already has an address, whether by calling ApplyAddress or by originating from a ListenSocket.
- success,error = socket:ApplyAddress()
- Fails with an error if not enough address parts were set. A game that sets every address part mentioned by GetAddressParts will not trigger this error.
- Returns false followed by an error string if the address was complete but invalid. (Unknown Host errors, etc.)
- Returns false followed by an error string if the connection failed (ConnectedSocket) or if setting up to listen failed (ListenSocket), but only if the socket is still valid.
- Fails with an error if the socket was invalidated by a failure. ("half-open" socket, for instance.)
- Returns true if all went well.
- It is an error to call this function on a Socket that already has an address, whether by calling ApplyAddress or by originating from a ListenSocket.
- socket:SetBlocking(whether)
- Informs the socket of whether or not it should block on requests such as Receive or Accept.
- Sockets default to not blocking.
- This function always succeeds, unless it throws an error.
- It may be an error to call SetBlocking on a socket you received from a ListenSocket:Accept(), depending on the protocol.
- address = socket:GetPrintableAddress()
- Returns a string containing a human-readable network address in whatever format is standard for the protocol in question. For a ListenSocket, this is the address being listened on; for a ConnectedSocket, this is the address of the peer.
- It is an error to call this function on a Socket that does not have an address. A Socket upon which ApplyAddress has succeeded is okay, as is a Socket that was returned by ListenSocket:Accept().
ListenSocket : Socket
A ListenSocket is a "server" Socket. It listens for incoming connections, creates ConnectedSockets of the appropriate type, and passes them to your code.
- client = listen:Accept()
- If a client is waiting (or, if blocking, a client eventually shows up), return that client as a ConnectedSocket of the appropriate type. Otherwise, return nil.
- Even a blocking socket can return nil, in which case the Accept call should just be repeated.
- Don't call this on a ListenSocket which does not have an address applied, unless you like errors.
A ListenSocket that returns SocketStreams. Don't forget to set up an address.
ListenSocketStream has no methods it didn't inherit.
- listen = SubCritical.Construct("ListenSocketStream")
A ListenSocket that returns SocketDgrams. Don't forget to set up an address.
ListenSocketDgram has no methods it didn't inherit.
- listen = SubCritical.Construct("ListenSocketDgram")
ConnectedSocket : Socket
A ConnectedSocket is a "client" or "peer" socket.
- input,error = socket:Receive(amount)
- Returns up to amount bytes read from socket. If blocking, wait if necessary.
- A SocketDgram will return only single packets.
- If no bytes were read from socket, return false followed by an error message. If that error message is "not ready", then you should simply wait and try again later. If we are a SocketDgram and the error is "packet too big", you did not provide a large enough amount. (The maximum possible size of a UDP packet is 65507, but a more common non-fragmented maximum is 1484.) Any other error message indicates that further Receives on this socket are futile.
- sent,error = socket:Send(output)
- Tries to send output (a string) over socket. A SocketDgram will return true on success (since partial datagrams cannot be sent), while a SocketStream will return the number of bytes sent, if any. In either case, if nothing was sent, return nil followed by an error message. If this error message is "not ready", you should simply wait and try again later. If we are a SocketDgram and the error is "packet too big", you should try sending a smaller packet if possible. (The maximum possible size of a UDP packet is 65507, above which an error will occur, but remember to take into account the Receive size at the other end.) Any other error message indicates that further Sends on this socket are futile.
A socket representing a reliable, in-order, continuous bytestream (like TCP). Don't forget to set up an address.
SocketStream has no methods it didn't inherit.
- socket = SubCritical.Construct("SocketStream")
A socket representing a series of unreliable, possibly out-of-order, possibly duplicated, discrete packets (like UDP). Don't forget to set up an address.
SocketDgram has no methods it didn't inherit.
- socket = SubCritical.Construct("SocketDgram")
Back to index