Socket Connection

Overview

The Socket Connection module allows an application to transmit data over a socket connection through the TCP, UDP, Multicast, or TLS protocol.

Basic Concepts

• Socket: An abstraction of endpoints for bidirectional communication between application processes running on different hosts in a network.
• TCP: Transmission Control Protocol, which is a byte stream–based transport layer communication protocol that is connection-oriented and reliable.
• UDP: User Datagram Protocol, which is a simple datagram-oriented transport layer communication protocol.
• Multicast: A UDP-based communication mode that implements broadcast communication between all devices in a group.
• LocalSocket: An inter-process communication (IPC) mechanism that implements communication between processes on a device without using a network.
• TLS: Transport Layer Security, which is a protocol that ensures the data confidentiality and integrity between communication programs.

When to Use

Applications transmit data over TCP, UDP, Multicast, or TLS socket connections. The main application scenarios are as follows:

• Implementing data transmission over TCP socket or UDP socket connections
• Implementing data transmission over TCP socket server connections
• Implementing data transmission over multicast socket connections
• Implementing data transmission over local socket connections
• Implementing data transmission over local socket server connections
• Implementing encrypted data transmission over TLS socket connections
• Implementing encrypted data transmission over TLS socket server connections

Available APIs

For the complete list of APIs and example code, see Socket Connection.

Socket connection functions are mainly implemented by the socket module. The following table describes the related APIs.

TLS socket connection functions are mainly provided by the tls_socket module. The following table describes the related APIs.

Transmitting Data over TCP Socket or UDP Socket Connections

The implementation is similar for UDP socket and TCP socket connections. The following uses data transmission over a TCP socket connection as an example.

1. Import the required socket module.

2. Create a TCP socket connection. A TCPSocketConnction object is returned.

3. (Optional) Subscribe to events of the TCPSocketConnction object.

4. Bind the IP address and port number. The port number can be specified or randomly allocated by the system.

5. Set up a connection to the specified IP address and port number.

6. Send data over the connection.

7. Enable the TCP socket connection to be automatically closed after use.

import socket from '@ohos.net.socket';
import { BusinessError } from '@ohos.base';

class SocketInfo {
  message: ArrayBuffer = new ArrayBuffer(1);
  remoteInfo: socket.SocketRemoteInfo = {} as socket.SocketRemoteInfo;
}
// Create a TCP socket connection. A TCPSocket object is returned.
let tcp = socket.constructTCPSocketInstance();
tcp.on('message', (value: SocketInfo) => {
  console.log("on message");
  let buffer = value.message;
  let dataView = new DataView(buffer);
  let str = "";
  for (let i = 0; i < dataView.byteLength; ++i) {
    str += String.fromCharCode(dataView.getUint8(i));
  }
  console.log("on connect received:" + str);
});
tcp.on('connect', () => {
  console.log("on connect");
});
tcp.on('close', () => {
  console.log("on close");
});

// Bind the local IP address and port number.
let ipAddress : socket.NetAddress = {} as socket.NetAddress;
ipAddress.address = "192.168.xxx.xxx";
ipAddress.port = 1234;
tcp.bind(ipAddress, (err: BusinessError) => {
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');

  // Set up a connection to the specified IP address and port number.
  ipAddress.address = "192.168.xxx.xxx";
  ipAddress.port = 5678;

  let tcpConnect : socket.TCPConnectOptions = {} as socket.TCPConnectOptions;
  tcpConnect.address = ipAddress;
  tcpConnect.timeout = 6000;

  tcp.connect(tcpConnect, (err: BusinessError) => {
    if (err) {
      console.log('connect fail');
      return;
    }
    console.log('connect success');
    // Send data over the connection.
    let tcpSendOptions : socket.TCPSendOptions = {} as socket.TCPSendOptions;
    tcpSendOptions.data = 'Hello, server!';
    tcp.send(tcpSendOptions, (err: BusinessError) => {
      if (err) {
        console.log('send fail');
        return;
      }
      console.log('send success');
    })
  });
});

// Enable the socket connection to be automatically closed after use. Then, unsubscribe from events of the connection.
setTimeout(() => {
  tcp.close((err: BusinessError) => {
    console.log('close socket.');
  });
  tcp.off('message');
  tcp.off('connect');
  tcp.off('close');
}, 30 * 1000);

Transmitting Data over TCP Socket Server Connections

How to Develop

The TCP socket server connection process is described as follows:

1. Import the required socket module.
2. Create a TCP socket server connection. A TCPSocketServer object is returned.
3. Bind the local IP address and port, and listen for and accept TCP socket connections established over the socket.
4. Subscribe to connect events of the TCPSocketServer object to listen for client connection status changes.
5. Set up a connection between the client and the server. A TCPSocketConnection object is returned.
6. Subscribe to events of the TCPSocketConnection object, and send data to the client through the TCPSocketConnection object.
7. Close the connection between the client and the server.
8. Unsubscribe from events of the TCPSocketConnection and TCPSocketServer objects.

import socket from '@ohos.net.socket';
import { BusinessError } from '@ohos.base';
// Create a TCP socket server connection. A TCPSocketServer object is returned.
let tcpServer = socket.constructTCPSocketServerInstance();
// Bind the local IP address and port number for listening.

let ipAddress : socket.NetAddress = {} as socket.NetAddress;
ipAddress.address = "192.168.xxx.xxx";
ipAddress.port = 4651;
tcpServer.listen(ipAddress, (err: BusinessError) => {
  if (err) {
    console.log("listen fail");
    return;
  }
  console.log("listen success");
});

class SocketInfo {
  message: ArrayBuffer = new ArrayBuffer(1);
  remoteInfo: socket.SocketRemoteInfo = {} as socket.SocketRemoteInfo;
}
// Subscribe to connect events of the TCPSocketServer object.
tcpServer.on("connect", (client: socket.TCPSocketConnection) => {
  // Subscribe to events of the TCPSocketConnection object.
  client.on("close", () => {
    console.log("on close success");
  });
  client.on("message", (value: SocketInfo) => {
    let buffer = value.message;
    let dataView = new DataView(buffer);
    let str = "";
    for (let i = 0; i < dataView.byteLength; ++i) {
      str += String.fromCharCode(dataView.getUint8(i));
    }
    console.log("received message--:" + str);
    console.log("received address--:" + value.remoteInfo.address);
    console.log("received family--:" + value.remoteInfo.family);
    console.log("received port--:" + value.remoteInfo.port);
    console.log("received size--:" + value.remoteInfo.size);
  });

  // Send data to the client.
  let tcpSendOptions : socket.TCPSendOptions = {} as socket.TCPSendOptions;
  tcpSendOptions.data = 'Hello, client!';
  client.send(tcpSendOptions, (err: BusinessError) => {
    if (err) {
      console.log("send fail");
      return;
    }
    console.log("send success");
  });

  // Close the connection between the client and the server.
  client.close((err: BusinessError) => {
    if (err) {
      console.log("close fail");
      return;
    }
    console.log("close success");
  });

  // Unsubscribe from events of the TCPSocketConnection object.
  setTimeout(() => {
    client.off("message");
    client.off("close");
  }, 10 * 1000);
});

// Unsubscribe from events of the TCPSocketServer object.
setTimeout(() => {
  tcpServer.off("connect");
}, 30 * 1000);

Transmitting Data over Multicast Socket Connections

How to Develop

1. Import the required socket module.

2. Create a MulticastSocket object.

3. Specify a MulticastSocket object by the IP address and port number, and add it to the multicast group.

4. Subscribe to message events.

5. Send data in broadcast mode. All MulticastSocket objects in the same multicast group for which message event listening has been enabled will receive the data.

6. Unsubscribe from message events.

7. Drop the MulticastSocket object from the multicast group.

import socket from '@ohos.net.socket'
// Create a MulticastSocket object.
let multicast = socket.constructMulticastSocketInstance();

let addr : socket.NetAddress = {
  address: '239.255.0.1',
  port: 32123,
  family: 1
}

// Add the MulticastSocket object to a multicast group.
multicast.addMembership(addr, (err: Object) => {
  if (err) {
    console.info('add err: ' + JSON.stringify(err));
    return;
  }
  console.info('add ok');
})

// Subscribe to message events and convert the received data of the ArrayBuffer type to strings.
class SocketInfo {
  message: ArrayBuffer = new ArrayBuffer(1);
  remoteInfo: socket.SocketRemoteInfo = {} as socket.SocketRemoteInfo;
}
multicast.on('message', (data: SocketInfo) => {
  console.info ('Received data:' + JSON.stringify (data))
  const uintArray = new Uint8Array(data.message)
  let str = ''
  for (let i = 0; i < uintArray.length; ++i) {
    str += String.fromCharCode(uintArray[i])
  }
  console.info(str)
})

// Send data over the connection.
multicast.send({ data:'Hello12345', address: addr }, (err: Object) => {
  if (err) {
    console.info ('Sending failed:' + JSON.stringify (err));
    return;
  }
  console.info('Sending success');
})

// Unsubscribe from message events.
multicast.off('message')

// Drop the MulticastSocket object from the multicast group.
multicast.dropMembership(addr, (err: Object) => {
  if (err) {
    console.info('drop err ' + JSON.stringify(err));
    return;
  }
  console.info('drop ok');
})

Transmitting Data over Local Socket Connections

How to Develop

1. Import the required socket module.

2. Call constructLocalSocketInstance to create a LocalSocket object.

3. Subscribe to message events of the LocalSocket object and other events (optional).

4. Connect to server based on the specified address of the local socket file.

5. Send data over the connection.

6. If the socket connection is no longer needed, unsubscribe from message events and close the connection.

import socket from '@ohos.net.socket';

// Create a local socket connection. A LocalSocket object is returned.
let client = socket.constructLocalSocketInstance();
client.on('message', (value: socket.LocalSocketMessageInfo) => {
  const uintArray = new Uint8Array(value.message)
  let messageView = '';
  for (let i = 0; i < uintArray.length; i++) {
    messageView += String.fromCharCode(uintArray[i]);
  }
  console.log('total receive: ' + JSON.stringify(value));
  console.log('message information: ' + messageView);
});
client.on('connect', () => {
  console.log("on connect");
});
client.on('close', () => {
  console.log("on close");
});

// Specify the address of local socket file to connect to the server.
let sandboxPath: string = getContext(this).filesDir + '/testSocket'
let connectOpt: socket.LocalConnectOptions = {
  address: {
    address: sandboxPath
  },
  timeout: 6000
}
let sendOpt: socket.LocalSendOptions = {
  data: 'Hello world!'
}
client.connect(connectOpt).then(() => {
  console.log('connect success')
  client.send(sendOpt).then(() => {
  console.log('send success')
  }).catch((err: Object) => {
    console.log('send failed: ' + JSON.stringify(err))
  })
}).catch((err: Object) => {
  console.log('connect fail: ' + JSON.stringify(err));
});

// If the socket connection is no longer needed, unsubscribe from message events and close the connection.
client.off('message');
client.off('connect');
client.off('close');
client.close().then(() => {
  console.log('close client success')
}).catch((err: Object) => {
  console.log('close client err: ' + JSON.stringify(err))
})

Transmitting Data over Local Socket Server Connections

How to Develop

The local socket connection process on the server is described as follows:

1. Import the required socket module.

2. Call constructLocalSocketServerInstance to create a LocalSocketServer object.

3. Bind the address of the local socket file.

4. Subscribe to connect events of the local socket client and other events (optional).

5. When the local socket client is connected, obtain the LocalSocketConnection object through the callback of the connect event.

6. Subscribe to message events of the LocalSocketConnection object and other events (optional).

7. Send messages to the local socket client through the LocalSocketConnection object.

8. When the communication ends, close the local socket connection.

9. Unsubscribe from events of the LocalSocketConnection and LocalSocketServer objects.

import socket from '@ohos.net.socket';
// Create a local socket server connection. A LocalSocketServer object is returned.
let server = socket.constructLocalSocketServerInstance();
// Create and bind the local socket file testSocket for listening.
let sandboxPath: string = getContext(this).filesDir + '/testSocket'
let listenAddr: socket.LocalAddress = {
  address: sandboxPath
}
server.listen(listenAddr).then(() => {
  console.log("listen success");
}).catch((err: Object) => {
  console.log("listen fail: " + JSON.stringify(err));
});

// Subscribe to connect events of the LocalSocketServer object.
server.on("connect", (connection: socket.LocalSocketConnection) => {
  // Subscribe to events of the LocalSocketConnection object.
  connection.on("error", (err) => {
    console.log("on error success");
  });
  connection.on('message', (value: socket.LocalSocketMessageInfo) => {
    const uintArray = new Uint8Array(value.message);
    let messageView = '';
    for (let i = 0; i < uintArray.length; i++) {
      messageView += String.fromCharCode(uintArray[i]);
    }
    console.log('total: ' + JSON.stringify(value));
    console.log('message information: ' + messageView);
  });

  connection.on('error', (err) => {
    console.log("err:" + JSON.stringify(err));
  })

  // Send data to the client.
  let sendOpt : socket.LocalSendOptions = {
    data: 'Hello world!'
  };
  connection.send(sendOpt).then(() => {
    console.log('send success');
  }).catch((err: Object) => {
    console.log('send failed: ' + JSON.stringify(err));
  })

  // Close the connection between the client and the server.
  connection.close().then(() => {
    console.log('close success');
  }).catch((err: Object) => {
    console.log('close failed: ' + JSON.stringify(err));
  });

  // Unsubscribe from events of the LocalSocketConnection object.
  connection.off('message');
  connection.off('error');
});

// Unsubscribe from events of the LocalSocketServer object.
server.off('connect');
server.off('error');

Implementing Encrypted Data Transmission over TLS Socket Connections

How to Develop

The TLS socket connection process on the client is described as follows:

1. Import the required socket module.

2. Bind the IP address and port number of the server.

3. For two-way authentication, upload the client CA certificate and digital certificate. For one-way authentication, upload the client CA certificate.

4. Create a TLS socket connection. A TLSSocketConnection object is returned.

5. (Optional) Subscribe to events of the TLSSocketConnection object.

6. Send data over the connection.

7. Enable the TLS socket connection to be automatically closed after use.

import socket from '@ohos.net.socket';
import { BusinessError } from '@ohos.base';

class SocketInfo {
  message: ArrayBuffer = new ArrayBuffer(1);
  remoteInfo: socket.SocketRemoteInfo = {} as socket.SocketRemoteInfo;
}
// Create a TLS socket connection (for two-way authentication). A TLSSocketConnection object is returned.
let tlsTwoWay = socket.constructTLSSocketInstance();
// Subscribe to events of the TLSSocketConnection object.
tlsTwoWay.on('message', (value: SocketInfo) => {
  console.log("on message");
  let buffer = value.message;
  let dataView = new DataView(buffer);
  let str = "";
  for (let i = 0; i < dataView.byteLength; ++i) {
    str += String.fromCharCode(dataView.getUint8(i));
  }
  console.log("on connect received:" + str);
});
tlsTwoWay.on('connect', () => {
  console.log("on connect");
});
tlsTwoWay.on('close', () => {
  console.log("on close");
});

// Bind the local IP address and port number.
let ipAddress : socket.NetAddress = {} as socket.NetAddress;
ipAddress.address = "192.168.xxx.xxx";
ipAddress.port = 4512;
tlsTwoWay.bind(ipAddress, (err: BusinessError) => {
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});

ipAddress.address = "192.168.xxx.xxx";
ipAddress.port = 1234;

let tlsSecureOption : socket.TLSSecureOptions = {} as socket.TLSSecureOptions;
tlsSecureOption.key = "xxxx";
tlsSecureOption.cert = "xxxx";
tlsSecureOption.ca = ["xxxx"];
tlsSecureOption.password = "xxxx";
tlsSecureOption.protocols = [socket.Protocol.TLSv12];
tlsSecureOption.useRemoteCipherPrefer = true;
tlsSecureOption.signatureAlgorithms = "rsa_pss_rsae_sha256:ECDSA+SHA256";
tlsSecureOption.cipherSuite = "AES256-SHA256";

let tlsTwoWayConnectOption : socket.TLSConnectOptions = {} as socket.TLSConnectOptions;
tlsSecureOption.key = "xxxx";
tlsTwoWayConnectOption.address = ipAddress;
tlsTwoWayConnectOption.secureOptions = tlsSecureOption;
tlsTwoWayConnectOption.ALPNProtocols = ["spdy/1", "http/1.1"];

// Set up a connection.
tlsTwoWay.connect(tlsTwoWayConnectOption, () => {
  console.error("connect function");
});

// Enable the socket connection to be automatically closed after use. Then, unsubscribe from events of the connection.
tlsTwoWay.close((err: BusinessError) => {
  if (err) {
    console.log("close callback error = " + err);
  } else {
    console.log("close success");
  }
  tlsTwoWay.off('message');
  tlsTwoWay.off('connect');
  tlsTwoWay.off('close');
});

// Create a TLS socket connection (for one-way authentication). A TLSSocketConnection object is returned.
let tlsOneWay = socket.constructTLSSocketInstance(); // One way authentication

// Subscribe to events of the TLSSocketConnection object.
tlsTwoWay.on('message', (value: SocketInfo) => {
  console.log("on message");
  let buffer = value.message;
  let dataView = new DataView(buffer);
  let str = "";
  for (let i = 0; i < dataView.byteLength; ++i) {
    str += String.fromCharCode(dataView.getUint8(i));
  }
  console.log("on connect received:" + str);
});
tlsTwoWay.on('connect', () => {
  console.log("on connect");
});
tlsTwoWay.on('close', () => {
  console.log("on close");
});

// Bind the local IP address and port number.
ipAddress.address = "192.168.xxx.xxx";
ipAddress.port = 5445;
tlsOneWay.bind(ipAddress, (err:BusinessError) => {
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});

ipAddress.address = "192.168.xxx.xxx";
ipAddress.port = 8789;
let tlsOneWaySecureOption : socket.TLSSecureOptions = {} as socket.TLSSecureOptions;
tlsOneWaySecureOption.ca = ["xxxx", "xxxx"];
tlsOneWaySecureOption.cipherSuite = "AES256-SHA256";

let tlsOneWayConnectOptions: socket.TLSConnectOptions = {} as socket.TLSConnectOptions;
tlsOneWayConnectOptions.address = ipAddress;
tlsOneWayConnectOptions.secureOptions = tlsOneWaySecureOption;

// Set up a connection.
tlsOneWay.connect(tlsOneWayConnectOptions, () => {
  console.error("connect function");
});

// Enable the socket connection to be automatically closed after use. Then, unsubscribe from events of the connection.
tlsTwoWay.close((err: BusinessError) => {
  if (err) {
    console.log("close callback error = " + err);
  } else {
    console.log("close success");
  }
  tlsTwoWay.off('message');
  tlsTwoWay.off('connect');
  tlsTwoWay.off('close');
});

Implementing Encrypted Data Transmission over TLS Socket Server Connections

How to Develop

The TLS socket connection process on the server is described as follows:

1. Import the required socket module.

2. Start the service and bind the IP address and port number to set up a TLS socket connection. Then, create and initialize a TLS session, and load and verify the certificate key.

3. Subscribe to connect events of the TLSSocketServer object.

4. Obtain a TLSSocketConnection object through the callback when the client initiates a TLS socket connection.

5. Subscribe to events of the TLSSocketConnection object.

6. Send data over the connection.

7. Close the TLS socket connection if it is no longer needed.

8. Unsubscribe from events of the TLSSocketConnection and TLSSocketServer objects.

import socket from "@ohos.net.socket";
import { BusinessError } from '@ohos.base';
let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: {
    address: '192.168.xx.xxx',
    port: 8080
  },
  secureOptions: {
    key: "xxxx",
    cert: "xxxx",
    ca: ["xxxx"],
    password: "xxxx",
    protocols: socket.Protocol.TLSv12,
    useRemoteCipherPrefer: true,
    signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
    cipherSuite: "AES256-SHA256"
  },
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.log("listen callback success");
}).catch((err: BusinessError) => {
  console.log("failed" + err);
});

class SocketInfo {
  message: ArrayBuffer = new ArrayBuffer(1);
  remoteInfo: socket.SocketRemoteInfo = {} as socket.SocketRemoteInfo;
}
let callback = (value: SocketInfo) => {
  let messageView = '';
  for (let i: number = 0; i < value.message.byteLength; i++) {
    let uint8Array = new Uint8Array(value.message)
    let messages = uint8Array[i]
    let message = String.fromCharCode(messages);
    messageView += message;
  }
  console.log('on message message: ' + JSON.stringify(messageView));
  console.log('remoteInfo: ' + JSON.stringify(value.remoteInfo));
}
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.on('message', callback);

  // Send data over the connection.
  client.send('Hello, client!').then(() => {
    console.log('send success');
  }).catch((err: BusinessError) => {
    console.log('send fail');
  });

  // Close the connection.
  client.close().then(() => {
    console.log('close success');
  }).catch((err: BusinessError) => {
    console.log('close fail');
  });

  // You can pass the callback of the on function if you want to unsubscribe from a certain type of events. If you do not pass the callback, you will unsubscribe from all events.
  client.off('message', callback);
  client.off('message');
});

// Unsubscribe from events of the TLSSocketServer object.
tlsServer.off('connect');