docs » hs.socket

Timeout for the socket operations, in seconds.

• New hs.socket objects will be created with this timeout value, but can individually change it with the hs.socket:setTimeout method.

• If the timeout value is negative, the operations will not use a timeout. The default value is -1.

Parses a binary socket address structure into a readable table.

• sockaddr - A binary socket address structure, usually obtained from the info method or in hs.socket.udp's read callback.

• A table describing the address with the following keys or nil:
• host - A string containing the host IP.
• port - A number containing the port.
• addressFamily - A number containing the address family.

• Some address family definitions from <sys/socket.h>:

address family | number | description :--- | :--- | : AF_UNSPEC | 0 | unspecified AF_UNIX | 1 | local to host (pipes) AF_LOCAL | AF_UNIX | backward compatibility AF_INET | 2 | internetwork: UDP, TCP, etc. AF_NS | 6 | XEROX NS protocols AF_CCITT | 10 | CCITT protocols, X.25 etc AF_APPLETALK | 16 | Apple Talk AF_ROUTE | 17 | Internal Routing Protocol AF_LINK | 18 | Link layer interface AF_INET6 | 30 | IPv6

Creates an unconnected asynchronous TCP socket object.

• fn - An optional callback function for reading data from the socket, settable here for convenience.

• An hs.socket object.

Creates a TCP socket, and binds it to either a port or path (Unix domain socket) for listening.

• port - A port number [0-65535]. Ports [1-1023] are privileged. Port 0 allows the OS to select any available port.
• path - A string containing the path to the Unix domain socket.
• fn - An optional callback function for reading data from the socket, settable here for convenience.

• An hs.socket object.

Connects an unconnected socket.

• host - A string containing the hostname or IP address.
• port - A port number [1-65535].
• path - A string containing the path to the Unix domain socket.
• fn - An optional single-use callback function to execute after establishing the connection. The callback receives no parameters.

• The hs.socket object, or nil if an error occurred.

• Either a host/port pair OR a Unix domain socket path must be supplied. If no port is passed, the first parameter is assumed to be a path to the socket file.

Returns the connection status of the socket.

• None

• true if the socket is connected, otherwise false.

• If the socket is bound for listening, this method returns true if there is at least one connection.

Returns the number of connections to the socket.

• None

• The number of connections to the socket.

• This method returns at most 1 for default (non-listening) sockets.

Disconnects the socket, freeing it for reuse.

• None

• The hs.socket object.

• If called on a listening socket with multiple connections, each client is disconnected.

Returns information about the socket.

• None

• A table containing the following keys:
  • connectedAddress - string (sockaddr struct)
  • connectedHost - string
  • connectedPort - number
  • connectedURL - string
  • connections - number
  • isConnected - boolean
  • isDisconnected - boolean
  • isIPv4 - boolean
  • isIPv4Enabled - boolean
  • isIPv4PreferredOverIPv6 - boolean
  • isIPv6 - boolean
  • isIPv6Enabled - boolean
  • isSecure - boolean
  • localAddress - string (sockaddr struct)
  • localHost - string
  • localPort - number
  • timeout - number
  • unixSocketPath - string
  • userData - string

Binds an unconnected socket to either a port or path (Unix domain socket) for listening.

• port - A port number [0-65535]. Ports [1-1023] are privileged. Port 0 allows the OS to select any available port.
• path - A string containing the path to the Unix domain socket.

• The hs.socket object, or nil if an error occurred.

Read data from the socket.

• delimiter - Either a number of bytes to read, or a string delimiter such as "\n" or "\r\n". Data is read up to and including the delimiter.
• tag - An optional integer to assist with labeling reads. It is passed to the callback to assist with implementing state machines for processing complex protocols.

• The hs.socket object, or nil if an error occurred.

• Results are passed to the socket's callback function, which must be set to use this method.
• If called on a listening socket with multiple connections, data is read from each of them.

Alias for hs.socket:read

Alias for hs.socket:write

Sets the read callback for the socket.

• fn - An optional callback function to process data read from the socket. nil or no argument clears the callback. The callback receives 2 parameters:
  • data - The data read from the socket as a string.
  • tag - The integer tag associated with the read call, which defaults to -1.

• The hs.socket object.

• A callback must be set in order to read data from the socket.

Sets the timeout for the socket operations.

• timeout - A number containing the timeout duration, in seconds.

• The hs.socket object.

• If the timeout value is negative, the operations will not use a timeout, which is the default.

Secures the socket with TLS.

• verify - An optional boolean that, if false, allows TLS handshaking with servers with self-signed certificates and does not evaluate the chain of trust. Defaults to true and omitted if peerName is supplied
• peerName - An optional string containing the fully qualified domain name of the peer to validate against — for example, store.apple.com. It should match the name in the X.509 certificate given by the remote party. See the important security note below.

• The hs.socket object.

• The socket will disconnect immediately if TLS negotiation fails.
• IMPORTANT SECURITY NOTE: The default settings will check to make sure the remote party's certificate is signed by a trusted 3rd party certificate agency (e.g. verisign) and that the certificate is not expired. However it will not verify the name on the certificate unless you give it a name to verify against via peerName. The security implications of this are important to understand. Imagine you are attempting to create a secure connection to MySecureServer.com, but your socket gets directed to MaliciousServer.com because of a hacked DNS server. If you simply use the default settings, and MaliciousServer.com has a valid certificate, the default settings will not detect any problems since the certificate is valid. To properly secure your connection in this particular scenario you should set peerName to "MySecureServer.com".

Write data to the socket.

• message - A string containing data to be sent on the socket.
• tag - An optional integer to assist with labeling writes.
• fn - An optional single-use callback function to execute after writing data to the socket. The callback receives the tag parameter provided here.

• The hs.socket object.

• If called on a listening socket with multiple connections, data is broadcast to all connected sockets.