class SF::TcpSocket

Overview

Specialized socket using the TCP protocol

TCP is a connected protocol, which means that a TCP socket can only communicate with the host it is connected to. It can't send or receive anything if it is not connected.

The TCP protocol is reliable but adds a slight overhead. It ensures that your data will always be received in order and without errors (no data corrupted, lost or duplicated).

When a socket is connected to a remote host, you can retrieve informations about this host with the remote_address and remote_port functions. You can also get the local port to which the socket is bound (which is automatically chosen when the socket is connected), with the local_port function.

Sending and receiving data can use either the low-level or the high-level functions. The low-level functions process a raw sequence of bytes, and cannot ensure that one call to Send will exactly match one call to Receive at the other end of the socket.

The high-level interface uses packets (see SF::Packet), which are easier to use and provide more safety regarding the data that is exchanged. You can look at the SF::Packet class to get more details about how they work.

The socket is automatically disconnected when it is destroyed, but if you want to explicitly close the connection while the socket instance is still alive, you can call disconnect.

Usage example:

# ----- The client -----

# Create a socket and connect it to 192.168.1.50 on port 55001
socket = SF::TcpSocket.new
socket.connect("192.168.1.50", 55001)

# Send a message to the connected host
message = "Hi, I am a client"
socket.send(message.to_slice)

# Receive an answer from the server
buffer = Slice(UInt8).new(1024)
status, received = socket.receive(buffer)
puts "The server said: #{buffer}"

# ----- The server -----

# Create a listener to wait for incoming connections on port 55001
listener = SF::TcpListener.new
listener.listen(55001)

# Wait for a connection
socket = SF::TcpSocket.new
listener.accept(socket)
puts "New client connected: #{socket.remote_address}"

# Receive a message from the client
buffer = Slice(UInt8).new(1024)
status, received = socket.receive(buffer)
puts "The client said: #{buffer}"

# Send an answer
message = "Welcome, client"
socket.send(message.to_slice)

See also: SF::Socket, SF::UdpSocket, SF::Packet

Defined in:

network/obj.cr

Constructors

Instance Method Summary

Instance methods inherited from class SF::Socket

blocking=(blocking : Bool) blocking=, blocking? : Bool blocking?, finalize finalize

Constructor Detail

def self.new #

Default constructor


[View source]

Instance Method Detail

def connect(remote_address : IpAddress, remote_port : Int, timeout : Time = Time::Zero) : Socket::Status #

Connect the socket to a remote peer

In blocking mode, this function may take a while, especially if the remote peer is not reachable. The last parameter allows you to stop trying to connect after a given timeout. If the socket is already connected, the connection is forcibly disconnected before attempting to connect again.

  • remote_address - Address of the remote peer
  • remote_port - Port of the remote peer
  • timeout - Optional maximum time to wait

Returns: Status code

See also: #disconnect


[View source]
def disconnect #

Disconnect the socket from its remote peer

This function gracefully closes the connection. If the socket is not connected, this function has no effect.

See also: #connect


[View source]
def finalize #
Description copied from class SF::Socket

Destructor


[View source]
def local_port : UInt16 #

Get the port to which the socket is bound locally

If the socket is not connected, this function returns 0.

Returns: Port to which the socket is bound

See also: #connect, #remote_port


[View source]
def receive(data : Slice) : Tuple(Socket::Status, Int32) #

Receive raw data from the remote peer

In blocking mode, this function will wait until some bytes are actually received. This function will fail if the socket is not connected.

  • data - The slice to fill with the received bytes

Returns:

  • Status code
  • The actual number of bytes received

See also: #send


[View source]
def receive(packet : Packet) : Socket::Status #

Receive a formatted packet of data from the remote peer

In blocking mode, this function will wait until the whole packet has been received. This function will fail if the socket is not connected.

  • packet - Packet to fill with the received data

Returns: Status code

See also: #send


[View source]
def remote_address : IpAddress #

Get the address of the connected peer

It the socket is not connected, this function returns SF::IpAddress::None.

Returns: Address of the remote peer

See also: #remote_port


[View source]
def remote_port : UInt16 #

Get the port of the connected peer to which the socket is connected

If the socket is not connected, this function returns 0.

Returns: Remote port to which the socket is connected

See also: #remote_address


[View source]
def send(data : Slice) : Tuple(Socket::Status, Int32) #

Send raw data to the remote peer

This function will fail if the socket is not connected.

  • data - Slice containing the bytes to send

Returns:

  • Status code
  • The number of bytes sent

See also: #receive


[View source]
def send(packet : Packet) : Socket::Status #

Send a formatted packet of data to the remote peer

In non-blocking mode, if this function returns SF::Socket::Partial, you must retry sending the same unmodified packet before sending anything else in order to guarantee the packet arrives at the remote peer uncorrupted. This function will fail if the socket is not connected.

  • packet - Packet to send

Returns: Status code

See also: #receive


[View source]