capacitor-tcp-socket

A TCP Socket Plugin for Capacitor, providing TCP communication capabilities in mobile applications.

Thanks to @ottimis

Installation

npm install capacitor-tcp-socket
npx cap sync

Basic Usage

import { TcpSocket } from 'capacitor-tcp-socket';

// Connect to TCP server
const connect = async () => {
  try {
    const result = await TcpSocket.connect({
      ipAddress: '192.168.1.100',
      port: 9100
    });
    console.log(`Connected with client ID: ${result.client}`);
    return result.client;
  } catch (error) {
    console.error('Connection failed:', error);
  }
};

// Send data
const sendData = async (clientId: number) => {
  try {
    await TcpSocket.send({
      client: clientId,
      data: 'Hello, TCP Server!'
    });
    console.log('Data sent successfully');
  } catch (error) {
    console.error('Send failed:', error);
  }
};

// Read data
const readData = async (clientId: number) => {
  try {
    const result = await TcpSocket.read({
      client: clientId,
      expectLen: 1024,  // Expected maximum bytes to read
      timeout: 10       // Timeout in seconds, iOS only
    });
    console.log('Received data:', result.result);
    return result.result;
  } catch (error) {
    console.error('Read failed:', error);
  }
};

// Disconnect
const disconnect = async (clientId: number) => {
  try {
    const result = await TcpSocket.disconnect({
      client: clientId
    });
    console.log(`Disconnected client: ${result.client}`);
  } catch (error) {
    console.error('Disconnect failed:', error);
  }
};

// Usage example
const main = async () => {
  const clientId = await connect();
  if (clientId !== undefined) {
    await sendData(clientId);
    const data = await readData(clientId);
    await disconnect(clientId);
  }
};

Working with Different Encodings

This plugin supports multiple data encodings for handling various types of data:

Using UTF-8 Encoding (Default)

import { TcpSocket, DataEncoding } from 'capacitor-tcp-socket';

// Send text data using UTF-8 encoding
await TcpSocket.send({
  client: clientId,
  data: 'Hello, World!',
  encoding: DataEncoding.UTF8 // Optional, UTF8 is the default
});

// Read data as UTF-8 text
const result = await TcpSocket.read({
  client: clientId,
  expectLen: 1024,
  encoding: DataEncoding.UTF8 // Optional, UTF8 is the default
});

console.log('Received text:', result.result);
console.log('Received encoding:', result.encoding);

Using Base64 Encoding for Binary Data

import { TcpSocket, DataEncoding } from 'capacitor-tcp-socket';

// Send binary data using Base64 encoding
const binaryData = new Uint8Array([0x48, 0x65, 0x6C, 0x6C, 0x6F]); // "Hello" in ASCII
const base64Data = btoa(String.fromCharCode.apply(null, binaryData));

await TcpSocket.send({
  client: clientId,
  data: base64Data,
  encoding: DataEncoding.BASE64
});

// Read binary data as Base64
const result = await TcpSocket.read({
  client: clientId,
  expectLen: 1024,
  encoding: DataEncoding.BASE64
});

// Convert Base64 back to binary if needed
const binaryResult = new Uint8Array(
  atob(result.result)
    .split('')
    .map(c => c.charCodeAt(0))
);

Using Hexadecimal Encoding

import { TcpSocket, DataEncoding } from 'capacitor-tcp-socket';

// Send data using hex encoding
const hexData = "48656C6C6F"; // "Hello" in hex

await TcpSocket.send({
  client: clientId,
  data: hexData,
  encoding: DataEncoding.HEX
});

// Read data as hex string
const result = await TcpSocket.read({
  client: clientId,
  expectLen: 1024,
  encoding: DataEncoding.HEX
});

console.log('Received hex data:', result.result);
// Example output: "48656C6C6F"

// Convert hex to binary if needed
function hexToBytes(hex) {
  const bytes = [];
  for (let c = 0; c < hex.length; c += 2) {
    bytes.push(parseInt(hex.substr(c, 2), 16));
  }
  return new Uint8Array(bytes);
}

const binaryFromHex = hexToBytes(result.result);

Platform-Specific Considerations

Web

• Not supported on the web platform.

iOS

• iOS implementation uses the SwiftSocket library for TCP functionality.
• Supports setting a timeout for read operations (via the timeout parameter).

Android

• Android implementation uses the standard Java Socket API.
• Currently, the read timeout parameter is not supported on Android.

Example Project

Check out the example directory to see a complete sample application.

Running the example app:

cd example
npm install
npm start

API

• connect(...)
• send(...)
• read(...)
• disconnect(...)
• Interfaces
• Enums

TCP Socket Plugin interface for Capacitor Provides methods for TCP socket communication

connect(...)

connect(options: ConnectOptions) => Promise<ConnectResult>

Connects to a TCP server

| Param | Type | Description | | ------------- | --------------------------------------------------------- | ------------------------------------------------ | | options | ConnectOptions | Connection options including IP address and port |

Returns: Promise<ConnectResult>

send(...)

send(options: SendOptions) => Promise<void>

Sends data to a connected TCP server

| Param | Type | Description | | ------------- | --------------------------------------------------- | --------------------------------------------------- | | options | SendOptions | Send options including client ID, data and encoding |

read(...)

read(options: ReadOptions) => Promise<ReadResult>

Reads data from a connected TCP server

| Param | Type | Description | | ------------- | --------------------------------------------------- | ------------------------------------------------------------- | | options | ReadOptions | Read options including client ID, expected length and timeout |

Returns: Promise<ReadResult>

disconnect(...)

disconnect(options: DisconnectOptions) => Promise<DisconnectResult>

Disconnects from a TCP server

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | --------------------------------- | | options | DisconnectOptions | Disconnect options with client ID |

Returns: Promise<DisconnectResult>

Interfaces

ConnectResult

Result of a successful connection

| Prop | Type | Description | | ------------ | ------------------- | ---------------------------------------------------- | | client | number | Client ID that can be used for subsequent operations |

ConnectOptions

Options for connecting to a TCP server

| Prop | Type | Description | Default | | --------------- | ------------------- | -------------------------------------- | ----------------- | | ipAddress | string | IP address of the server to connect to | | | port | number | Port number of the TCP server | 9100 |

SendOptions

Options for sending data to a TCP server

| Prop | Type | Description | Default | | -------------- | ----------------------------------------------------- | -------------------------------------- | ------------------------------ | | client | number | Client ID from a previous connect call | | | data | string | Data string to send to the server | | | encoding | DataEncoding | Encoding type for the data | DataEncoding.UTF8 |

ReadResult

Result of a read operation

| Prop | Type | Description | | -------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | result | string | Data read from the server Can be UTF-8 string, Base64 encoded string, or Hex string depending on the encoding option | | encoding | DataEncoding | The encoding of the returned result |

ReadOptions

Options for reading data from a TCP server

| Prop | Type | Description | Default | | --------------- | ----------------------------------------------------- | -------------------------------------- | ------------------------------ | | client | number | Client ID from a previous connect call | | | expectLen | number | Expected number of bytes to read | | | timeout | number | Read timeout in seconds | 10 | | encoding | DataEncoding | Preferred encoding for returned data | DataEncoding.UTF8 |

DisconnectResult

Result of a disconnect operation

| Prop | Type | Description | | ------------ | ------------------- | ------------------------------- | | client | number | Client ID that was disconnected |

DisconnectOptions

Options for disconnecting from a TCP server

| Prop | Type | Description | | ------------ | ------------------- | -------------------------------------- | | client | number | Client ID from a previous connect call |

Enums

DataEncoding

| Members | Value | Description | | ------------ | --------------------- | ------------------- | | UTF8 | 'utf8' | UTF-8 text encoding | | BASE64 | 'base64' | Base64 encoded data | | HEX | 'hex' | Hexadecimal string |