Represents caller object in tcp service remote methods.



The hostname or the IP address of the remote host


remoteHost

string

remotePort

localHost

The port number to which the socket is bound


localPort

The unique ID associated with the connection


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



writeBytes

The data need to be sent to the remote host


data

byte

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


Error

close

`()` or else a `tcp:Error` if the connection cannot be properly
closed


Caller

Initializes the TCP connection client based on the provided configurations.


Initializes the TCP client based on the provided configurations.
```ballerina
tcp:Client|tcp:Error? socketClient = new("www.remote.com", 80,
                             localHost = "localHost");
```


init

Connection-oriented client-related configurations


config

ClientConfiguration

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



The data that need to be sent to the connected remote host


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



readBytes

The `readonly & byte[]` or else a `tcp:Error` if the data cannot be read from the remote host


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



A `tcp:Error` if it cannot close the connection or else `()`


Client

## Overview

This module provides APIs for sending/receiving messages to/from another application process (local or remote) over the connection-oriented TCP protocol.

#### Client

The `tcp:Client` is used to connect to a socket server and interact with it.
The client can send the data to the server and retrieve the data from the server.

A client can be defined by providing the `remoteHost` and the `remotePort`. 
A simple client code is as follows.

```ballerina
import ballerina/tcp;

public function main() returns error? {
    tcp:Client socketClient = check new("localhost", 3000);

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

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

    check socketClient->close();
}
```

#### Listener
The `tcp:Listener` is used to listen to the incoming socket request. The `onConnect(tcp:Caller)` remote method gets invoked when a new client is connected. The new client is represented using the `tcp:Caller`. The `onConnect(tcp:Caller)` method may return `tcp:ConnectionService|tcp:Error`.

The `tcp:ConnectionService` can have the following remote methods

**onBytes(readonly & byte[] data)** - This remote method is invoked once the content is received from the client.

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

**onClose()** - This remote method is invoked when the connection is closed.

A `tcp:Listener` can be defined as follows:
```ballerina
import ballerina/tcp;
import ballerina/io;
import ballerina/log;

service on new tcp:Listener(3000) {
    remote function onConnect(tcp:Caller caller) returns tcp:ConnectionService {
        io:println("Client connected to echoServer: ", caller.remotePort);
        return new EchoService();
    }
}

service class EchoService {

    remote function onBytes(readonly & byte[] data) returns byte[]|tcp:Error? {
        // echo back the data to the client
        return data;
    }

    remote function onError(tcp:Error err) returns tcp:Error? {
        log:printError("An error occurred", 'error = err);
    }

    remote function onClose() returns tcp:Error? {
         io:println("Client left");
    }
}
```

#### Using the TLS protocol

The Ballerina TCP module allows the use of TLS in communication. This expects a secure socket to be set in the connection configuration as shown below.

##### Configuring TLS in server side
```ballerina
tcp:ListenerSecureSocket listenerSecureSocket = {
    key: {
        certFile: "../resource/path/to/public.crt",
        keyFile: "../resource/path/to/private.key"
    }
};

service on new tcp:Listener(9002, secureSocket = listenerSecureSocket) {
    isolated remote function onConnect(tcp:Caller caller) returns tcp:ConnectionService {
        return new EchoService();
    }
}
```

##### Configuring TLS in client side
```ballerina
tcp:Client socketClient = check new ("localhost", 9002, secureSocket = {
    cert: "../resource/path/to/public.crt",
});
```


Protocol

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


Initializes the TCP listener based on the provided configurations.
```ballerina
 listener Listener|error? server1 = new (8080);
```


Configurations related to the `tcp:Listener`


ListenerConfiguration

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



attach

tcpService

Service

name

`()` or else a `tcp: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 the 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 `tcp:Listener`.
```ballerina
tcp:error? result = tcpListener.detach(helloService);
```



detach

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


Listener

Represent TCP Listener ConnectionService service type.


ConnectionService

Represents a combination of the certificate, private key, and private key password (if encrypted).



certFile

A file containing the private key in PKCS8 format


keyFile

Password of the private key if it is encrypted


keyPassword

CertKey

Configurations for the connection-oriented TCP 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

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


writeTimeout

secureSocket

ClientSecureSocket

Secure Socket configuration for TCP Client.



enable

boolean

Configurations associated with `crypto:TrustStore` or single certificate file that the client trusts


cert

TrustStore

protocol

versions

List of ciphers to be used
E.g., `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`


ciphers

handshakeTimeout

sessionTimeout

Provides a set of configurations for tcp listener.



ListenerSecureSocket

Secure Socket configuration for TCP Listener.



Configurations associated with `crypto:KeyStore` or combination of certificate and (PKCS8) private key of the server


KeyStore

This module provides APIs for sending/receiving messages to/from another application process (local or remote) over the connection-oriented TCP protocol.


Client: Caller

Remote Methods

Fields

writeBytes

Parameters

Return Type

close

Return Type