Module : socket

Module Overview

This module provides an implementation for sending/receiving messages to/from another application process (local or remote) for both connection-oriented and connectionless protocols.

TCP Client

The socket:Client is used to connect to a socket server and interact with it. The client can only send the data to the server and the client's call-back service can retrieve the data from the server and do multiple requests/responses between the client and the server.

A Client can be defined by providing the host, port, and callbackService as follows.

socket:Client socketClient = new ({host: "localhost", port: 61598, callbackService: ClientService});
string msg = "Hello Ballerina\n";
byte[] message = msg.toBytes();
var writeResult = socketClient->write(message);

A client's call-back service can be defined as follows:

service ClientService = service {
    resource function onConnect(socket:Caller caller) {
        io:println("connect: ", caller.remotePort);
    }
}

UDP Client

The socket:UdpClient is used to interact with the remote UDP host and it can be defined as follows:

socket:UdpClient socketClient = new;
string msg = "Hello from UDP client";
byte[] message = msg.toBytes();
int|socket:Error sendResult = socketClient->sendTo(message, { host: "localhost", port: 48826 });

Listener

The socket:Listener is used to listen to the incoming socket request. The onConnect(socket:Caller) resource function gets invoked when a new client is connected. The new client is represented using the socket:Caller. The onReadReady(socket:Caller) resource gets invoked once the remote client sends some data.

A socket:Listener can be defined as follows:

listener socket:Listener server = new(61598);
service echoServer on server {

    resource function onConnect(socket:Caller caller) {
        io:println("connect: ", caller.remotePort);
    }

    resource function onReadReady(socket:Caller caller) {
        [byte[], int]|socket:ReadTimedOutError result = caller->read();
    }
}

For information on the operations, which you can perform with this module, see the below Functions. For examples on the usage of the operations, see the following.

Records

Address This represent the IP socket address.
ClientConfig Configurations for the socket client.
Detail Record type to hold the details of an error.
ListenerConfig Represents the socket server configuration.
UdpClientConfig Configurations for the UDP client.

Clients

Client Represents the socket client and related remote functions.
UdpClient Initializes the UDP client based on the provided configurations.

Listeners

Listener Represents the socket listener on which the socket listener service is registered and started.

Constants

READ_TIMED_OUT This will used to construct a ReadTimedOutError.
GENERIC_ERROR This will used to construct a GENERIC_ERROR.

Types

Caller Represents caller object in socket service resources and client callback service resources.
Error Represents socket module related errors.

Errors

GenericError Represents generic socket error.
ReadTimedOutError This will returns once the given read timed out time exceed for socket reads.