Home
Ratchet Library :: API Reference
API  ·  Manual

Module ratchet.socket

The socket library provides an implementation of the standard Berkeley sockets on top of the ratchet library. Any methods that pause execution MUST be called from within a thread attached to a ratchet object. This library is also intended for use alongside calls to ratchet:resolve_dns(), see the manual for examples.

Functions

accept (self) Pauses the current thread until a new connection to the socket is attempted.
bind (self, sockaddr) Binds the socket to the given sockaddr, corresponding to the bind() system call.
check_ok (self) Gets the current state of the socket.
close (self) Closes the socket internal file descriptor.
connect (self, sockaddr) Attempts a connection to the given sockaddr and pauses the thread until it is completed.
encrypt (self, context) Creates and attaches an encryption session to the socket, based on the given context.
from_fd (fd) Returns a new socket object, using the given file descriptor.
get_encryption (self) Returns the current encryption session for the socket.
get_fd (self) Returns the internal socket file descriptor.
get_timeout (self) Gets the current timeout for all socket methods that pause the thread.
listen (self, backlog) Sets the socket to listen mode.
new (family, socktype, protocol) Returns a new socket object, with its own file descriptor.
prepare_tcp (host, port) Prepares TCP socket information.
prepare_udp (host, port) Prepares UDP socket information.
prepare_unix (path) Prepares UNIX socket information.
prepare_uri (uri) URI parser for socket connection strings.
recv (self) Attempts to receive data from across the socket, pausing the thread until data is available.
send (self, data) Attempts to send the given data across the socket, pausing the thread until it is able to do so.
set_timeout (self, seconds) Sets the current timeout for all socket methods that pause the thread.
shutdown (self, what) Shuts down portions of the socket, corresponding to the system call of the same name.


Functions

accept (self)
Pauses the current thread until a new connection to the socket is attempted. The current socket MUST have called listen().

Parameters

  • self: the socket object.

Return value:

a new socket object for the connection, followed by a string with the IP address of the connecting host.
bind (self, sockaddr)
Binds the socket to the given sockaddr, corresponding to the bind() system call. This method must be used for sockets that call listen(), and may be used for sockets that call connect() when it is desired to connect from a specific network interface.

Parameters

  • self: the socket object.
  • sockaddr: a sockaddr userdata object.
check_ok (self)
Gets the current state of the socket. If a fatal socket error has occurred, a Lua error is raised on the current thread.

Parameters

  • self: the socket object.

Return value:

true if the socket is okay, false otherwise followed by info.
close (self)
Closes the socket internal file descriptor. This is called automatically when the socket object is collected, for convenience.

Parameters

  • self: the socket object.
connect (self, sockaddr)
Attempts a connection to the given sockaddr and pauses the thread until it is completed.

Parameters

  • self: the socket object.
  • sockaddr: a sockaddr userdata object.

Return value:

true if the connection succeeded, false otherwise.
encrypt (self, context)
Creates and attaches an encryption session to the socket, based on the given context. Once this session is created, it handles all calls to the send()/recv() methods.

Parameters

  • self: the socket object.
  • context: a ratchet.ssl context object.

Return value:

the new encryption session for the socket.
from_fd (fd)
Returns a new socket object, using the given file descriptor. This is particularly useful when sockets are returned by the accept() system call.

Parameters

  • fd: an existing file descriptor of a socket.

Return value:

a new socket object.
get_encryption (self)
Returns the current encryption session for the socket.

Parameters

  • self: the socket object.

Return value:

the encryption session, or nil if unencrypted.
get_fd (self)
Returns the internal socket file descriptor.

Parameters

  • self: the socket object.

Return value:

a file descriptor.
get_timeout (self)
Gets the current timeout for all socket methods that pause the thread.

Parameters

  • self: the socket object.

Return value:

the current timeout in seconds.
listen (self, backlog)
Sets the socket to listen mode. This socket will open the system port it was bind()ed to. Connections to this socket can be accepted by the accept() method.

Parameters

  • self: the socket object.
  • backlog: optional maximum length of pending connections queue.
new (family, socktype, protocol)
Returns a new socket object, with its own file descriptor.

Parameters

  • family: the protocol family which will be used for communication.
  • socktype: specifies the communication semantics.
  • protocol: specifies a particular protocol to be used.

Return value:

a new socket object.
prepare_tcp (host, port)
Prepares TCP socket information. On success, the returned object contains all necessary data to create and bind/connect a new socket object. See the manual page for complete details. If host is not an IP address, this call will pause the current thread to wait for a DNS lookup.

Parameters

  • host: queried by DNS for new TCP connection.
  • port: destination port number for new TCP connection.

Return value:

Table of information useful in creating a new socket, or nil on failure followed by an error. See the manual for details.
prepare_udp (host, port)
Prepares UDP socket information. On success, the returned object contains all necessary data to create and bind/connect a new socket object. See the manual page for complete details. If host is not an IP address, this call will pause the current thread to wait for a DNS lookup.

Parameters

  • host: queried by DNS for new UDP connection.
  • port: destination port number for new UDP connection.

Return value:

Table of information useful in creating a new socket, or nil on failure followed by an error. See the manual for details.
prepare_unix (path)
Prepares UNIX socket information. On success, the returned object contains all necessary data to create and bind/connect a new socket object. See the manual page for complete details.

Parameters

  • path: file-path to connect/create UNIX socket.

Return value:

Table of information useful in creating a new socket, or nil on failure followed by an error. See the manual for details.
prepare_uri (uri)
URI parser for socket connection strings. On success, the returned object contains all necessary data to create and bind/connect a new socket object. The parser is capable of creating TCP, UDP, and Unix sockets. See the manual page for complete details. Depending on the URI schema, this call *may* block until data is ready, such as for DNS lookups.

Parameters

  • uri: the URI connection string.

Return value:

Table of information useful in creating a new socket, or nil on failure followed by an error. See the manual for details.
recv (self)
Attempts to receive data from across the socket, pausing the thread until data is available. As in the system call, recv() will return an empty string if the other end has shutdown.

Parameters

  • self: the socket object.

Return value:

string of data received on the socket.
send (self, data)
Attempts to send the given data across the socket, pausing the thread until it is able to do so.

Parameters

  • self: the socket object.
  • data: a string of data to send.
set_timeout (self, seconds)
Sets the current timeout for all socket methods that pause the thread.

Parameters

  • self: the socket object.
  • seconds: the new timeout in seconds.
shutdown (self, what)
Shuts down portions of the socket, corresponding to the system call of the same name. You can shut down reads, writes, or both.

Parameters

  • self: the socket object.
  • what: either "read", "write", or "both". Default "both".