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 which the socket is binded


localPort

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



writeBytes

The data need to be sent to the remote host


data

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


Error

close

() or else a `tcp:Error` if the connection can't 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 configuration


config

ClientConfiguration

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



The data 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
can't be read from the remote host


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



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


Client

## Package Overview

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

#### Client

The `tcp:Client` is used to connect to a socket server and interact with it.
The client can simply 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 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 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");
    }
}
```

For information on the operations, which you can perform with this package, see the below **Functions**. For examples on the usage of the operations, see the following.
 * [Basic TCP Client Example](https://ballerina.io/learn/by-example/tcp-client.html)
 * [Basic TCP Listener Example](https://ballerina.io/learn/by-example/tcp-listener.html)

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 privovided configurations. 
```ballerina
 listener Listener|error? server1 = new (8080);
```


Configurations related to the `tcp:Listener`


ListenerConfiguration

error

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



attach

Service

name

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


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 `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

onConnect

caller

Represents combination of 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

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

    record {|
        Protocol name;
        string[] versions = [];
    |} 

List of ciphers to be used
eg: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA


ciphers

handshakeTimeout

sessionTimeout

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 package provides an implementation for sending/receiving messages to/from another application process (local or remote) for both connection-oriented protocols.


Initializes the TCP connection client based on the 
provided configurations.

This is used for creating TCP server endpoints.

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

Represent TCP Listener ConnectionService service type.

Represents combination of certificate, private key and private key password if encrypted.

Configurations for the connection oriented tcp client.

Secure Socket configuration for TCP Client.

Secure Socket configuration for TCP Listener.

ballerina/tcp
0.8.0-alpha8
1.0.0 0.8.0-beta.2 0.8.0-beta.1 0.8.0-alpha8

Package Overview

Client

Listener

Listeners

Clients

Object Types

Records

Enums

Errors

ballerina/tcp0.8.0-alpha81.0.00.8.0-beta.20.8.0-beta.10.8.0-alpha8

Package Overview

Client

Listener

Listeners

Clients

Object Types

Records

Enums

Errors

ballerina/tcp
0.8.0-alpha8
1.0.0 0.8.0-beta.2 0.8.0-beta.1 0.8.0-alpha8