Error

Represents caller object in UDP service remote methods.



The hostname or the IP address of the remote host


remoteHost

string

remotePort

Sends the response as byte[] to the same remote host.



sendBytes

The data need to be sent to the remote host


data

() or else a `udp:Error` if the given data can't be sent


Sends the response as datagram to a remote destination as
specified in datagram.



sendDatagram

Contains the data to be sent to the remote host
and the address of the remote host


datagram

Datagram

Caller

Initializes the UDP connectionless client based on the provided configurations.


Initializes the UDP connectionless client based on the provided 
configurations.
```ballerina
udp:Client|udp:Error? socketClient = new(localHost = "localhost");
```



init

Connectionless client-related configuration


config

ClientConfiguration

`()` or else a `udp:Error` if the given data cannot be sent


Sends the given data to the specified remote host.
```ballerina
udp:Error? result = socketClient->sendDatagram({remoteHost: "localhost",
           remotePort: 48826, data:"msg".toBytes()});
```



Reads data from the remote host. 
```ballerina
udp:Datagram|udp:Error result = socketClient->receiveDatagram();
```



receiveDatagram

A `udp:Datagram` or else a `udp:Error` if the data
cannot be read from the remote host


Free up the occupied socket.
```ballerina
udp:Error? closeResult = socketClient->close();
```



close

A `udp:Error` if it can't close the connection or else `()`


Client

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


Initializes the UDP connect client based on the 
provided configurations.
```ballerina
udp:ConnectClient|udp:Error? socketClient = new("www.remote.com", 80,
                             localHost = "localHost");
```


Connection oriented client related configuration


ConnectClientConfiguration

Sends the given data to the connected remote host.
```ballerina
udp:Error? result = socketClient->writeBytes("msg".toBytes());
```



writeBytes

The data need to be sent to the connected remote host


`()` or else a `udp:Error` if the given data can't be sent


Reads data only from the connected remote host. 
```ballerina
readonly & byte[]|udp:Error result = socketClient->readBytes();
```



readBytes

A `byte[]` or else a `udp:Error` if the data
cannot be read from the remote host


ConnectClient

## 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:

```ballerina
udp:Client socketClient = check new;

udp:Datagram datagram = {
    remoteHost: "localhost",
    remotePort : 48829,
    data : "Hello Ballerina".toBytes()
};

check socketClient->sendDatagram(datagram);

readonly & udp:Datagram result = check socketClient->receiveDatagram();

check 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.

```ballerina
udp:ConnectClient socketClient = check new("localhost", 48829);

string msg = "Hello Ballerina";
check socketClient->writeBytes(msg.toBytes());

readonly & byte[] result = check socketClient->readBytes();

check socketClient->close();
```

#### Listener
The `udp:Listener` is used to listen to the incoming socket request.<br/>

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:Listener`can be defined as follows:

```ballerina
service on new udp:Listener(48829) {
    remote function onDatagram(readonly & udp:Datagram datagram)
            returns udp:Datagram|udp:Error? {
        // Handle the content received from the client
    }

    remote function onError(udp:Error err) {
        // Handle the error situation
    }
}
```


This is used for creating the UDP server endpoints. A UDP server endpoint
is capable of responding to remote callers. The `udp:Listener` is
responsible for initializing the endpoint using the provided
configurations.


Initializes the UDP listener based on the privovided configurations. 
```ballerina
 listener Listener|error? udpServer = new (8080);
```


localPort

Configurations related to the `udp:Listener`


ListenerConfiguration

Binds a service to the `udp:Listener`.
```ballerina
udp:error? result = udpListener.attach(helloService);
```



attach

Service

name

`()` or else a `udp:Error` upon failure to register
the listener


error

Starts the registered service programmatically.



'start

An `error` if an error occurred during the listener 
starting process


Stops the service listener gracefully. Already-accepted requests will be
served before connection closure.



gracefulStop

An `error` if an error occurred during the listener
stopping process


Stops the service listener immediately. It is not implemented yet.



immediateStop

An `error` if an error occurred during the listener
stop process


Stops consuming messages and detaches the service from the `udp:Listener`.
```ballerina
udp:error? result = udpListener.detach(helloService);
```



detach

`()` or else a `udp:Error` upon failure to detach the service


Listener

Configurations for the connectionless UDP client.



The socket-reading timeout value to be used 
in seconds. If this is not set,the default value
of 300 seconds (5 minutes) will be used


timeout

decimal

localHost

Configurations for the connection oriented udp client.



The socket reading timeout value to be used 
in seconds. If this is not set,the default value
of 300 seconds (5 minutes) will be used


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.



The content which needs to be transported to the remote host


byte

Represents the UDP listener configuration.



The remote host's port number. If this is not set, the server
runs without connecting to a remote host


The interface for the server to be bound


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


Errors