ballerina/udp

Overview

This module provides APIs for sending/receiving datagrams to/from another application process (local or remote) using UDP.

When the local host address or the IP address is not given to the optional localHost field, the localhost address is bound by default. The port number of the local port, which is used to connect to the remote server is determined randomly (ephemeral port).

Client

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

1udp:Client socketClient = check new;
2
3udp:Datagram datagram = {
4 remoteHost: "localhost",
5 remotePort : 48829,
6 data : "Hello Ballerina".toBytes()
7};
8
9check socketClient->sendDatagram(datagram);
10
11readonly & udp:Datagram result = check socketClient->receiveDatagram();
12
13check socketClient->close();

ConnectClient

The udp:ConnectClient is configured by providing the remoteHost and remotePort so that it only receives data from and sends data to the configured remote host. Once connected, data may not be received from or sent to any other hosts. The client remains connected until it is explicitly closed. If the number of bytes given to the writeBytes method is greater than the data size allowed by a datagram, it will iteratively send all the bytes with several datagrams.

1udp:ConnectClient socketClient = check new("localhost", 48829);
2
3string msg = "Hello Ballerina";
4check socketClient->writeBytes(msg.toBytes());
5
6readonly & byte[] result = check socketClient->readBytes();
7
8check socketClient->close();

Listener

The udp:Listener is used to listen to the incoming socket request.

The udp:Listener can have the following methods.

onBytes(readonly & byte[] data, udp:Caller caller) or onDatagram(readonly & udp:Datagram, udp:Caller): These remote methods get invoked once the content is received from the client. The client is represented using the udp:Caller.

onError(readonly & udp:Error err): This remote method is invoked in an error situation.

A udp:Listenercan be defined as follows:

1service on new udp:Listener(48829) {
2 remote function onDatagram(readonly & udp:Datagram datagram)
3 returns udp:Datagram|udp:Error? {
4 // Handle the content received from the client
5 }
6
7 remote function onError(udp:Error err) {
8 // Handle the error situation
9 }
10}

Listeners

[1]

Listener

This is used for creating the UDP server endpoints.

Clients

[3]

Caller

Represents caller object in UDP service remote methods.

Client

Initializes the UDP connectionless client based on the provided configurations.

ConnectClient

Initializes the UDP connection oriented client based on the provided configurations.

Object Types

[1]

Service

Represent UDP Listener service type.

Records

[4]

ClientConfiguration

Configurations for the connectionless UDP client.

ConnectClientConfiguration

Configurations for the connection oriented udp client.

Datagram

A self-contained, independent entity of data carrying sufficient information to be routed from the source to the destination nodes without reliance on earlier exchanges between the nodes and the transporting network.

ListenerConfiguration

Represents the UDP listener configuration.

Errors

[1]

Error

Represents udp module related errors.