Standard library

tcp

Module tcp

Listener

CallerClient

ConnectionService
Service

CertKey
ClientConfiguration
ClientSecureSocket
ListenerConfiguration
ListenerSecureSocket

Protocol

Error

ballerina/tcp

1.6.0

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.

Copy

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:

Copy

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
Copy
Configuring TLS in client side
Copy

Listeners

tcp: Listener

Isolated

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.

Constructor

Initializes the TCP listener based on the provided configurations.

 listener Listener|error? server1 = new (8080);

init (int localPort, *ListenerConfiguration config)
  • localPort int - The port number of the remote service

attach

Isolated Function
function attach(Service tcpService, string[]|string? name) returns error?

Binds a service to the tcp:Listener.

Copy
Parameters
  • tcpService Service - Type descriptor of the service
Return Type
  • error? - () or else a tcp:Error upon failure to register the listener

'start

Isolated Function
function 'start() returns error?

Starts the registered service programmatically.

Return Type
  • error? - An error if an error occurred during the listener starting process

gracefulStop

Isolated Function
function gracefulStop() returns error?

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

Return Type
  • error? - An error if an error occurred during the listener stopping process

immediateStop

Isolated Function
function immediateStop() returns error?

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

Return Type
  • error? - An error if an error occurred during the listener stop process

detach

Isolated Function
function detach(Service tcpService) returns error?

Stops consuming messages and detaches the service from the tcp:Listener.

Copy
Parameters
  • tcpService Service - Type descriptor of the service
Return Type
  • error? - () or else a tcp:Error upon failure to detach the service

Clients

tcp: Caller

Isolated

Represents caller object in tcp service remote methods.

writeBytes

Isolated FunctionRemote Function
function writeBytes(byte[] data) returns Error?

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

Parameters
  • data byte[] - The data need to be sent to the remote host
Return Type
  • Error? - () or else a tcp:Error if the given data cannot be sent

close

Isolated FunctionRemote Function
function close() returns Error?

Close the remote connection.

Return Type
  • Error? - () or else a tcp:Error if the connection cannot be properly closed

tcp: Client

Isolated

Initializes the TCP connection client based on the provided configurations.

Constructor

Initializes the TCP client based on the provided configurations.

tcp:Client|tcp:Error? socketClient = new("www.remote.com", 80,
                             localHost = "localHost");

init (string remoteHost, int remotePort, *ClientConfiguration config)
  • remoteHost string - The hostname or the IP address of the remote host
  • remotePort int - The port number of the remote host

writeBytes

Remote Function
function writeBytes(byte[] data) returns Error?

Sends the given data to the connected remote host.

Copy
Parameters
  • data byte[] - The data that need to be sent to the connected remote host
Return Type
  • Error? - () or else a tcp:Error if the given data cannot be sent

readBytes

Remote Function
function readBytes() returns (readonly & byte[])|Error

Reads data only from the connected remote host.

Copy
Return Type
  • (readonly & byte[])|Error - The readonly & byte[] or else a tcp:Error if the data cannot be read from the remote host

close

Isolated FunctionRemote Function
function close() returns Error?

Frees up the occupied socket.

Copy
Return Type
  • Error? - A tcp:Error if it cannot close the connection or else ()

Object types

tcp: ConnectionService

Distinct

Represent TCP Listener ConnectionService service type.

tcp: Service

Distinct

Represent TCP Listener service type.

Records

tcp: CertKey

Closed record

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

Fields
  • certFile string - A file containing the certificate
  • keyFile string - A file containing the private key in PKCS8 format
  • keyPassword string? - Password of the private key if it is encrypted

tcp: ClientConfiguration

Closed record

Configurations for the connection-oriented TCP client.

Fields
  • localHost string? - Local binding of the interface
  • timeout decimal(default 300) - 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
  • writeTimeout decimal(default 300) - 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

tcp: ClientSecureSocket

Closed record

Secure Socket configuration for TCP Client.

Fields
  • enable boolean(default true) - Enable SSL validation
  • cert TrustStore|string? - Configurations associated with crypto:TrustStore or single certificate file that the client trusts
  • protocol record {| name Protocol, versions string[] |}? - SSL/TLS protocol related options
  • ciphers string[]? - List of ciphers to be used E.g., TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • handshakeTimeout decimal? - SSL handshake time out
  • sessionTimeout decimal? - SSL session time out

tcp: ListenerConfiguration

Closed record

Provides a set of configurations for tcp listener.

Fields
  • localHost string? - The hostname

tcp: ListenerSecureSocket

Closed record

Secure Socket configuration for TCP Listener.

Fields
  • key KeyStore|CertKey - Configurations associated with crypto:KeyStore or combination of certificate and (PKCS8) private key of the server
  • protocol record {| name Protocol, versions string[] |}? - SSL/TLS protocol related options
  • ciphers string[](default []) - List of ciphers to be used E.g., TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • handshakeTimeout decimal? - SSL handshake time out
  • sessionTimeout decimal? - SSL session time out

Enums

tcp: Protocol

Represents protocol options.

Members

SSL
TLS

Errors

tcp: Error

Distinct

Represents TCP module related errors.

Other versions

1.6.0

1.5.11.5.01.4.01.3.0
See more...

Terms of service

Privacy policy

Cookie policy

2023 WSO2