Home
Ratchet Library :: API Reference
API  ·  Manual

Module ratchet.socketpad

The socketpad library provides a layer on top of the ratchet.socket library to manage buffered socket IO. This allows for more familiar usages and easier implementation of binary and ASCII socket protocols. These functions can fail, see error handling section in manual for details.

Functions

close (self) Calls close() on the underlying socket, provided purely as convenience.
new (socket) Returns a new socketpad object, using the given socket as the underlying engine to send and receive buffered IO.
peek (self) Peeks at the current, full contents of the socket buffer, without updating or changing them.
recv (self, stop) Attempts to receive a specific amount of data from the socket, receiving packets on the underlying socket until the criteria is met.
recv_remaining (self) Returns all remaining data in the socket buffer, without actually checking for new data.
send (self, data, more) Adds the given data to the send-buffer, and possibly flushes it to the underlying socket.
update_and_peek (self) Calls for one single update of the socket buffer, and then returns the full contents of the buffer.


Functions

close (self)
Calls close() on the underlying socket, provided purely as convenience.

Parameters

  • self: the socket object.
new (socket)
Returns a new socketpad object, using the given socket as the underlying engine to send and receive buffered IO. The socket object is available in raw form as the "socket" field of the returned socketpad object. A table for storing misc information related to the socketpad is available in the "data" field of the returned socketpad object.

Parameters

  • socket: A socket object to buffer.

Return value:

a new socketpad object.
peek (self)
Peeks at the current, full contents of the socket buffer, without updating or changing them.

Parameters

  • self: the socketpad object.

Return value:

string of data currently in the socket buffer.
recv (self, stop)
Attempts to receive a specific amount of data from the socket, receiving packets on the underlying socket until the criteria is met.

Parameters

  • self: the socketpad object.
  • stop: if given as a number, this method will attempt to receive that many bytes on the socket and return exactly that many. If given as a string, the socket will receive until that string is seen, everything up-to and including that string is returned.

Return value:

string of data received on the socket, or nil followed by an error message. If the first return is not nil, the second returned value will be true if only part of the requested data was received before the connection was remotely closed.
recv_remaining (self)
Returns all remaining data in the socket buffer, without actually checking for new data. This function empties the socket buffer. It is useful for checking for extra data that came along with previous calls to recv().

Parameters

  • self: the socketpad object.

Return value:

string of data cleared from the socket buffer.
send (self, data, more)
Adds the given data to the send-buffer, and possibly flushes it to the underlying socket.

Parameters

  • self: the socketpad object.
  • data: a string of data to send.
  • more: flag specifying more data will be buffered, so the send-buffer will not be flushed until this parameter is false.
update_and_peek (self)
Calls for one single update of the socket buffer, and then returns the full contents of the buffer. It is useful when you know new data is waiting on the socket but are not ready to do a full recv() on a criteria.

Parameters

  • self: the socketpad object.

Return value:

string of data in the socket buffer after a single update.