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. Most of these functions can fail, see error handling section in manual for details.

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_errors (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.
hton (in, use_16) Converts a number into a byte-string ready to be sent over the network.
listen (self, backlog) Sets the socket to listen mode.
new (family, socktype, protocol) Returns a new socket object, with its own file descriptor.
ntoh (in) Converts a byte-string from network byte-order to host byte-order.
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_errors (self)
Gets the current state of the socket. Returns true if the socket is connected and not in an error state, or returns nil and an error otherwise.

Parameters

  • self: the socket object.

Return value:

true if the socket is okay. See error handling section in manual.
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. See ratchet.ssl.session for details.
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.
hton (in, use_16)
Converts a number into a byte-string ready to be sent over the network. This is necessary only for binary socket protocols. See manpage byteorder(3).

Parameters

  • in: the number to be converted.
  • use_16: if given and true, the number is truncated to 16-bits and the resulting string is only two bytes long.

Return value:

a byte-string in network byte-order ready to be sent over the network.
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.
ntoh (in)
Converts a byte-string from network byte-order to host byte-order. This is necessary only for binary socket protocols. Takes a 2- or 4-byte string from the socket and returns the regular number after conversion. See manpage byteorder(3).

Parameters

  • in: the binary input string from the socket to convert to a number.

Return value:

the resulting number after conversion.
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 shut down.

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