This API documentation is for Ballerina 1.2.0. View API documentation for the latest release.

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.