@ohos.net.socket (Socket Connection)

The socket module implements data transfer over TCP, UDP, Web, and TLS socket connections.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. You are advised to call the APIs of this module in the worker thread or taskpool to perform network-related operations. Otherwise, the UI thread may be suspended.

Modules to Import

import { socket } from '@kit.NetworkKit';

socket.constructUDPSocketInstance

constructUDPSocketInstance(): UDPSocket

Creates a UDPSocket object.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
UDPSocket	UDPSocket object.

Example

import { socket } from '@kit.NetworkKit';
let udp: socket.UDPSocket = socket.constructUDPSocketInstance();

UDPSocket

Defines a UDP socket connection. Before calling UDPSocket APIs, you need to call socket.constructUDPSocketInstance to create a UDPSocket object.

bind

bind(address: NetAddress, callback: AsyncCallback<void>): void

Binds the IP address and port number. The port number can be customized or randomly allocated by the system. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	NetAddress	Yes	Local address. For details, see NetAddress.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx', // Local IP address
  port: 1234
}
udp.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});

bind

bind(address: NetAddress): Promise<void>

Binds the IP address and port number. The port number can be customized or randomly allocated by the system. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	NetAddress	Yes	Local address. For details, see NetAddress.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx', // Local IP address
  port: 8080
}
udp.bind(bindAddr).then(() => {
  console.info('bind success');
}).catch((err: BusinessError) => {
  console.error('bind fail');
});

send

send(options: UDPSendOptions, callback: AsyncCallback<void>): void

Sends data over a UDP socket connection. This API uses an asynchronous callback to return the result.

Before sending data, call UDPSocket.bind() to bind the IP address and port. Call the API in the worker thread or taskpool thread as this operation is time-consuming.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	UDPSendOptions	Yes	Parameters for sending data over a UDP socket connection. For details, see UDPSendOptions.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2301206	Socks5 failed to connect to the proxy server.
2301207	Socks5 username or password is invalid.
2301208	Socks5 failed to connect to the remote server.
2301209	Socks5 failed to negotiate the authentication method.
2301210	Socks5 failed to send the message.
2301211	Socks5 failed to receive the message.
2301212	Socks5 serialization error.
2301213	Socks5 deserialization error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx', // Local IP address
  port: 1234
}
udp.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',  // Peer IP address
  port: 8080
}
let sendOptions: socket.UDPSendOptions = {
  data: 'Hello, server!',
  address: netAddress
}
udp.send(sendOptions, (err: BusinessError) => {
  if (err) {
    console.error('send fail');
    return;
  }
  console.info('send success');
});

Example (with socket proxy):

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx', // Local IP address
  port: 1234
}
udp.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',  // Peer IP address
  port: 8080
}
let socks5Server: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let proxyOptions: socket.ProxyOptions = {
  type : 1,
  address: socks5Server,
  username: "xxx",
  password: "xxx"
}
let sendOptions: socket.UDPSendOptions = {
  data: 'Hello, server!',
  address: netAddress,
  proxy: proxyOptions,
}
udp.send(sendOptions, (err: BusinessError) => {
  if (err) {
    console.error('send fail');
    return;
  }
  console.info('send success');
});

send

send(options: UDPSendOptions): Promise<void>

Sends data over a UDP socket connection. This API uses a promise to return the result.

Before sending data, call UDPSocket.bind() to bind the IP address and port. Call the API in the worker thread or taskpool thread as this operation is time-consuming.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	UDPSendOptions	Yes	Parameters for sending data over a UDP socket connection. For details, see UDPSendOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2301206	Socks5 failed to connect to the proxy server.
2301207	Socks5 username or password is invalid.
2301208	Socks5 failed to connect to the remote server.
2301209	Socks5 failed to negotiate the authentication method.
2301210	Socks5 failed to send the message.
2301211	Socks5 failed to receive the message.
2301212	Socks5 serialization error.
2301213	Socks5 deserialization error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx', // Local IP address
  port: 8080
}
udp.bind(bindAddr).then(() => {
  console.info('bind success');
}).catch((err: BusinessError) => {
  console.error('bind fail');
  return;
});
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx', // Peer IP address
  port: 8080
}
let sendOptions: socket.UDPSendOptions = {
  data: 'Hello, server!',
  address: netAddress
}
udp.send(sendOptions).then(() => {
  console.info('send success');
}).catch((err: BusinessError) => {
  console.error('send fail');
});

Example (with socket proxy):

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx', // Local IP address
  port: 8080
}
udp.bind(bindAddr).then(() => {
  console.info('bind success');
}).catch((err: BusinessError) => {
  console.error('bind fail');
  return;
});
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx', // Peer IP address
  port: 8080
}
let socks5Server: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let proxyOptions: socket.ProxyOptions = {
  type : 1,
  address: socks5Server,
  username: "xxx",
  password: "xxx"
}
let sendOptions: socket.UDPSendOptions = {
  data: 'Hello, server!',
  address: netAddress,
  proxy: proxyOptions,
}
udp.send(sendOptions).then(() => {
  console.info('send success');
}).catch((err: BusinessError) => {
  console.error('send fail');
});

close

close(callback: AsyncCallback<void>): void

Closes a UDP socket connection. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
udp.close((err: BusinessError) => {
  if (err) {
    console.error('close fail');
    return;
  }
  console.info('close success');
})

close

close(): Promise<void>

Closes a UDP socket connection. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
udp.close().then(() => {
  console.info('close success');
}).catch((err: BusinessError) => {
  console.error('close fail');
});

getState

getState(callback: AsyncCallback<SocketStateBase>): void

Obtains the status of the UDP socket connection. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after bind is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<SocketStateBase>	Yes	Callback used to return the result. If the operation is successful, the status of the UDP socket connection is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
udp.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.error('bind success');
  udp.getState((err: BusinessError, data: socket.SocketStateBase) => {
    if (err) {
      console.error('getState fail');
      return;
    }
    console.info('getState success:' + JSON.stringify(data));
  })
})

getState

getState(): Promise<SocketStateBase>

Obtains the status of the UDP socket connection. This API uses a promise to return the result.

NOTE This API can be called only after bind is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<SocketStateBase>	Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
udp.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
  udp.getState().then((data: socket.SocketStateBase) => {
    console.info('getState success:' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error('getState fail' + JSON.stringify(err));
  });
});

getSocketFd²³⁺

getSocketFd(): Promise<number>

Obtains the UDPSocket file descriptor. This API uses a promise to return the result.

NOTE

• This API can be called only after bind is successfully called.
• This API returns -1 in abnormal cases such as bind exceptions or socket closed (for example, after close is called).
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the socket file descriptor.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let bindAddr: socket.NetAddress = {
    address: '192.168.xx.xxx',
    port: 8080
}
udp.bind(bindAddr)
  .then(() => {
    udp.getSocketFd()
      .then((fd: number) => {
        console.info(`Socket FD: ${fd}`);
      }).catch((err: BusinessError) => {
      console.error(`getSocketFd fail: ${err.message}, errorCode: ${err.code}`);
    });
  }).catch((err: BusinessError) => {
  console.error('bind fail');
});

setExtraOptions

setExtraOptions(options: UDPExtraOptions, callback: AsyncCallback<void>): void

Sets other properties of the UDPSocket object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after bind is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	UDPExtraOptions	Yes	Other properties of the UDPSocket object. For details, see UDPExtraOptions.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();

let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
udp.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
  let udpextraoptions: socket.UDPExtraOptions = {
    receiveBufferSize: 8192,
    sendBufferSize: 8192,
    reuseAddress: false,
    socketTimeout: 6000,
    broadcast: true
  }
  udp.setExtraOptions(udpextraoptions, (err: BusinessError) => {
    if (err) {
      console.error('setExtraOptions fail');
      return;
    }
    console.info('setExtraOptions success');
  })
})

setExtraOptions

setExtraOptions(options: UDPExtraOptions): Promise<void>

Sets other properties of the UDPSocket object. This API uses a promise to return the result.

NOTE This API can be called only after bind is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	UDPExtraOptions	Yes	Other properties of the UDPSocket object. For details, see UDPExtraOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();

let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
udp.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
  let udpextraoptions: socket.UDPExtraOptions = {
    receiveBufferSize: 8192,
    sendBufferSize: 8192,
    reuseAddress: false,
    socketTimeout: 6000,
    broadcast: true
  }
  udp.setExtraOptions(udpextraoptions).then(() => {
    console.info('setExtraOptions success');
  }).catch((err: BusinessError) => {
    console.error('setExtraOptions fail');
  });
})

getLocalAddress¹²⁺

getLocalAddress(): Promise<NetAddress>

Obtains the local socket address of a UDPSocket connection. This API uses a promise to return the result.

NOTE This API can be called only after bind is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();

let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
udp.bind(bindAddr).then(() => {
  console.info('bind success');
  udp.getLocalAddress().then((localAddress: socket.NetAddress) => {
        console.info("UDP_Socket get SUCCESS! Address: " + JSON.stringify(localAddress));
      }).catch((err: BusinessError) => {
        console.error("UDP_Socket get FAILED! Error: " + JSON.stringify(err));
      })
}).catch((err: BusinessError) => {
  console.error('bind fail');
});

on('message')

on(type: 'message', callback: Callback<SocketMessageInfo>): void

Subscribes to message events of the UDPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	Yes	Callback used to return the result.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();

udp.on('message', (value: socket.SocketMessageInfo) => {
  let messageView = '';
  let uint8Array = new Uint8Array(value.message); 
  for (let i: number = 0; i < value.message.byteLength; i++) {
    let messages = uint8Array[i];
    let message = String.fromCharCode(messages);
    messageView += message;
  }
  console.info('on message message: ' + JSON.stringify(messageView));
  console.info('remoteInfo: ' + JSON.stringify(value.remoteInfo));
});

off('message')

off(type: 'message', callback?: Callback<SocketMessageInfo>): void

Unsubscribes from message events of the UDPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let messageView = '';
let callback = (value: socket.SocketMessageInfo) => {
  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.info('on message message: ' + JSON.stringify(messageView));
  console.info('remoteInfo: ' + JSON.stringify(value.remoteInfo));
}
udp.on('message', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
udp.off('message', callback);
udp.off('message');

on('listening' | 'close')

on(type: 'listening' | 'close', callback: Callback<void>): void

Subscribes to listening events or close events of the UDPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - listening: data packet message event. - close: close event.
callback	Callback<void>	Yes	Callback used to return the result.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
udp.on('listening', () => {
  console.info("on listening success");
});
udp.on('close', () => {
  console.info("on close success");
});

off('listening' | 'close')

off(type: 'listening' | 'close', callback?: Callback<void>): void

Unsubscribes from listening events or close events of the UDPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - listening: data packet message event. - close: close event.
callback	Callback<void>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let callback1 = () => {
  console.info("on listening, success");
}
udp.on('listening', callback1);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
udp.off('listening', callback1);
udp.off('listening');
let callback2 = () => {
  console.info("on close, success");
}
udp.on('close', callback2);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
udp.off('close', callback2);
udp.off('close');

on('error')

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the UDPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	Yes	Callback used to return the result.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
udp.on('error', (err: BusinessError) => {
  console.error("on error, err:" + JSON.stringify(err))
});

off('error')

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the UDPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let udp: socket.UDPSocket = socket.constructUDPSocketInstance();
let callback = (err: BusinessError) => {
  console.error("on error, err:" + JSON.stringify(err));
}
udp.on('error', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
udp.off('error', callback);
udp.off('error');

NetAddress

Defines the destination address.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
address11+	string	No	No	IP address.
port	number	No	No	Port number. The value ranges from 0 to 65535. If this parameter is not specified, the system randomly allocates a port.
family	number	No	No	Network protocol type. - 1: IPv4 The default value is 1. - 2: IPv6 For an IPv6 address, this field must be explicitly set to 2. - 3: domain address18+ For a domain address, this field must be explicitly set to 3. Currently, only TCPSocket.connect and TLSSocket.connect are supported.

ProxyOptions¹⁸⁺

Defines the socket proxy information.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
type	ProxyTypes	No	No	Proxy type.
address	NetAddress	No	No	Proxy address.
username	string	No	Yes	User name. This field must be specified if the user password authentication mode is used.
password	string	No	Yes	Password. This field must be specified if the user password authentication mode is used.

ProxyTypes¹⁸⁺

Enumerates socket proxy types.

System capability: SystemCapability.Communication.NetStack

Name	Value	Description
NONE	0	No proxy.
SOCKS5	1	SOCKS5 proxy.

UDPSendOptions

Defines the parameters for sending data over a UDP socket connection.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
data	string | ArrayBuffer	No	No	Data to send.
address	NetAddress	No	No	Destination address.
proxy18+	ProxyOptions	No	Yes	Proxy option. By default, no proxy is used.

UDPExtraOptions

Defines other properties of the UDPSocket object. This object is inherited from ExtraOptionsBase.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
broadcast	boolean	No	Yes	Whether to send broadcast messages. The value true indicates that broadcast messages can be sent, and the value false indicates the opposite. The default value is false.

SocketMessageInfo¹¹⁺

Defines the socket connection information.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
message	ArrayBuffer	No	No	Received message event.
remoteInfo	SocketRemoteInfo	No	No	Socket connection information.

SocketStateBase

Defines the status of the socket connection.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
isBound	boolean	No	No	Whether the connection is in the bound state. The value true indicates that the connection is in the bound state, and the value false indicates the opposite.
isClose	boolean	No	No	Whether the connection is in the closed state. The value true indicates that the connection is in the closed state, and the value false indicates the opposite.
isConnected	boolean	No	No	Whether the connection is in the connected state. The value true indicates that the connection is in the connected state, and the value false indicates the opposite.

SocketRemoteInfo

Defines information about the socket connection.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
address	string	No	No	Peer IP address.
family	'IPv4' | 'IPv6'	No	No	Network protocol type. - IPv4 - IPv6 The default value is IPv4.
port	number	No	No	Port number. The value ranges from 0 to 65535.
size	number	No	No	Length of the server response message, in bytes.

Description of UDP Error Codes

The UDP error code mapping is in the format of 2301000 + Linux kernel error code.

For details about error codes, see Socket Error Codes.

socket.constructMulticastSocketInstance¹¹⁺

constructMulticastSocketInstance(): MulticastSocket

Creates a MulticastSocket object.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
MulticastSocket	MulticastSocket object.

Example

import { socket } from '@kit.NetworkKit';
let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();

MulticastSocket¹¹⁺

Defines a MulticastSocket connection. Before calling MulticastSocket APIs, you need to call socket.constructMulticastSocketInstance to create a MulticastSocket object.

setReuseAddress

setReuseAddress(reuse: boolean): void

Sets whether the multicast socket supports address reuse. This API is called in synchronous mode.

NOTE This API is used to control whether to enable address reuse when a multicast socket is bound to a port. To bind an occupied port, ensure that the address reuse capability is enabled for the party that occupies the port. In addition, the service needs to call this API before calling bind to enable the address reuse capability.

Since: 26.0.0

System capability: SystemCapability.Communication.NetStack

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
reuse	boolean	Yes	Whether to enable address reuse. true to enable, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
let bindAddr: socket.NetAddress = {
  // 0.0.0.0 indicates that port 8080 on all IPv4 network APIs of the local host is bound. This is commonly used to receive data from this port in multicast scenarios.
  address: '0.0.0.0',
  port: 8080
}

try {
  multicast.setReuseAddress(true);
  multicast.bind(bindAddr).then(() => {
    console.info('setReuseAddress success');
  }).catch((err: BusinessError) => {
    console.error(`bind failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
  let error = err as BusinessError;
  console.error(`setReuseAddress failed, code is ${error.code}, message is ${error.message}`);
}

addMembership¹¹⁺

addMembership(multicastAddress: NetAddress, callback: AsyncCallback<void>): void

Adds a member to a multicast group. This API uses an asynchronous callback to return the result.

NOTE The IP addresses used for multicast belong to a specific range, for example, 224.0.0.0 to 239.255.255.255. A member in a multicast group can serve as a sender or a receiver. Data is transmitted in broadcast mode, regardless of the client or server.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
multicastAddress	NetAddress	Yes	Destination address. For details, see NetAddress.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2301022	Invalid argument.
2301088	Not a socket.
2301098	Address in use.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
let addr: socket.NetAddress = {
  address: '239.255.0.1',
  port: 8080
}
multicast.addMembership(addr, (err: Object) => {
  if (err) {
    console.error('add membership fail, err: ' + JSON.stringify(err));
    return;
  }
  console.info('add membership success');
})

addMembership¹¹⁺

addMembership(multicastAddress: NetAddress): Promise<void>

Adds a member to a multicast group. This API uses a promise to return the result.

NOTE The IP addresses used for multicast belong to a specific range, for example, 224.0.0.0 to 239.255.255.255. A member in a multicast group can serve as a sender or a receiver. Data is transmitted in broadcast mode, regardless of the client or server.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
multicastAddress	NetAddress	Yes	Destination address. For details, see NetAddress.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2301088	Not a socket.
2301098	Address in use.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
let addr: socket.NetAddress = {
  address: '239.255.0.1',
  port: 8080
}
multicast.addMembership(addr).then(() => {
  console.info('addMembership success');
}).catch((err: Object) => {
  console.error('addMembership fail');
});

dropMembership¹¹⁺

dropMembership(multicastAddress: NetAddress, callback: AsyncCallback<void>): void

Drops a member from a multicast group. This API uses an asynchronous callback to return the result.

NOTE The IP addresses used for multicast belong to a specific range, for example, 224.0.0.0 to 239.255.255.255. You can drop only a member that has been added to a multicast group by using addMembership.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
multicastAddress	NetAddress	Yes	Destination address. For details, see NetAddress.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2301088	Not a socket.
2301098	Address in use.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
let addr: socket.NetAddress = {
  address: '239.255.0.1',
  port: 8080
}
multicast.dropMembership(addr, (err: Object) => {
  if (err) {
    console.error('drop membership fail, err: ' + JSON.stringify(err));
    return;
  }
  console.info('drop membership success');
})

dropMembership¹¹⁺

dropMembership(multicastAddress: NetAddress): Promise<void>

Drops a member from a multicast group. This API uses a promise to return the result.

NOTE The IP addresses used for multicast belong to a specific range, for example, 224.0.0.0 to 239.255.255.255. You can drop only a member that has been added to a multicast group by using addMembership.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
multicastAddress	NetAddress	Yes	Destination address. For details, see NetAddress.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2301088	Not a socket.
2301098	Address in use.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
let addr: socket.NetAddress = {
  address: '239.255.0.1',
  port: 8080
}
multicast.dropMembership(addr).then(() => {
  console.info('drop membership success');
}).catch((err: Object) => {
  console.error('drop membership fail');
});

setMulticastTTL¹¹⁺

setMulticastTTL(ttl: number, callback: AsyncCallback<void>): void

Sets the time to live (TTL) for multicast packets. This API uses an asynchronous callback to return the result.

NOTE TTL is used to limit the maximum number of router hops for packet transmission on a network. The value ranges from 0 to 255. The default value is 1. If the TTL value is 1, multicast packets can be transmitted only to the host directly connected to the sender. If the TTL is set to a large value, multicast packets can be transmitted over a longer distance. This API is effective only after addMembership is called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
ttl	number	Yes	TTL value. The value is of the number type.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301022	Invalid argument.
2301088	Not a socket.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
let ttl = 8
multicast.setMulticastTTL(ttl, (err: Object) => {
  if (err) {
    console.error('set ttl fail, err: ' + JSON.stringify(err));
    return;
  }
  console.info('set ttl success');
})

setMulticastTTL¹¹⁺

setMulticastTTL(ttl: number): Promise<void>

Sets the TTL for multicast packets. This API uses a promise to return the result.

NOTE TTL is used to limit the maximum number of router hops for packet transmission on a network. The value ranges from 0 to 255. The default value is 1. If the TTL value is 1, multicast packets can be transmitted only to the host directly connected to the sender. If the TTL is set to a large value, multicast packets can be transmitted over a longer distance. This API is effective only after addMembership is called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
ttl	number	Yes	TTL value. The value is of the number type.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301022	Invalid argument.
2301088	Not a socket.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
multicast.setMulticastTTL(8).then(() => {
  console.info('set ttl success');
}).catch((err: Object) => {
  console.error('set ttl failed');
});

getMulticastTTL¹¹⁺

getMulticastTTL(callback: AsyncCallback<number>): void

Obtains the TTL for multicast packets. This API uses an asynchronous callback to return the result.

NOTE TTL is used to limit the maximum number of router hops for packet transmission on a network. The value ranges from 0 to 255. The default value is 1. If the TTL value is 1, multicast packets can be transmitted only to the host directly connected to the sender. If the TTL is set to a large value, multicast packets can be transmitted over a longer distance. This API is effective only after addMembership is called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<number>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301088	Not a socket.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
multicast.getMulticastTTL((err: Object, value: Number) => {
  if (err) {
    console.error('set ttl fail, err: ' + JSON.stringify(err));
    return;
  }
  console.info('set ttl success, value: ' + JSON.stringify(value));
})

getMulticastTTL¹¹⁺

getMulticastTTL(): Promise<number>

Obtains the TTL for multicast packets. This API uses a promise to return the result.

NOTE TTL is used to limit the maximum number of router hops for packet transmission on a network. The value ranges from 0 to 255. The default value is 1. If the TTL value is 1, multicast packets can be transmitted only to the host directly connected to the sender. If the TTL is set to a large value, multicast packets can be transmitted over a longer distance. This API is effective only after addMembership is called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301088	Not a socket.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
multicast.getMulticastTTL().then((value: Number) => {
  console.info('ttl: ', JSON.stringify(value));
}).catch((err: Object) => {
  console.error('set ttl failed');
});

setLoopbackMode¹¹⁺

setLoopbackMode(flag: boolean, callback: AsyncCallback<void>): void

Sets the loopback mode flag for multicast communication. This API uses an asynchronous callback to return the result.

NOTE Use this API to enable or disable the loopback mode. By default, the loopback mode is enabled. The value true indicates that the host is allowed to receive the multicast packets sent by itself, and the value false indicates the opposite. This API is effective only after addMembership is called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
flag	boolean	Yes	Whether to enable the loopback mode. The value true means to enable the loopback mode, and the value false means the opposite.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301088	Not a socket.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
multicast.setLoopbackMode(false, (err: Object) => {
  if (err) {
    console.error('set loopback mode fail, err: ' + JSON.stringify(err));
    return;
  }
  console.info('set loopback mode success');
})

setLoopbackMode¹¹⁺

setLoopbackMode(flag: boolean): Promise<void>

Sets the loopback mode flag for multicast communication. This API uses a promise to return the result.

NOTE Use this API to enable or disable the loopback mode. By default, the loopback mode is enabled. The value true indicates that the host is allowed to receive the multicast packets sent by itself, and the value false indicates the opposite. This API is effective only after addMembership is called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
flag	boolean	Yes	Whether to enable the loopback mode. The value true means to enable the loopback mode, and the value false means the opposite.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301088	Not a socket.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
multicast.setLoopbackMode(false).then(() => {
  console.info('set loopback mode success');
}).catch((err: Object) => {
  console.error('set loopback mode failed');
});

getLoopbackMode¹¹⁺

getLoopbackMode(callback: AsyncCallback<boolean>): void

Obtains the loopback mode flag for multicast communication. This API uses an asynchronous callback to return the result.

NOTE Use this API to check whether the loopback mode is enabled. The value true indicates that the loopback mode is enabled, and the value false indicates the opposite. When the loopback mode is disabled, the host does not receive the multicast packets sent by itself. This API is effective only after addMembership is called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. The value true indicates that the loopback mode is enabled, and the value false indicates the opposite.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301088	Not a socket.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
multicast.getLoopbackMode((err: Object, value: Boolean) => {
  if (err) {
    console.error('get loopback mode fail, err: ' + JSON.stringify(err));
    return;
  }
  console.info('get loopback mode success, value: ' + JSON.stringify(value));
})

getLoopbackMode¹¹⁺

getLoopbackMode(): Promise<boolean>

Obtains the loopback mode flag for multicast communication. This API uses a promise to return the result.

NOTE Use this API to check whether the loopback mode is enabled. The value true indicates that the loopback mode is enabled, and the value false indicates the opposite. When the loopback mode is disabled, the host does not receive the multicast packets sent by itself. This API is effective only after addMembership is called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true indicates that the loopback mode is enabled, and the value false indicates the opposite.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301088	Not a socket.

Example

import { socket } from '@kit.NetworkKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
multicast.getLoopbackMode().then((value: Boolean) => {
  console.info('loopback mode: ', JSON.stringify(value));
}).catch((err: Object) => {
  console.error('get loopback mode failed');
});

getSocketFd²³⁺

getSocketFd(): Promise<number>

Obtains the file descriptor of the MulticastSocket. This API uses a promise to return the result.

NOTE

• This API can be called only after bind is successfully called.
• This API returns -1 in abnormal cases such as bind exceptions or socket closed (for example, after close is called).
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Model restriction: This API can be used only in the stage model.

Return value

Type	Description
Promise<number>	Promise used to return the socket file descriptor.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let multicast: socket.MulticastSocket = socket.constructMulticastSocketInstance();
let bindAddr: socket.NetAddress = {
    address: '192.168.xx.xxx',
    port: 8080
}
multicast.bind(bindAddr)
  .then(() => {
    console.info('bind success');
    multicast.getSocketFd().then((fd: number) => {
      console.info(`Socket FD: ${fd}`);
    }).catch((err: BusinessError) => {
      console.error(`getSocketFd fail: ${err.message}, errorCode: ${err.code}`);
    });
  }).catch((err: BusinessError) => {
  console.error('bind fail');
});

socket.constructTCPSocketInstance

constructTCPSocketInstance(): TCPSocket

Creates a TCPSocket object.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
TCPSocket	TCPSocket object.

Example

import { socket } from '@kit.NetworkKit';
let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();

TCPSocket

Defines a TCP socket connection. Before calling TCPSocket APIs, you need to call socket.constructTCPSocketInstance to create a TCPSocket object.

bind

bind(address: NetAddress, callback: AsyncCallback<void>): void

Binds an IP address and a port number. The port number can be customized or randomly allocated by the system. This API uses an asynchronous callback to return the result.

NOTE If the bind operation fails due to a port conflict, the system will randomly allocate a port number. The TCP client can call tcp.bind to explicitly bind the IP address and port number, and then call tcp.connect to connect to the server. Alternatively, the TCP client can directly call tcp.connect to automatically bind the IP address and port number to connect to the server. If the IP address is localhost or 127.0.0.1, only local loopback access is allowed; that is, the TCP client and the server are deployed on the same device.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	NetAddress	Yes	Local address. For details, see NetAddress.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tcp.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
})

bind

bind(address: NetAddress): Promise<void>

Binds an IP address and a port number. The port number can be customized or randomly allocated by the system. This API uses a promise to return the result.

NOTE If the bind operation fails due to a port conflict, the system will randomly allocate a port number. The TCP client can call tcp.bind to explicitly bind the IP address and port number, and then call tcp.connect to connect to the server. Alternatively, the TCP client can directly call tcp.connect to automatically bind the IP address and port number to connect to the server. If the IP address is localhost or 127.0.0.1, only local loopback access is allowed; that is, the TCP client and the server are deployed on the same device.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	NetAddress	Yes	Local address. For details, see NetAddress.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tcp.bind(bindAddr).then(() => {
  console.info('bind success');
}).catch((err: BusinessError) => {
  console.error('bind fail');
});

connect

connect(options: TCPConnectOptions, callback: AsyncCallback<void>): void

Sets up a connection to the specified IP address and port number. This API uses an asynchronous callback to return the result.

NOTE This API allows you to connect to the TCP server without first executing tcp.bind.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPConnectOptions	Yes	TCP socket connection parameters. For details, see TCPConnectOptions.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2301206	Socks5 failed to connect to the proxy server.
2301207	Socks5 username or password is invalid.
2301208	Socks5 failed to connect to the remote server.
2301209	Socks5 failed to negotiate the authentication method.
2301210	Socks5 failed to send the message.
2301211	Socks5 failed to receive the message.
2301212	Socks5 serialization error.
2301213	Socks5 deserialization error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions, (err: BusinessError) => {
  if (err) {
    console.error('connect fail');
    return;
  }
  console.info('connect success');
})

Example (with socket proxy):

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let socks5Server: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let proxyOptions: socket.ProxyOptions = {
  type : 1,
  address: socks5Server,
  username: "xxx",
  password: "xxx"
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000,
  proxy: proxyOptions,
}
tcp.connect(tcpconnectoptions, (err: BusinessError) => {
  if (err) {
    console.error('connect fail');
    return;
  }
  console.info('connect success');
})

connect

connect(options: TCPConnectOptions): Promise<void>

Sets up a connection to the specified IP address and port number. This API uses a promise to return the result.

NOTE This API allows you to connect to the TCP server without first executing tcp.bind.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPConnectOptions	Yes	TCP socket connection parameters. For details, see TCPConnectOptions.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2301206	Socks5 failed to connect to the proxy server.
2301207	Socks5 username or password is invalid.
2301208	Socks5 failed to connect to the remote server.
2301209	Socks5 failed to negotiate the authentication method.
2301210	Socks5 failed to send the message.
2301211	Socks5 failed to receive the message.
2301212	Socks5 serialization error.
2301213	Socks5 deserialization error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions).then(() => {
  console.info('connect success')
}).catch((err: BusinessError) => {
  console.error('connect fail');
});

Example (with socket proxy):

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let socks5Server: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let proxyOptions: socket.ProxyOptions = {
  type : 1,
  address: socks5Server,
  username: "xxx",
  password: "xxx"
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000,
  proxy: proxyOptions,
}
tcp.connect(tcpconnectoptions).then(() => {
  console.info('connect success')
}).catch((err: BusinessError) => {
  console.error('connect fail');
});

send

send(options: TCPSendOptions, callback: AsyncCallback<void>): void

Sends data over a TCP socket connection. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after connect is successfully called. Call the API in the worker thread or taskpool thread as this operation is time-consuming.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPSendOptions	Yes	Parameters for sending data over a TCP socket connection. For details, see TCPSendOptions.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions, () => {
  console.info('connect success');
  let tcpSendOptions: socket.TCPSendOptions = {
    data: 'Hello, server!'
  }
  tcp.send(tcpSendOptions, (err: BusinessError) => {
    if (err) {
      console.error('send fail');
      return;
    }
    console.info('send success');
  })
})

send

send(options: TCPSendOptions): Promise<void>

Sends data over a TCP socket connection. This API uses a promise to return the result.

NOTE This API can be called only after connect is successfully called. Call the API in the worker thread or taskpool thread as this operation is time-consuming.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPSendOptions	Yes	Parameters for sending data over a TCP socket connection. For details, see TCPSendOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions, () => {
  console.info('connect success');
  let tcpSendOptions: socket.TCPSendOptions = {
    data: 'Hello, server!'
  }
  tcp.send(tcpSendOptions).then(() => {
    console.info('send success');
  }).catch((err: BusinessError) => {
    console.error('send fail');
  });
})

close

close(callback: AsyncCallback<void>): void

Closes a TCP socket connection. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();

tcp.close((err: BusinessError) => {
  if (err) {
    console.error('close fail');
    return;
  }
  console.info('close success');
})

close

close(): Promise<void>

Closes a TCP socket connection. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();

tcp.close().then(() => {
  console.info('close success');
}).catch((err: BusinessError) => {
  console.error('close fail');
});

getRemoteAddress

getRemoteAddress(callback: AsyncCallback<NetAddress>): void

Obtains the remote address of a socket connection. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after connect is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<NetAddress>	Yes	Callback used to return the result. If the operation is successful, the remote address is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions, () => {
  console.info('connect success');
  tcp.getRemoteAddress((err: BusinessError, data: socket.NetAddress) => {
    if (err) {
      console.error('getRemoteAddressfail');
      return;
    }
    console.info('getRemoteAddresssuccess:' + JSON.stringify(data));
  })
});

getRemoteAddress

getRemoteAddress(): Promise<NetAddress>

Obtains the remote address of a socket connection. This API uses a promise to return the result.

NOTE This API can be called only after connect is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions).then(() => {
  console.info('connect success');
  tcp.getRemoteAddress().then(() => {
    console.info('getRemoteAddress success');
  }).catch((err: BusinessError) => {
    console.error('getRemoteAddressfail');
  });
}).catch((err: BusinessError) => {
  console.error('connect fail');
});

getState

getState(callback: AsyncCallback<SocketStateBase>): void

Obtains the status of the TCP socket connection. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after bind or connect is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<SocketStateBase>	Yes	Callback used to return the result. If the operation is successful, the status of the TCP socket is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions, () => {
  console.info('connect success');
  tcp.getState((err: BusinessError, data: socket.SocketStateBase) => {
    if (err) {
      console.error('getState fail');
      return;
    }
    console.info('getState success:' + JSON.stringify(data));
  });
});

getState

getState(): Promise<SocketStateBase>

Obtains the status of the TCP socket connection. This API uses a promise to return the result.

NOTE This API can be called only after bind or connect is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<SocketStateBase>	Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions).then(() => {
  console.info('connect success');
  tcp.getState().then(() => {
    console.info('getState success');
  }).catch((err: BusinessError) => {
    console.error('getState fail');
  });
}).catch((err: BusinessError) => {
  console.error('connect fail');
});

getSocketFd¹⁰⁺

getSocketFd(callback: AsyncCallback<number>): void

Obtains the file descriptor of the TCPSocket object. This API uses an asynchronous callback to return the result.

NOTE

• This API can be called only after bind or connect is successfully called.
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<number>	Yes	Callback used to return the result. If the operation is successful, the file descriptor of the socket is returned. Otherwise, undefined is returned.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  // Bind the specified network API.
}
tcp.bind(bindAddr)
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions)
tcp.getSocketFd((err: BusinessError, data: number) => {
  console.error("getSocketFd failed: " + err);
  console.info("socketFd: " + data);
})

getSocketFd¹⁰⁺

getSocketFd(): Promise<number>

Obtains the file descriptor of the TCPSocket object. This API uses a promise to return the result.

NOTE

• This API can be called only after bind or connect is successfully called.
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the result.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let bindAddr: socket.NetAddress = {
    address: '192.168.xx.xxx',
  // Bind the specified network API.
}
tcp.bind(bindAddr)
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}
tcp.connect(tcpconnectoptions)
tcp.getSocketFd().then((data: number) => {
  console.info("socketFd: " + data);
})

setExtraOptions

setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback<void>): void

Sets other properties of the TCPSocket object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after bind or connect is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPExtraOptions	Yes	Other properties of the TCPSocket object. For details, see TCPExtraOptions.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}

interface SocketLinger {
  on: boolean;
  linger: number;
}

tcp.connect(tcpconnectoptions, () => {
  console.info('connect success');
  let tcpExtraOptions: socket.TCPExtraOptions = {
    keepAlive: true,
    OOBInline: true,
    TCPNoDelay: true,
    socketLinger: { on: true, linger: 10 } as SocketLinger,
    receiveBufferSize: 8192,
    sendBufferSize: 8192,
    reuseAddress: true,
    socketTimeout: 3000,
    tcpFastOpen: false
  }
  tcp.setExtraOptions(tcpExtraOptions, (err: BusinessError) => {
    if (err) {
      console.error('setExtraOptions fail');
      return;
    }
    console.info('setExtraOptions success');
  });
});

setExtraOptions

setExtraOptions(options: TCPExtraOptions): Promise<void>

Sets other properties of the TCPSocket object. This API uses a promise to return the result.

NOTE This API can be called only after bind or connect is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPExtraOptions	Yes	Other properties of the TCPSocket object. For details, see TCPExtraOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}

interface SocketLinger {
  on: boolean;
  linger: number;
}

tcp.connect(tcpconnectoptions, () => {
  console.info('connect success');
  let tcpExtraOptions: socket.TCPExtraOptions = {
    keepAlive: true,
    OOBInline: true,
    TCPNoDelay: true,
    socketLinger: { on: true, linger: 10 } as SocketLinger,
    receiveBufferSize: 8192,
    sendBufferSize: 8192,
    reuseAddress: true,
    socketTimeout: 3000,
    tcpFastOpen: false
  }
  tcp.setExtraOptions(tcpExtraOptions).then(() => {
    console.info('setExtraOptions success');
  }).catch((err: BusinessError) => {
    console.error('setExtraOptions fail');
  });
});

getLocalAddress¹²⁺

getLocalAddress(): Promise<NetAddress>

Obtains the local socket address of a TCPSocket connection. This API uses a promise to return the result.

NOTE This API can be called only after bind is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  family: 1,
  port: 8080
}
tcp.bind(bindAddr).then(() => {
  tcp.getLocalAddress().then((localAddress: socket.NetAddress) => {
    console.info("SUCCESS! Address:" + JSON.stringify(localAddress));
  }).catch((err: BusinessError) => {
    console.error("FAILED! Error:" + JSON.stringify(err));
  })
}).catch((err: BusinessError) => {
  console.error('bind fail');
});

on('message')

on(type: 'message', callback: Callback<SocketMessageInfo>): void

Subscribes to message events of the TCPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	Yes	Callback used to return the result.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
tcp.on('message', (value: socket.SocketMessageInfo) => {
  let messageView = '';
  let uint8Array = new Uint8Array(value.message); 
  for (let i: number = 0; i < value.message.byteLength; i++) {
    let messages = uint8Array[i];
    let message = String.fromCharCode(messages);
    messageView += message;
  }
  console.info('on message message: ' + JSON.stringify(messageView));
  console.info('remoteInfo: ' + JSON.stringify(value.remoteInfo));
});

off('message')

off(type: 'message', callback?: Callback<SocketMessageInfo>): void

Unsubscribes from message events of the TCPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let messageView = '';
let callback = (value: socket.SocketMessageInfo) => {
  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.info('on message message: ' + JSON.stringify(messageView));
  console.info('remoteInfo: ' + JSON.stringify(value.remoteInfo));
}
tcp.on('message', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tcp.off('message', callback);
tcp.off('message');

on('connect' | 'close')

on(type: 'connect' | 'close', callback: Callback<void>): void

Subscribes to connect or close events of the TCPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - connect: connection event. - close: close event.
callback	Callback<void>	Yes	Callback used to return the result.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
tcp.on('connect', () => {
  console.info("on connect success")
});
tcp.on('close', () => {
  console.info("on close success")
});

off('connect' | 'close')

off(type: 'connect' | 'close', callback?: Callback<void>): void

Unsubscribes from connect or close events of the TCPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - connect: connection event. - close: close event.
callback	Callback<void>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let callback1 = () => {
  console.info("on connect success");
}
tcp.on('connect', callback1);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tcp.off('connect', callback1);
tcp.off('connect');
let callback2 = () => {
  console.info("on close success");
}
tcp.on('close', callback2);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tcp.off('close', callback2);
tcp.off('close');

on('error')

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the TCPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	Yes	Callback used to return the result.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
tcp.on('error', (err: BusinessError) => {
  console.error("on error, err:" + JSON.stringify(err))
});

off('error')

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the TCPSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let callback = (err: BusinessError) => {
  console.error("on error, err:" + JSON.stringify(err));
}
tcp.on('error', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tcp.off('error', callback);
tcp.off('error');

TCPConnectOptions

Defines TCP socket connection parameters.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
address	NetAddress	No	No	Bound IP address and port number.
timeout	number	No	Yes	Timeout duration of the TCP socket connection, in ms. The default value is 5000.
proxy18+	ProxyOptions	No	Yes	Proxy option. By default, no proxy is used.

TCPSendOptions

Defines the parameters for sending data over a TCP socket connection.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
data	string| ArrayBuffer	No	No	Data to send.
encoding	string	No	Yes	Character encoding format. The options are as follows: UTF-8, UTF-16BE, UTF-16LE, UTF-16, US-ASCII, and ISO-8859-1. The default value is UTF-8.

TCPExtraOptions

Defines other properties of the TCPSocket object. This object is inherited from ExtraOptionsBase.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
keepAlive	boolean	No	Yes	Whether to keep the connection alive. The default value is false. The value true means to keep the connection alive, and the value false indicates the opposite.
OOBInline	boolean	No	Yes	Whether to enable OOBInline. The default value is false. The value true means to enable OOBInline, and the value false indicates the opposite.
TCPNoDelay	boolean	No	Yes	Whether to enable no-delay on the TCP socket connection. The default value is false. The value true means to enable no-delay on the TCP socket connection, and the value false indicates the opposite.
socketLinger	{on:boolean, linger:number}	No	Yes	Socket linger. - on: whether to enable socket linger. The value true means to enable socket linger and false means the opposite. - linger: linger time, in ms. The value ranges from 0 to 65535. Specify this parameter only when on is set to true.
tcpFastOpen24+	boolean	No	Yes	Whether to enable TCP Fast Open (TFO) in the TCP socket connection. This function allows the client to carry data during the first handshake, reducing the connection setup delay and improving the performance in high-frequency short connection scenarios. The default value is false. true: yes; false: no. Currently, this parameter can be configured only on the client. Model restriction: This API can be used only in the stage model.

socket.constructTCPSocketServerInstance¹⁰⁺

constructTCPSocketServerInstance(): TCPSocketServer

Creates a TCPSocketServer object.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
TCPSocketServer	TCPSocketServer object.

Example

import { socket } from '@kit.NetworkKit';
let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();

TCPSocketServer¹⁰⁺

Defines a TCP socket server connection. Before calling TCPSocketServer APIs, you need to call socket.constructTCPSocketServerInstance to create a TCPSocketServer object.

listen¹⁰⁺

listen(address: NetAddress, callback: AsyncCallback<void>): void

Binds the IP address and port number. The port number can be specified or randomly allocated by the system. The server listens to and accepts TCP socket connections established over the socket. Multiple threads are used to process client data concurrently. This API uses an asynchronous callback to return the result.

NOTE The server uses this API to perform the bind, listen, and accept operations. If the bind operation fails, the system randomly allocates a port number.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	NetAddress	Yes	Destination address.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.
2303109	Bad file number.
2303111	Resource temporarily unavailable. Try again.
2303198	Address already in use.
2303199	Cannot assign requested address.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  if (err) {
    console.error("listen fail");
    return;
  }
  console.info("listen success");
})

listen¹⁰⁺

listen(address: NetAddress): Promise<void>

Binds the IP address and port number. The port number can be specified or randomly allocated by the system. The server listens to and accepts TCP socket connections established over the socket. Multiple threads are used to process client data concurrently. This API uses a promise to return the result.

NOTE The server uses this API to perform the bind, listen, and accept operations. If the bind operation fails, the system randomly allocates a port number.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	NetAddress	Yes	Destination address.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.
2303109	Bad file number.
2303111	Resource temporarily unavailable. Try again.
2303198	Address already in use.
2303199	Cannot assign requested address.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr).then(() => {
  console.info('listen success');
}).catch((err: BusinessError) => {
  console.error('listen fail');
});

getState¹⁰⁺

getState(callback: AsyncCallback<SocketStateBase>): void

Obtains the status of a TCP socket server connection. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<SocketStateBase>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  if (err) {
    console.error("listen fail");
    return;
  }
  console.info("listen success");
})
tcpServer.getState((err: BusinessError, data: socket.SocketStateBase) => {
  if (err) {
    console.error('getState fail');
    return;
  }
  console.info('getState success:' + JSON.stringify(data));
})

getState¹⁰⁺

getState(): Promise<SocketStateBase>

Obtains the status of a TCP socket server connection. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<SocketStateBase>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
201	Permission denied.
2300002	System internal error.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  if (err) {
    console.error("listen fail");
    return;
  }
  console.info("listen success");
})
tcpServer.getState().then((data: socket.SocketStateBase) => {
  console.info('getState success' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error('getState fail');
});

getSocketFd²³⁺

getSocketFd(): Promise<number>

Obtains the file descriptor bound to the TCPSocketServer listening port. This API uses a promise to return the result.

NOTE

• This method can be called only after the listen method is successfully called. When listen is called for multiple times, the file descriptor bound to the latest listening port is obtained.
• This API returns -1 in abnormal cases such as listening exceptions or socket closed (for example, after close is called).
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the socket file descriptor.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr).then(() => {
  console.info('listen success');
  tcpServer.getSocketFd().then((fd: number) => {
    console.info(`Socket FD: ${fd}`);
  }).catch((err: BusinessError) => {
    console.error(`getSocketFd fail: ${err.message}, errorCode: ${err.code}`);
  });
}).catch((err: BusinessError) => {
  console.error('listen fail');
});

setExtraOptions¹⁰⁺

setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback<void>): void

Sets other properties of the TCPSocketServer object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPExtraOptions	Yes	Other properties of the TCPSocketServer object.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  if (err) {
    console.error("listen fail");
    return;
  }
  console.info("listen success");
})

interface SocketLinger {
  on: boolean;
  linger: number;
}

let tcpExtraOptions: socket.TCPExtraOptions = {
  keepAlive: true,
  OOBInline: true,
  TCPNoDelay: true,
  socketLinger: { on: true, linger: 10 } as SocketLinger,
  receiveBufferSize: 8192,
  sendBufferSize: 8192,
  reuseAddress: true,
  socketTimeout: 3000
}
tcpServer.setExtraOptions(tcpExtraOptions, (err: BusinessError) => {
  if (err) {
    console.error('setExtraOptions fail');
    return;
  }
  console.info('setExtraOptions success');
});

setExtraOptions¹⁰⁺

setExtraOptions(options: TCPExtraOptions): Promise<void>

Sets other properties of the TCPSocketServer object. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPExtraOptions	Yes	Other properties of the TCPSocketServer object.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}

interface SocketLinger {
  on: boolean;
  linger: number;
}

tcpServer.listen(listenAddr, (err: BusinessError) => {
  if (err) {
    console.error("listen fail");
    return;
  }
  console.info("listen success");
})

let tcpExtraOptions: socket.TCPExtraOptions = {
  keepAlive: true,
  OOBInline: true,
  TCPNoDelay: true,
  socketLinger: { on: true, linger: 10 } as SocketLinger,
  receiveBufferSize: 8192,
  sendBufferSize: 8192,
  reuseAddress: true,
  socketTimeout: 3000
}
tcpServer.setExtraOptions(tcpExtraOptions).then(() => {
  console.info('setExtraOptions success');
}).catch((err: BusinessError) => {
  console.error('setExtraOptions fail');
});

getLocalAddress¹²⁺

getLocalAddress(): Promise<NetAddress>

Obtains the local socket address of a TCPSocketServer connection. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr).then(() => {
  tcpServer.getLocalAddress().then((localAddress: socket.NetAddress) => {
    console.info("SUCCESS! Address:" + JSON.stringify(localAddress));
  }).catch((err: BusinessError) => {
    console.error("FerrorAILED! Error:" + JSON.stringify(err));
  })
}).catch((err: BusinessError) => {
  console.error('listen fail');
});

on('connect')¹⁰⁺

on(type: 'connect', callback: Callback<TCPSocketConnection>): void

Subscribes to connect events of the TCPSocketServer object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. connect: connection event.
callback	Callback<TCPSocketConnection>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();

let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  if (err) {
    console.error("listen fail");
    return;
  }
  console.info("listen success");
  tcpServer.on('connect', (data: socket.TCPSocketConnection) => {
    console.info(JSON.stringify(data))
  });
})

off('connect')¹⁰⁺

off(type: 'connect', callback?: Callback<TCPSocketConnection>): void

Unsubscribes from connect events of the TCPSocketServer object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. connect: connection event.
callback	Callback<TCPSocketConnection>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();

let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  if (err) {
    console.error("listen fail");
    return;
  }
  console.info("listen success");
  let callback = (data: socket.TCPSocketConnection) => {
    console.info('on connect message: ' + JSON.stringify(data));
  }
  tcpServer.on('connect', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  tcpServer.off('connect', callback);
  tcpServer.off('connect');
})

on('error')¹⁰⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the TCPSocketServer object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();

let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  if (err) {
    console.error("listen fail");
    return;
  }
  console.info("listen success");
  tcpServer.on('error', (err: BusinessError) => {
    console.error("on error, err:" + JSON.stringify(err))
  });
})

off('error')¹⁰⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the TCPSocketServer object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();

let listenAddr: socket.NetAddress = {
  address:  '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  if (err) {
    console.error("listen fail");
    return;
  }
  console.info("listen success");
  let callback = (err: BusinessError) => {
    console.error("on error, err:" + JSON.stringify(err));
  }
  tcpServer.on('error', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  tcpServer.off('error', callback);
  tcpServer.off('error');
})

close²⁰⁺

close(): Promise<void>

Stops listening for events of the TCPSocketServer object and releases the port bound by listen. If listen has been called for multiple times, all listening ports of the TCPSocketServer object are released when this API is called. This API uses a promise to return the result.

NOTE This API does not close existing connections. To close connections, call the close API of TCPSocketConnection.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
201	Permission denied.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080,
  family: 1
}
tcpServer.on('connect', (connection: socket.TCPSocketConnection) => {
  console.info("connection clientId: " + connection.clientId);
  // Logical processing
  tcpServer.close(); // Stop event listening.
  connection.close(); // Close the current connection.
});
tcpServer.listen(listenAddr).then(() => {
  console.info('listen success');
}).catch((err: BusinessError) => {
  console.error('listen fail: ' + err.code);
});

TCPSocketConnection¹⁰⁺

Defines a TCPSocketConnection object, that is, the connection between the TCPSocket client and the server. Before calling TCPSocketConnection APIs, you need to obtain a TCPSocketConnection object.

NOTE The TCPSocket client can call related APIs through the TCPSocketConnection object only after a connection is successfully established between the TCPSocket client and the server.

System capability: SystemCapability.Communication.NetStack

Attributes

Name	Type	Read-Only	Optional	Description
clientId	number	No	No	ID of the connection between the client and TCPSocketServer.

send¹⁰⁺

send(options: TCPSendOptions, callback: AsyncCallback<void>): void

Sends data over a TCPSocketConnection object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after a connection with the client is set up.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPSendOptions	Yes	Defines the parameters for sending data over a TCP socket connection.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();

tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  let tcpSendOption: socket.TCPSendOptions = {
    data: 'Hello, client!'
  }
  client.send(tcpSendOption, () => {
    console.info('send success');
  });
});

send¹⁰⁺

send(options: TCPSendOptions): Promise<void>

Sends data over a TCPSocketConnection object. This API uses a promise to return the result.

NOTE This API can be called only after a connection with the client is set up.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPSendOptions	Yes	Defines the parameters for sending data over a TCP socket connection.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();

tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  let tcpSendOption: socket.TCPSendOptions = {
    data: 'Hello, client!'
  }
  client.send(tcpSendOption).then(() => {
    console.info('send success');
  }).catch((err: BusinessError) => {
    console.error('send fail');
  });
});

close¹⁰⁺

close(callback: AsyncCallback<void>): void

Closes a TCP socket connection. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();

tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.close((err: BusinessError) => {
    if (err) {
      console.error('close fail');
      return;
    }
    console.info('close success');
  });
});

close¹⁰⁺

close(): Promise<void>

Closes a TCP socket connection. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
201	Permission denied.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.close().then(() => {
    console.info('close success');
  }).catch((err: BusinessError) => {
    console.error('close fail');
  });
});

getRemoteAddress¹⁰⁺

getRemoteAddress(callback: AsyncCallback<NetAddress>): void

Obtains the remote address of a socket connection. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after a connection with the client is set up.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<NetAddress>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.getRemoteAddress((err: BusinessError, data: socket.NetAddress) => {
    if (err) {
      console.error('getRemoteAddress fail');
      return;
    }
    console.info('getRemoteAddress success:' + JSON.stringify(data));
  });
});

getRemoteAddress¹⁰⁺

getRemoteAddress(): Promise<NetAddress>

Obtains the remote address of a socket connection. This API uses a promise to return the result.

NOTE This API can be called only after a connection with the client is set up.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
201	Permission denied.
2300002	System internal error.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.getRemoteAddress().then(() => {
    console.info('getRemoteAddress success');
  }).catch((err: BusinessError) => {
    console.error('getRemoteAddress fail');
  });
});

getLocalAddress¹²⁺

getLocalAddress(): Promise<NetAddress>

Obtains the local socket address of a TCPSocketConnection connection. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address: "192.168.xx.xx",
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
  let netAddress: socket.NetAddress = {
    address: "192.168.xx.xx",
    port: 8080
  }
  let options: socket.TCPConnectOptions = {
    address: netAddress,
    timeout: 6000
  }
  tcp.connect(options, (err: BusinessError) => {
    if (err) {
      console.error('connect fail');
      return;
    }
    console.info('connect success!');
  })
  tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
    client.getLocalAddress().then((localAddress: socket.NetAddress) => {
      console.info("Family IP Port: " + JSON.stringify(localAddress));
    }).catch((err: BusinessError) => {
      console.error('Error:' + JSON.stringify(err));
    });
  })
})

getSocketFd²³⁺

getSocketFd(): Promise<number>

Obtains the file descriptor of a TCPSocketConnection connection. This API uses a promise to return the result.

NOTE

• This API can be called only after a connection with the client is set up.
• This API returns -1 in abnormal cases such as disconnection and socket closed (for example, after the close API is called).
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the socket file descriptor.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let listenAddr: socket.NetAddress = {
  address: "192.168.xx.xx",
  port: 8080,
  family: 1
}
tcpServer.listen(listenAddr, (err: BusinessError) => {
  tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
    client.getSocketFd().then((fd: number) => {
      console.info(`Socket FD: ${fd}`);
    }).catch((err: BusinessError) => {
      console.error(`getSocketFd fail: ${err.message}, errorCode: ${err.code}`);
    });
  })
}).catch((err: BusinessError) => {
  console.error('listen fail');
});

on('message')¹⁰⁺

on(type: 'message', callback: Callback<SocketMessageInfo>): void

Subscribes to message events of the TCPSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();

tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.on('message', (value: socket.SocketMessageInfo) => {
    let messageView = '';
    let uint8Array = new Uint8Array(value.message); 
    for (let i: number = 0; i < value.message.byteLength; i++) {
      let messages = uint8Array[i];
      let message = String.fromCharCode(messages);
      messageView += message;
    }
    console.info('on message message: ' + JSON.stringify(messageView));
    console.info('remoteInfo: ' + JSON.stringify(value.remoteInfo));
  });
});

off('message')¹⁰⁺

off(type: 'message', callback?: Callback<SocketMessageInfo>): void

Unsubscribes from message events of the TCPSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let callback = (value: socket.SocketMessageInfo) => {
  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.info('on message message: ' + JSON.stringify(messageView));
  console.info('remoteInfo: ' + JSON.stringify(value.remoteInfo));
}
tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.on('message', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  client.off('message', callback);
  client.off('message');
});

on('close')¹⁰⁺

on(type: 'close', callback: Callback<void>): void

Subscribes to close events of the TCPSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. close: close event.
callback	Callback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.on('close', () => {
    console.info("on close success")
  });
});

off('close')¹⁰⁺

off(type: 'close', callback?: Callback<void>): void

Unsubscribes from close events of the TCPSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. close: close event.
callback	Callback<void>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
let callback = () => {
  console.info("on close success");
}
tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.on('close', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  client.off('close', callback);
  client.off('close');
});

on('error')¹⁰⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the TCPSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.on('error', (err: BusinessError) => {
    console.error("on error, err:" + JSON.stringify(err))
  });
});

off('error')¹⁰⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the TCPSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let callback = (err: BusinessError) => {
  console.error("on error, err:" + JSON.stringify(err));
}
let tcpServer: socket.TCPSocketServer = socket.constructTCPSocketServerInstance();
tcpServer.on('connect', (client: socket.TCPSocketConnection) => {
  client.on('error', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  client.off('error', callback);
  client.off('error');
});

Description of TCP Error Codes

The TCP error code mapping is in the format of 2301000 + Linux kernel error code.

For details about error codes, see Socket Error Codes.

socket.constructLocalSocketInstance¹¹⁺

constructLocalSocketInstance(): LocalSocket

Creates a LocalSocket object.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
LocalSocket	LocalSocket object.

Example

import { socket } from '@kit.NetworkKit';
let client: socket.LocalSocket = socket.constructLocalSocketInstance();

LocalSocket¹¹⁺

Defines a LocalSocket object. Before calling LocalSocket APIs, you need to call socket.constructLocalSocketInstance to create a LocalSocket object.

bind¹¹⁺

bind(address: LocalAddress): Promise<void>;

Binds the address of a local socket file. This API uses a promise to return the result.

NOTE This API explicitly binds the client to a local socket file based on the specified address. It is not mandatory in local socket communication.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	LocalAddress	Yes	Local address. For details, see LocalAddress.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301013	Insufficient permissions.
2301022	Invalid argument.
2301098	Address already in use.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance()
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let address : socket.LocalAddress = {
  address: sandboxPath
}
client.bind(address).then(() => {
  console.info('bind success')
}).catch((err: Object) => {
  console.error('failed to bind: ' + JSON.stringify(err))
})

connect¹¹⁺

connect(options: LocalConnectOptions): Promise<void>

Connects to the specified socket file. This API uses a promise to return the result.

NOTE This API allows you to connect to the TCP server without first executing localsocket.bind.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	LocalConnectOptions	Yes	Local socket connection parameters. For details, see LocalConnectOptions.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301013	Insufficient permissions.
2301022	Invalid argument.
2301111	Connection refused.
2301099	Cannot assign requested address.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let localAddress : socket.LocalAddress = {
  address: sandboxPath
}
let connectOpt: socket.LocalConnectOptions = {
  address: localAddress,
  timeout: 6000
}
client.connect(connectOpt).then(() => {
  console.info('connect success')
}).catch((err: Object) => {
  console.error('connect fail: ' + JSON.stringify(err));
});

send¹¹⁺

send(options: LocalSendOptions): Promise<void>

Sends data over a local socket connection. This API uses a promise to return the result.

NOTE This API can be called only after connect is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	LocalSendOptions	Yes	Parameters for sending data over a local socket connection. For details, see LocalSendOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301011	Operation would block.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance()
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let localAddress : socket.LocalAddress = {
  address: sandboxPath
}
let connectOpt: socket.LocalConnectOptions = {
  address: localAddress,
  timeout: 6000
}
client.connect(connectOpt).then(() => {
  console.info('connect success')
}).catch((err: Object) => {
  console.error('connect failed: ' + JSON.stringify(err))
})
let sendOpt: socket.LocalSendOptions = {
  data: 'Hello world!'
}
client.send(sendOpt).then(() => {
  console.info('send success')
}).catch((err: Object) => {
  console.error('send fail: ' + JSON.stringify(err))
})

close¹¹⁺

close(): Promise<void>

Closes a local socket connection. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2301009	Bad file descriptor.

Example

import { socket } from '@kit.NetworkKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();

client.close().then(() => {
  console.info('close success');
}).catch((err: Object) => {
  console.error('close fail: ' + JSON.stringify(err));
});

getState¹¹⁺

getState(): Promise<SocketStateBase>

Obtains the local socket connection status. This API uses a promise to return the result.

NOTE This API can be called only after bind or connect is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<SocketStateBase>	Promise used to return the result.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let localAddress : socket.LocalAddress = {
  address: sandboxPath
}
let connectOpt: socket.LocalConnectOptions = {
  address: localAddress,
  timeout: 6000
}
client.connect(connectOpt).then(() => {
  console.info('connect success');
  client.getState().then(() => {
    console.info('getState success');
  }).catch((err: Object) => {
    console.error('getState fail: ' + JSON.stringify(err))
  });
}).catch((err: Object) => {
  console.error('connect fail: ' + JSON.stringify(err));
});

getSocketFd¹¹⁺

getSocketFd(): Promise<number>

Obtains the file descriptor of the LocalSocket object. This API uses a promise to return the result.

NOTE

• This API can be called only after bind or connect is successfully called.
• The file descriptor is allocated by the system kernel to uniquely identify the local socket in use.
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the result.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let localAddress : socket.LocalAddress = {
  address: sandboxPath
}
let connectOpt: socket.LocalConnectOptions = {
  address: localAddress,
  timeout: 6000
}
client.connect(connectOpt).then(() => {
  console.info('connect ok')
}).catch((err: Object) => {
  console.error('connect fail: ' + JSON.stringify(err))
})
client.getSocketFd().then((data: number) => {
  console.info("fd: " + data);
}).catch((err: Object) => {
  console.error("getSocketFd failed: " + JSON.stringify(err));
})

setExtraOptions¹¹⁺

setExtraOptions(options: ExtraOptionsBase): Promise<void>

Sets the properties of the LocalSocket object. This API uses a promise to return the result.

NOTE This API can be called only after bind or connect is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	ExtraOptionsBase	Yes	Other properties of the LocalSocket connection. For details, see ExtraOptionsBase.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301009	Bad file descriptor.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let localAddress : socket.LocalAddress = {
  address: sandboxPath
}
let connectOpt: socket.LocalConnectOptions = {
  address: localAddress,
  timeout: 6000
}
client.connect(connectOpt).then(() => {
  console.info('connect success');
  let options: socket.ExtraOptionsBase = {
    receiveBufferSize: 8192,
    sendBufferSize: 8192,
    socketTimeout: 3000
  }
  client.setExtraOptions(options).then(() => {
    console.info('setExtraOptions success');
  }).catch((err: Object) => {
    console.error('setExtraOptions fail: ' + JSON.stringify(err));
  });
}).catch((err: Object) => {
  console.error('connect fail: ' + JSON.stringify(err));
});

getExtraOptions¹¹⁺

getExtraOptions(): Promise<ExtraOptionsBase>;

Obtains the socket properties of the LocalSocket object. This API uses a promise to return the result.

NOTE This API can be called only after bind or connect is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<ExtraOptionsBase>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2301009	Bad file descriptor.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let localAddress : socket.LocalAddress = {
  address: sandboxPath
}
let connectOpt: socket.LocalConnectOptions = {
  address: localAddress,
  timeout: 6000
}
client.connect(connectOpt).then(() => {
  console.info('connect success');
  client.getExtraOptions().then((options : socket.ExtraOptionsBase) => {
    console.info('options: ' + JSON.stringify(options));
  }).catch((err: Object) => {
    console.error('setExtraOptions fail: ' + JSON.stringify(err));
  });
}).catch((err: Object) => {
  console.error('connect fail: ' + JSON.stringify(err));
});

getLocalAddress¹²⁺

getLocalAddress(): Promise<string>

Obtains the local socket address of a LocalSocket connection. This API uses a promise to return the result.

NOTE This API can be called only after bind is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<string>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { common } from '@kit.AbilityKit';
import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let address : socket.LocalAddress = {
  address: sandboxPath
}
client.bind(address).then(() => {
  console.error('bind success');
  client.getLocalAddress().then((localPath: string) => {
    console.info("SUCCESS " + JSON.stringify(localPath));
  }).catch((err: BusinessError) => {
    console.error("FAIL " + JSON.stringify(err));
  })
}).catch((err: Object) => {
  console.error('failed to bind: ' + JSON.stringify(err));
})

on('message')¹¹⁺

on(type: 'message', callback: Callback<LocalSocketMessageInfo>): void

Subscribes to message events of the LocalSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<LocalSocketMessageInfo>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let client: socket.LocalSocket = 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.info('total: ' + JSON.stringify(value));
  console.info('message information: ' + messageView);
});

off('message')¹¹⁺

off(type: 'message', callback?: Callback<LocalSocketMessageInfo>): void

Unsubscribes from message events of the LocalSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<LocalSocketMessageInfo>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let messageView = '';
let callback = (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.info('total: ' + JSON.stringify(value));
  console.info('message information: ' + messageView);
}
client.on('message', callback);
client.off('message');

on('connect')¹¹⁺

on(type: 'connect', callback: Callback<void>): void

Subscribes to connect events of the LocalSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type.
callback	Callback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
client.on('connect', () => {
  console.info("on connect success")
});

off('connect')¹¹⁺

off(type: 'connect', callback?: Callback<void>): void

Unsubscribes from connect events of the LocalSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. 'connect': connection event.
callback	Callback<void>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let callback = () => {
  console.info("on connect success");
}
client.on('connect', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
client.off('connect', callback);
client.off('connect');

on('close')¹¹⁺

on(type: 'close', callback: Callback<void>): void

Subscribes to close events of the LocalSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type.
callback	Callback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let callback = () => {
  console.info("on close success");
}
client.on('close', callback);

off('close')¹¹⁺

off(type: 'close', callback?: Callback<void>): void

Unsubscribes from close events of the LocalSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. close: close event.
callback	Callback<void>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let callback = () => {
  console.info("on close success");
}
client.on('close', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
client.off('close', callback);
client.off('close');

on('error')¹¹⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the LocalSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type.
callback	ErrorCallback	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
client.on('error', (err: Object) => {
  console.error("on error, err:" + JSON.stringify(err))
});

off('error')¹¹⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the LocalSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. 'error': error event.
callback	ErrorCallback	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let client: socket.LocalSocket = socket.constructLocalSocketInstance();
let callback = (err: Object) => {
  console.error("on error, err:" + JSON.stringify(err));
}
client.on('error', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
client.off('error', callback);
client.off('error');

LocalSocketMessageInfo¹¹⁺

Defines the data received by the client over a local socket connection.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
message	ArrayBuffer	No	No	Data received.
address	string	No	No	Local socket connection address.
size	number	No	No	Data length.

LocalAddress¹¹⁺

Defines the address of a local socket file. When the address is passed for binding, a socket file is created at this address.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
address	string	No	No	Address of the local socket file.

LocalConnectOptions¹¹⁺

Defines local socket connection parameters.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
address	LocalAddress	No	No	Address of the local socket file.
timeout	number	No	Yes	Timeout duration of the local socket connection, in ms. Default value: 0 You need to manually set this parameter for your application. The recommended value is 5000.

LocalSendOptions¹¹⁺

Defines the request parameters for the LocalSocket object.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
data	string | ArrayBuffer	No	No	Data to be transmitted.
encoding	string	No	Yes	Encoding format of the string.

ExtraOptionsBase

Defines base properties of the LocalSocket object.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
receiveBufferSize	number	No	Yes	Size of the RX buffer, in bytes. The value ranges from 0 to 262144. If this parameter is left unspecified or the unspecified value exceeds the value range, the default value 8192 is used.
sendBufferSize	number	No	Yes	Size of the TX buffer, in bytes. The value ranges from 0 to 262144. If this parameter is left unspecified or the unspecified value exceeds the value range, the default value 8192 is used.
reuseAddress	boolean	No	Yes	Whether to reuse addresses. The value true means to reuse addresses, and the value false means the opposite.
socketTimeout	number	No	Yes	Timeout duration of the local socket connection, in ms.

socket.constructLocalSocketServerInstance¹¹⁺

constructLocalSocketServerInstance(): LocalSocketServer

Creates a LocalSocketServer object.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
LocalSocketServer	LocalSocketServer object.

Example

import { socket } from '@kit.NetworkKit';
let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();

LocalSocketServer¹¹⁺

Defines a local socket server connection. Before calling LocalSocketServer APIs, you need to call socket.constructLocalSocketServerInstance to create a LocalSocketServer object.

listen¹¹⁺

listen(address: LocalAddress): Promise<void>

Binds the address of the local socket file. The server listens to and accepts local socket connections established over the socket. Multiple threads are used to process client data concurrently. This API uses a promise to return the result.

NOTE The server uses this API to complete the bind, listen, and accept operations. If the address of the local socket file is passed for binding, a socket file is automatically created when this API is called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	LocalAddress	Yes	Destination address.

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2303109	Bad file number.
2301013	Insufficient permissions.
2301022	Invalid argument.
2301098	Address already in use.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let addr: socket.LocalAddress = {
  address: sandboxPath
}
server.listen(addr).then(() => {
  console.info('listen success');
}).catch((err: Object) => {
  console.error('listen fail: ' + JSON.stringify(err));
});

getState¹¹⁺

getState(): Promise<SocketStateBase>

Obtains the status of a local socket server connection. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<SocketStateBase>	Promise used to return the result.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';


let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let listenAddr: socket.LocalAddress = {
  address: sandboxPath
}
server.listen(listenAddr).then(() => {
  console.info("listen success");
}).catch((err: Object) => {
  console.error("listen fail: " + JSON.stringify(err));
})
server.getState().then((data: socket.SocketStateBase) => {
  console.info('getState success: ' + JSON.stringify(data));
}).catch((err: Object) => {
  console.error('getState fail: ' + JSON.stringify(err));
});

setExtraOptions¹¹⁺

setExtraOptions(options: ExtraOptionsBase): Promise<void>

Sets the socket properties of the LocalSocketServer object. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	ExtraOptionsBase	Yes	Other properties of the LocalSocketServer object.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301009	Bad file descriptor.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let listenAddr: socket.NetAddress = {
  address: sandboxPath
}
server.listen(listenAddr).then(() => {
  console.info("listen success");
}).catch((err: Object) => {
  console.error("listen fail: " + JSON.stringify(err));
})

let options: socket.ExtraOptionsBase = {
  receiveBufferSize: 8192,
  sendBufferSize: 8192,
  socketTimeout: 3000
}
server.setExtraOptions(options).then(() => {
  console.info('setExtraOptions success');
}).catch((err: Object) => {
  console.error('setExtraOptions fail: ' + JSON.stringify(err));
});

getExtraOptions¹¹⁺

getExtraOptions(): Promise<ExtraOptionsBase>;

Obtains the socket properties of the LocalSocketServer object. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<ExtraOptionsBase>	Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let listenAddr: socket.LocalAddress = {
  address: sandboxPath
}
server.listen(listenAddr).then(() => {
  console.info("listen success");
}).catch((err: Object) => {
  console.error("listen fail: " + JSON.stringify(err));
})
server.getExtraOptions().then((options: socket.ExtraOptionsBase) => {
  console.info('options: ' + JSON.stringify(options));
}).catch((err: Object) => {
  console.error('getExtraOptions fail: ' + JSON.stringify(err));
});

getLocalAddress¹²⁺

getLocalAddress(): Promise<string>

Obtains the local socket address of a LocalSocketServer connection. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<string>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { common } from '@kit.AbilityKit';
import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let listenAddr: socket.LocalAddress = {
  address: sandboxPath
}
server.listen(listenAddr).then(() => {
  console.info("listen success");
  server.getLocalAddress().then((localPath: string) => {
    console.info("SUCCESS " + JSON.stringify(localPath));
  }).catch((err: BusinessError) => {
    console.error("FAIL " + JSON.stringify(err));
  })
}).catch((err: Object) => {
  console.error("listen fail: " + JSON.stringify(err));
})

getSocketFd²³⁺

getSocketFd(): Promise<number>

Obtains the file descriptor bound to the LocalSocketServer listening port. This API uses a promise to return the result.

NOTE

• This method can be called only after the listen method is successfully called.
• This API returns -1 in abnormal cases such as listening exceptions or socket closed (for example, after close is called).
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the socket file descriptor.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let listenAddr : socket.LocalAddress = {
  address: sandboxPath
}

server.listen(listenAddr).then(() => {
  console.info("listen success");
  server.getSocketFd().then((fd: number) => {
    console.info(`Socket FD: ${fd}`);
  }).catch((err: Object) => {
    console.error(`getSocketFd fail: ${JSON.stringify(err)}`);
  });
}).catch((err: Object) => {
  console.error("listen fail: " + JSON.stringify(err));
})

on('connect')¹¹⁺

on(type: 'connect', callback: Callback<LocalSocketConnection>): void

Subscribes to connect events of the LocalSocketServer object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. connect: connection event.
callback	Callback<LocalSocketConnection>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
server.on('connect', (connection: socket.LocalSocketConnection) => {
  if (connection) {
    console.info('accept a client')
  }
});

off('connect')¹¹⁺

off(type: 'connect', callback?: Callback<LocalSocketConnection>): void

Unsubscribes from connect events of the LocalSocketServer object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. 'connect': connection event.
callback	Callback<LocalSocketConnection>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let callback = (connection: socket.LocalSocketConnection) => {
  if (connection) {
    console.info('accept a client')
  }
}
server.on('connect', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
server.off('connect', callback);
server.off('connect');

on('error')¹¹⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the LocalSocketServer object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
server.on('error', (err: Object) => {
  console.error("on error, err:" + JSON.stringify(err))
});

off('error')¹¹⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the LocalSocketServer object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let callback = (err: Object) => {
  console.error("on error, err:" + JSON.stringify(err));
}
server.on('error', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
server.off('error', callback);
server.off('error');

close²⁰⁺

close(): Promise<void>

Stops listening for events of the LocalSocketServer object and releases the port bound by listen. This API uses a promise to return the result.

NOTE This API does not close existing connections. To close the connection, call the [close] (#close11-1) API of [LocalSocketConnection] (#localsocketconnection11).

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2300002	System internal error.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let localserver: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let addr: socket.LocalAddress = {
  address: sandboxPath
}
localserver.on('connect', (connection: socket.LocalSocketConnection) => {
  console.info("connection clientId: " + connection.clientId);
  // Logical processing
  localserver.close(); // Stop event listening.
  connection.close(); // Close the current connection.
});
localserver.listen(addr).then(() => {
  console.info('listen success');
}).catch((err: BusinessError) => {
  console.error('listen fail: ' + err.code);
});

LocalSocketConnection¹¹⁺

Defines a local socket connection, that is, the session between the local socket client and the server. Before calling LocalSocketConnection APIs, you need to obtain a LocalSocketConnection object.

NOTE The LocalSocketConnection client can call related APIs through the LocalSocketConnection object only after a connection is successfully established between the local socket client and the server.

System capability: SystemCapability.Communication.NetStack

Attributes

Name	Type	Read-Only	Optional	Description
clientId	number	No	No	ID of the session between the client and the server.

send¹¹⁺

send(options: LocalSendOptions): Promise<void>

Sends data through a local socket connection. This API uses a promise to return the result.

NOTE This API can be used only after the server obtains a LocalSocketConnection object through the callback of the connect event.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	LocalSendOptions	Yes	Parameters for sending data over a local socket connection.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2301011	Operation would block.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();

server.on('connect', (connection: socket.LocalSocketConnection) => {
  let sendOptions: socket.LocalSendOptions = {
    data: 'Hello, client!'
  }
  connection.send(sendOptions).then(() => {
    console.info('send success');
  }).catch((err: Object) => {
    console.error('send fail: ' + JSON.stringify(err));
  });
});

close¹¹⁺

close(): Promise<void>

Closes a local socket connection. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2301009	Bad file descriptor.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
server.on('connect', (connection: socket.LocalSocketConnection) => {
  connection.close().then(() => {
    console.info('close success');
  }).catch((err: Object) => {
    console.error('close fail: ' + JSON.stringify(err));
  });
});

getLocalAddress¹²⁺

getLocalAddress(): Promise<string>

Obtains the local socket address of a LocalSocketConnection connection. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<string>	Promise used to return the result.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { common } from '@kit.AbilityKit';
import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let localAddr: socket.LocalAddress = {
  address: sandboxPath
}
server.listen(localAddr).then(() => {
  console.info('listen success');
  let client: socket.LocalSocket = socket.constructLocalSocketInstance();
  let connectOpt: socket.LocalConnectOptions = {
    address: localAddr,
    timeout: 6000
  }
  client.connect(connectOpt).then(() => {
    server.getLocalAddress().then((localPath: string) => {
      console.info("success, localPath is" + JSON.stringify(localPath));
    }).catch((err: BusinessError) => {
      console.error("FAIL " + JSON.stringify(err));
    })
  }).catch((err: Object) => {
    console.error('connect fail: ' + JSON.stringify(err));
  });
});

getSocketFd²³⁺

getSocketFd(): Promise<number>

Obtains the file descriptor of a LocalSocketConnection connection. This API uses a promise to return the result.

NOTE

• This method can be called only after a connection is set up.
• This API returns -1 in abnormal cases such as disconnection and socket closed (for example, after the close API is called).
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the socket file descriptor.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let listenAddr : socket.LocalAddress = {
  address: sandboxPath
}
server.on('connect', (connection: socket.LocalSocketConnection) => {
  connection.getSocketFd().then((fd: number) => {
    console.info(`Socket FD: ${fd}`);
  }).catch((err: Object) => {
    console.error(`getSocketFd fail: ${JSON.stringify(err)}`);
  });
});
server.listen(listenAddr).then(() => {
  console.info("listen success");
}).catch((err: Object) => {
  console.error(`listen fail: ${JSON.stringify(err)}`);
})

on('message')¹¹⁺

on(type: 'message', callback: Callback<LocalSocketMessageInfo>): void

Subscribes to message events of the LocalSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<LocalSocketMessageInfo>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

NOTE

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { socket } from '@kit.NetworkKit';
import { common } from '@kit.AbilityKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
let sandboxPath: string = context.filesDir + '/testSocket';
let listenAddr: socket.LocalAddress = {
  address: sandboxPath
}
server.listen(listenAddr).then(() => {
  console.info("listen success");
}).catch((err: Object) => {
  console.error("listen fail: " + JSON.stringify(err));
});
server.on('connect', (connection: socket.LocalSocketConnection) => {
  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.info('total: ' + JSON.stringify(value));
    console.info('message information: ' + messageView);
  });
});

off('message')¹¹⁺

off(type: 'message', callback?: Callback<LocalSocketMessageInfo>): void

Unsubscribes from message events of the LocalSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<LocalSocketMessageInfo>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let callback = (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.info('total: ' + JSON.stringify(value));
  console.info('message information: ' + messageView);
}
server.on('connect', (connection: socket.LocalSocketConnection) => {
  connection.on('message', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  connection.off('message', callback);
  connection.off('message');
});

on('close')¹¹⁺

on(type: 'close', callback: Callback<void>): void

Unsubscribes from close events of the LocalSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. close: close event.
callback	Callback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
server.on('connect', (connection: socket.LocalSocketConnection) => {
  connection.on('close', () => {
    console.info("on close success")
  });
});

off('close')¹¹⁺

off(type: 'close', callback?: Callback<void>): void

Unsubscribes from close events of the LocalSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. close: close event.
callback	Callback<void>	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
let callback = () => {
  console.info("on close success");
}
server.on('connect', (connection: socket.LocalSocketConnection) => {
  connection.on('close', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  connection.off('close', callback);
  connection.off('close');
});

on('error')¹¹⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the LocalSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
server.on('connect', (connection: socket.LocalSocketConnection) => {
  connection.on('error', (err: Object) => {
    console.error("on error, err:" + JSON.stringify(err))
  });
});

off('error')¹¹⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the LocalSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	No	Callback used to return the result. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';

let callback = (err: Object) => {
  console.error("on error, err: " + JSON.stringify(err));
}
let server: socket.LocalSocketServer = socket.constructLocalSocketServerInstance();
server.on('connect', (connection: socket.LocalSocketConnection) => {
  connection.on('error', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  connection.off('error', callback);
  connection.off('error');
});

Description of LocalSocket Error Codes

The LocalSocket error code mapping is in the format of 2301000 + Linux kernel error code.

For details about error codes, see Socket Error Codes.

socket.constructTLSSocketInstance⁹⁺

constructTLSSocketInstance(): TLSSocket

Creates a TLSSocket object.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
TLSSocket	TLSSocket object.

Example

import { socket } from '@kit.NetworkKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();

socket.constructTLSSocketInstance¹²⁺

constructTLSSocketInstance(tcpSocket: TCPSocket): TLSSocket

Upgrades a TCPSocket connection to a TLSSocket connection.

NOTE Before calling constructTLSSocketInstance, ensure that a TCPSocket connection has been established and no data is transmitted. After a successful upgrade, you do not need to call the close API for the TCPSocket object.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
tcpSocket	TCPSocket	Yes	TCPSocket connection to be upgraded.

Return value

Type	Description
TLSSocket	TLSSocket object.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2300002	System internal error.
2303601	Invalid socket FD.
2303602	Socket is not connected.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tcpconnectoptions: socket.TCPConnectOptions = {
  address: netAddress,
  timeout: 6000
}

tcp.connect(tcpconnectoptions, (err: BusinessError) => {
  if (err) {
    console.error('connect fail');
    return;
  }
  console.info('connect success');

  // Ensure that a TCPSocket connection has been established before upgrading it to a TLSSocket connection.
  let tls: socket.TLSSocket = socket.constructTLSSocketInstance(tcp);
})

TLSSocket⁹⁺

Defines a TLS socket connection. Before calling TLSSocket APIs, you need to call socket.constructTLSSocketInstance to create a TLSSocket object.

bind⁹⁺

bind(address: NetAddress, callback: AsyncCallback<void>): void

Binds the IP address and port number. This API uses an asynchronous callback to return the result.

NOTE If the TLSSocket object is upgraded from a TCPSocket object, you do not need to execute the bind API.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	NetAddress	Yes	Local address. For details, see NetAddress.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, the result of binding the local IP address and port number is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2303198	Address already in use.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});

bind⁹⁺

bind(address: NetAddress): Promise<void>

Binds the IP address and port number. This API uses a promise to return the result.

NOTE If the TLSSocket object is upgraded from a TCPSocket object, you do not need to execute the bind API.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
address	NetAddress	Yes	Local address. For details, see NetAddress.

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
201	Permission denied.
2303198	Address already in use.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr).then(() => {
  console.info('bind success');
}).catch((err: BusinessError) => {
  console.error('bind fail');
});

getState⁹⁺

getState(callback: AsyncCallback<SocketStateBase>): void

Obtains the status of the TLS socket connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<SocketStateBase>	Yes	Callback used to return the result. If the operation is successful, the status of the TLS socket connection is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
tls.getState((err: BusinessError, data: socket.SocketStateBase) => {
  if (err) {
    console.error('getState fail');
    return;
  }
  console.info('getState success:' + JSON.stringify(data));
});

getState⁹⁺

getState(): Promise<SocketStateBase>

Obtains the status of the TLS socket connection. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<SocketStateBase>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes.

ID	Error Message
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
tls.getState().then(() => {
  console.info('getState success');
}).catch((err: BusinessError) => {
  console.error('getState fail');
});

setExtraOptions⁹⁺

setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback<void>): void

Sets other properties of the TCPSocket object after bind is successfully called. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPExtraOptions	Yes	Other properties of the TCPSocket object. For details, see TCPExtraOptions.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, the result of setting other properties of the TCPSocket object is returned. If the operation fails, an error message is returned.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});

interface SocketLinger {
  on: boolean;
  linger: number;
}

let tcpExtraOptions: socket.TCPExtraOptions = {
  keepAlive: true,
  OOBInline: true,
  TCPNoDelay: true,
  socketLinger: { on: true, linger: 10 } as SocketLinger,
  receiveBufferSize: 8192,
  sendBufferSize: 8192,
  reuseAddress: true,
  socketTimeout: 3000,
  tcpFastOpen: false
}
tls.setExtraOptions(tcpExtraOptions, (err: BusinessError) => {
  if (err) {
    console.error('setExtraOptions fail');
    return;
  }
  console.info('setExtraOptions success');
});

setExtraOptions⁹⁺

setExtraOptions(options: TCPExtraOptions): Promise<void>

Sets other properties of the TCPSocket object after bind is successfully called. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPExtraOptions	Yes	Other properties of the TCPSocket object. For details, see TCPExtraOptions.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
401	Parameter error.
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});

interface SocketLinger {
  on: boolean;
  linger: number;
}

let tcpExtraOptions: socket.TCPExtraOptions = {
  keepAlive: true,
  OOBInline: true,
  TCPNoDelay: true,
  socketLinger: { on: true, linger: 10 } as SocketLinger,
  receiveBufferSize: 8192,
  sendBufferSize: 8192,
  reuseAddress: true,
  socketTimeout: 3000,
  tcpFastOpen: false
}
tls.setExtraOptions(tcpExtraOptions).then(() => {
  console.info('setExtraOptions success');
}).catch((err: BusinessError) => {
  console.error('setExtraOptions fail');
});

on('message')⁹⁺

on(type: 'message', callback: Callback<SocketMessageInfo>): void

Subscribes to message events of the TLSSocket object. This API uses an asynchronous callback to return the result.

NOTE

This API can be called only after bind is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
  tls.on('message', (value: socket.SocketMessageInfo) => {
    let messageView = '';
    let uint8Array = new Uint8Array(value.message); 
    for (let i: number = 0; i < value.message.byteLength; i++) {
      let messages = uint8Array[i];
      let message = String.fromCharCode(messages);
      messageView += message;
    }
    console.info('on message message: ' + JSON.stringify(messageView));
    console.info('remoteInfo: ' + JSON.stringify(value.remoteInfo));
  });
});

off('message')⁹⁺

off(type: 'message', callback?: Callback<SocketMessageInfo>): void

Unsubscribes from message events of the TLSSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	No	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let messageView = '';
let callback = (value: socket.SocketMessageInfo) => {
  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.info('on message message: ' + JSON.stringify(messageView));
  console.info('remoteInfo: ' + JSON.stringify(value.remoteInfo));
}
tls.on('message', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tls.off('message', callback);

on('connect' | 'close')⁹⁺

on(type: 'connect' | 'close', callback: Callback<void>): void

Subscribes to connect or close events of the TLSSocket object. This API uses an asynchronous callback to return the result.

NOTE

This API can be called only after bind is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - connect: connection event. - close: close event.
callback	Callback<void>	Yes	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
  tls.on('connect', () => {
    console.info("on connect success")
  });
  tls.on('close', () => {
    console.info("on close success")
  });
});

off('connect' | 'close')⁹⁺

off(type: 'connect' | 'close', callback?: Callback<void>): void

Unsubscribes from connect or close events of the TLSSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - connect: connection event. - close: close event.
callback	Callback<void>	No	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let callback1 = () => {
  console.info("on connect success");
}
tls.on('connect', callback1);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tls.off('connect', callback1);
tls.off('connect');
let callback2 = () => {
  console.info("on close success");
}
tls.on('close', callback2);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tls.off('close', callback2);

on('error')⁹⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the TLSSocket object. This API uses an asynchronous callback to return the result.

NOTE

This API can be called only after bind is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	Yes	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
  tls.on('error', (err: BusinessError) => {
    console.error("on error, err:" + JSON.stringify(err))
  });
});

off('error')⁹⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the TLSSocket object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	No	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let callback = (err: BusinessError) => {
  console.error("on error, err:" + JSON.stringify(err));
}
tls.on('error', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tls.off('error', callback);

connect⁹⁺

connect(options: TLSConnectOptions, callback: AsyncCallback<void>): void

Sets up a TLSSocket connection, and creates and initializes a TLS session after bind is successfully called. During this process, a TLS/SSL handshake is performed between the application and the server to implement data transmission. This API uses an asynchronous callback to return the result. Note that ca in secureOptions of the options parameter is mandatory in API version 11 or earlier. You need to enter the CA certificate of the server for certificate authentication. The certificate content starts with "-----BEGIN CERTIFICATE-----" and ends with "-----END CERTIFICATE-----". This field is optional since API version 12.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TLSConnectOptions	Yes	Parameters required for the TLS socket connection.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303104	Interrupted system call.
2303109	Bad file number.
2303111	Resource temporarily unavailable. Try again.
2303188	Socket operation on non-socket.
2303191	Incorrect socket protocol type.
2303198	Address already in use.
2303199	Cannot assign requested address.
2303210	Connection timed out.
2303501	SSL is null.
2303502	An error occurred when reading data on the TLS socket.
2303503	An error occurred when writing data on the TLS socket.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.
2301206	Socks5 failed to connect to the proxy server.
2301207	Socks5 username or password is invalid.
2301208	Socks5 failed to connect to the remote server.
2301209	Socks5 failed to negotiate the authentication method.
2301210	Socks5 failed to send the message.
2301211	Socks5 failed to receive the message.
2301212	Socks5 serialization error.
2301213	Socks5 deserialization error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsTwoWay: socket.TLSSocket = socket.constructTLSSocketInstance();  // Two way authentication
let bindAddr: socket.NetAddress = {
    address: '192.168.xx.xxx',
  // Bind the specified network API.
}
tlsTwoWay.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let twoWayNetAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let twoWaySecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: twoWayNetAddr,
  secureOptions: twoWaySecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}

tlsTwoWay.connect(tlsConnectOptions, (err: BusinessError) => {
  console.error("connect callback error" + err);
});

let tlsOneWay: socket.TLSSocket = socket.constructTLSSocketInstance(); // One way authentication
tlsOneWay.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let oneWayNetAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let oneWaySecureOptions: socket.TLSSecureOptions = {
  ca: ["xxxx", "xxxx"],
  cipherSuite: "AES256-SHA256"
}
let tlsOneWayConnectOptions: socket.TLSConnectOptions = {
  address: oneWayNetAddr,
  secureOptions: oneWaySecureOptions
}
tlsOneWay.connect(tlsOneWayConnectOptions, (err: BusinessError) => {
  console.error("connect callback error" + err);
});

Example (with socket proxy):

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsTwoWay: socket.TLSSocket = socket.constructTLSSocketInstance(); // Two-way authentication
let bindAddr: socket.NetAddress = {
   address: '192.168.xx.xxx',
  // Bind the specified network API.
}
tlsTwoWay.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let twoWayNetAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let socks5Server: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let twoWaySecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let proxyOptions: socket.ProxyOptions = {
  type : 1,
  address: socks5Server,
  username: "xxx",
  password: "xxx"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: twoWayNetAddr,
  secureOptions: twoWaySecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"],
  proxy: proxyOptions,
}

tlsTwoWay.connect(tlsConnectOptions, (err: BusinessError) => {
  console.error("connect callback error" + err);
});

let tlsOneWay: socket.TLSSocket = socket.constructTLSSocketInstance(); // One-way authentication
tlsOneWay.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let oneWayNetAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let oneWaySecureOptions: socket.TLSSecureOptions = {
  ca: ["xxxx", "xxxx"],
  cipherSuite: "AES256-SHA256"
}
let oneWayProxyOptions: socket.ProxyOptions = {
  type : 1,
  address: socks5Server,
  username: "xxx",
  password: "xxx"
}
let tlsOneWayConnectOptions: socket.TLSConnectOptions = {
  address: oneWayNetAddr,
  secureOptions: oneWaySecureOptions,
  proxy: oneWayProxyOptions,
}
tlsOneWay.connect(tlsOneWayConnectOptions, (err: BusinessError) => {
  console.error("connect callback error" + err);
});

connect⁹⁺

connect(options: TLSConnectOptions): Promise<void>

Sets up a TLSSocket connection, and creates and initializes a TLS session after bind is successfully called. During this process, a TLS/SSL handshake is performed between the application and the server to implement data transmission. Both two-way and one-way authentication modes are supported. This API uses a promise to return the result. Note that ca in secureOptions of the options parameter is mandatory in API version 11 or earlier. You need to enter the CA certificate of the server for certificate authentication. The certificate content starts with "-----BEGIN CERTIFICATE-----" and ends with "-----END CERTIFICATE-----". This field is optional since API version 12.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TLSConnectOptions	Yes	Parameters required for the connection.

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303104	Interrupted system call.
2303109	Bad file number.
2303111	Resource temporarily unavailable. Try again.
2303188	Socket operation on non-socket.
2303191	Incorrect socket protocol type.
2303198	Address already in use.
2303199	Cannot assign requested address.
2303210	Connection timed out.
2303501	SSL is null.
2303502	An error occurred when reading data on the TLS socket.
2303503	An error occurred when writing data on the TLS socket.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.
2301206	Socks5 failed to connect to the proxy server.
2301207	Socks5 username or password is invalid.
2301208	Socks5 failed to connect to the remote server.
2301209	Socks5 failed to negotiate the authentication method.
2301210	Socks5 failed to send the message.
2301211	Socks5 failed to receive the message.
2301212	Socks5 serialization error.
2301213	Socks5 deserialization error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsTwoWay: socket.TLSSocket = socket.constructTLSSocketInstance();  // Two way authentication
let bindAddr: socket.NetAddress = {
   address: '192.168.xx.xxx',
  // Bind the specified network API.
}
tlsTwoWay.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let twoWayNetAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let twoWaySecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: twoWayNetAddr,
  secureOptions: twoWaySecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}

tlsTwoWay.connect(tlsConnectOptions).then(() => {
  console.info("connect successfully");
}).catch((err: BusinessError) => {
  console.error("connect failed " + JSON.stringify(err));
});

let tlsOneWay: socket.TLSSocket = socket.constructTLSSocketInstance(); // One way authentication
tlsOneWay.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let oneWayNetAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let oneWaySecureOptions: socket.TLSSecureOptions = {
  ca: ["xxxx", "xxxx"],
  cipherSuite: "AES256-SHA256"
}
let tlsOneWayConnectOptions: socket.TLSConnectOptions = {
  address: oneWayNetAddr,
  secureOptions: oneWaySecureOptions
}
tlsOneWay.connect(tlsOneWayConnectOptions).then(() => {
  console.info("connect successfully");
}).catch((err: BusinessError) => {
  console.error("connect failed " + JSON.stringify(err));
});

Example (with socket proxy):

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsTwoWay: socket.TLSSocket = socket.constructTLSSocketInstance(); // Two-way authentication
let bindAddr: socket.NetAddress = {
   address: '192.168.xx.xxx',
  // Bind the specified network API.
}
tlsTwoWay.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let twoWayNetAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let socks5Server: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let twoWaySecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let proxyOptions: socket.ProxyOptions = {
  type : 1,
  address: socks5Server,
  username: "xxx",
  password: "xxx"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: twoWayNetAddr,
  secureOptions: twoWaySecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"],
  proxy: proxyOptions,
}

tlsTwoWay.connect(tlsConnectOptions).then(() => {
  console.info("connect successfully");
}).catch((err: BusinessError) => {
  console.error("connect failed " + JSON.stringify(err));
});

let tlsOneWay: socket.TLSSocket = socket.constructTLSSocketInstance(); // One-way authentication
tlsOneWay.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
let oneWayNetAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let oneWaySecureOptions: socket.TLSSecureOptions = {
  ca: ["xxxx", "xxxx"],
  cipherSuite: "AES256-SHA256"
}
let oneWayProxyOptions: socket.ProxyOptions = {
  type : 1,
  address: socks5Server,
  username: "xxx",
  password: "xxx"
}
let tlsOneWayConnectOptions: socket.TLSConnectOptions = {
  address: oneWayNetAddr,
  secureOptions: oneWaySecureOptions,
  proxy: oneWayProxyOptions,
}
tlsOneWay.connect(tlsOneWayConnectOptions).then(() => {
  console.info("connect successfully");
}).catch((err: BusinessError) => {
  console.error("connect failed " + JSON.stringify(err));
});

getRemoteAddress⁹⁺

getRemoteAddress(callback: AsyncCallback<NetAddress>): void

Obtains the remote address of a TLS socket connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<NetAddress>	Yes	Callback used to return the result. If the operation is successful, the remote address is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getRemoteAddress((err: BusinessError, data: socket.NetAddress) => {
  if (err) {
    console.error('getRemoteAddress fail');
    return;
  }
  console.info('getRemoteAddress success:' + JSON.stringify(data));
});

getRemoteAddress⁹⁺

getRemoteAddress(): Promise<NetAddress>

Obtains the remote address of a TLS socket connection. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getRemoteAddress().then(() => {
  console.info('getRemoteAddress success');
}).catch((err: BusinessError) => {
  console.error('getRemoteAddress fail');
});

getCertificate⁹⁺

getCertificate(callback: AsyncCallback<X509CertRawData>): void

Obtains the local digital certificate after a TLSSocket connection is established. This API is applicable to two-way authentication. It uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<X509CertRawData>	Yes	Callback used to return the result. If the operation is successful, the local certificate is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303504	An error occurred when verifying the X.509 certificate.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getCertificate((err: BusinessError, data: socket.X509CertRawData) => {
  if (err) {
    console.error("getCertificate callback error = " + err);
  } else {
    console.info("getCertificate callback = " + data);
  }
});

getCertificate⁹⁺

getCertificate():Promise<X509CertRawData>

Obtains the local digital certificate after a TLSSocket connection is established. This API is applicable to two-way authentication. It uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<X509CertRawData>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303504	An error occurred when verifying the X.509 certificate.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { util } from '@kit.ArkTS';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getCertificate().then((data: socket.X509CertRawData) => {
  const decoder = util.TextDecoder.create();
  const str = decoder.decodeToString(data.data);
  console.info("getCertificate: " + str);
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});

getRemoteCertificate⁹⁺

getRemoteCertificate(callback: AsyncCallback<X509CertRawData>): void

Obtains the digital certificate of the server after a TLSSocket connection is established. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<X509CertRawData>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { util } from '@kit.ArkTS';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getRemoteCertificate((err: BusinessError, data: socket.X509CertRawData) => {
  if (err) {
    console.error("getRemoteCertificate callback error = " + err);
  } else {
    const decoder = util.TextDecoder.create();
    const str = decoder.decodeToString(data.data);
    console.info("getRemoteCertificate callback = " + str);
  }
});

getRemoteCertificate⁹⁺

getRemoteCertificate():Promise<X509CertRawData>

Obtains the digital certificate of the server after a TLSSocket connection is established. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<X509CertRawData>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { util } from '@kit.ArkTS';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getRemoteCertificate().then((data: socket.X509CertRawData) => {
  const decoder = util.TextDecoder.create();
  const str = decoder.decodeToString(data.data);
  console.info("getRemoteCertificate:" + str);
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});

getProtocol⁹⁺

getProtocol(callback: AsyncCallback<string>): void

Obtains the communication protocol version after a TLSSocket connection is established. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<string>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303505	An error occurred in the TLS system call.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getProtocol((err: BusinessError, data: string) => {
  if (err) {
    console.error("getProtocol callback error = " + err);
  } else {
    console.info("getProtocol callback = " + data);
  }
});

getProtocol⁹⁺

getProtocol():Promise<string>

Obtains the communication protocol version after a TLSSocket connection is established. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<string>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303505	An error occurred in the TLS system call.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getProtocol().then((data: string) => {
  console.info(data);
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});

getCipherSuite⁹⁺

getCipherSuite(callback: AsyncCallback<Array<string>>): void

Obtains the cipher suite negotiated by both communication parties after a TLSSocket connection is established. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<string>>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303502	An error occurred when reading data on the TLS socket.
2303505	An error occurred in the TLS system call.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getCipherSuite((err: BusinessError, data: Array<string>) => {
  if (err) {
    console.error("getCipherSuite callback error = " + err);
  } else {
    console.info("getCipherSuite callback = " + data);
  }
});

getCipherSuite⁹⁺

getCipherSuite(): Promise<Array<string>>

Obtains the cipher suite negotiated by both communication parties after a TLSSocket connection is established. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<Array<string>>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303502	An error occurred when reading data on the TLS socket.
2303505	An error occurred in the TLS system call.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getCipherSuite().then((data: Array<string>) => {
  console.info('getCipherSuite success:' + JSON.stringify(data));
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});

getSignatureAlgorithms⁹⁺

getSignatureAlgorithms(callback: AsyncCallback<Array<string>>): void

Obtains the signing algorithm negotiated by both communication parties after a TLSSocket connection is established. This API is applicable to two-way authentication. It uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<string>>	Yes	Callback used to return the result.

Error codes

ID	Error Message
2303501	SSL is null.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getSignatureAlgorithms((err: BusinessError, data: Array<string>) => {
  if (err) {
    console.error("getSignatureAlgorithms callback error = " + err);
  } else {
    console.info("getSignatureAlgorithms callback = " + data);
  }
});

getSignatureAlgorithms⁹⁺

getSignatureAlgorithms(): Promise<Array<string>>

Obtains the signing algorithm negotiated by both communication parties after a TLSSocket connection is established. This API is applicable to two-way authentication. It uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<Array<string>>	Promise used to return the result.

Error codes

ID	Error Message
2303501	SSL is null.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getSignatureAlgorithms().then((data: Array<string>) => {
  console.info("getSignatureAlgorithms success" + data);
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});

getLocalAddress¹²⁺

getLocalAddress(): Promise<NetAddress>

Obtains the local socket address of a TLSSocket connection. This API uses a promise to return the result.

NOTE Call this API only after the TLSSocketServer connection is successfully established.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result.

Error codes

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.getLocalAddress().then((localAddress: socket.NetAddress) => {
  console.info("Get success: " + JSON.stringify(localAddress));
}).catch((err: BusinessError) => {
  console.error("Get failed, error: " + JSON.stringify(err));
})

getSocketFd¹⁶⁺

getSocketFd(): Promise<number>

Obtains the file descriptor of the TLSSocket object. This API uses a promise to return the result.

NOTE

• This API can be called only after bind is successfully called.
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the result.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
let bindAddr: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
tls.bind(bindAddr, (err: BusinessError) => {
  if (err) {
    console.error('bind fail');
    return;
  }
  console.info('bind success');
});
tls.getSocketFd().then((data: number) => {
  console.info("tls socket fd: " + data);
})

send⁹⁺

send(data: string | ArrayBuffer, callback: AsyncCallback<void>): void

Sends a message to the server after a TLSSocket connection is established. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
data	string | ArrayBuffer	Yes	Data content of the message to send.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303503	An error occurred when writing data on the TLS socket.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.send("xxxx", (err: BusinessError) => {
  if (err) {
    console.error("send callback error = " + err);
  } else {
    console.info("send success");
  }
});

send⁹⁺

send(data: string | ArrayBuffer): Promise<void>

Sends a message to the server after a TLSSocket connection is established. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
data	string | ArrayBuffer	Yes	Data content of the message to send.

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303503	An error occurred when writing data on the TLS socket.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.send("xxxx").then(() => {
  console.info("send success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});

close⁹⁺

close(callback: AsyncCallback<void>): void

Closes a TLSSocket connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.close((err: BusinessError) => {
  if (err) {
    console.error("close callback error = " + err);
  } else {
    console.info("close success");
  }
});

close⁹⁺

close(): Promise<void>

Closes a TLSSocket connection. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tls: socket.TLSSocket = socket.constructTLSSocketInstance();
tls.close().then(() => {
  console.info("close success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});

TLSConnectOptions⁹⁺

Defines TLS connection options.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
address	NetAddress	No	No	Gateway address.
secureOptions	TLSSecureOptions	No	No	TLS security options.
ALPNProtocols	Array<string>	No	Yes	ALPN protocol. The value range is ["spdy/1", "http/1.1"]. The default value is [].
skipRemoteValidation12+	boolean	No	Yes	Whether to skip certificate authentication on the server. The default value is false. The value true means to skip certificate authentication on the server, and the value false means the opposite.
proxy18+	ProxyOptions	No	Yes	Proxy option. By default, no proxy is used.
timeout22+	number	No	Yes	Connection timeout interval, in milliseconds. The default value is 0. The input value must be an integer ranging from 0 to 4294967295. The TLS socket connection fails after the timeout interval.

TLSSecureOptions⁹⁺

TLS security options. When cert (local certificate) and key (private key) are not empty, the two-way authentication mode is enabled. If cert or key is empty, one-way authentication is enabled.

System capability: SystemCapability.Communication.NetStack

Name	Type	Read-Only	Optional	Description
ca	string | Array<string>	No	Yes	CA certificate of the server, which is used to authenticate the digital certificate of the server. The default value is the preset CA certificate12+. A maximum of 1000 certificates can be set.
cert	string | Array<string>	No	Yes	Digital certificate of the local client. An array can be passed since API version 24. A maximum of 1000 certificates can be set.
key	string	No	Yes	Private key of the local digital certificate.
password	string	No	Yes	Password for reading the private key.
protocols	Protocol |Array<Protocol>	No	Yes	TLS protocol version. The default value is TLSv1.2.
useRemoteCipherPrefer	boolean	No	Yes	Whether to use the remote cipher suite preferentially. The value true means to use the remote cipher suite preferentially, and the value false means the opposite.
signatureAlgorithms	string	No	Yes	Signing algorithm used during communication. The default value is "".
cipherSuite	string	No	Yes	Cipher suite used during communication. The default value is "".
isBidirectionalAuthentication12+	boolean	No	Yes	Two-way authentication. The default value is false. The value true means to enable two-way authentication, and the value false means the opposite.

Protocol⁹⁺

Enumerates TLS protocol versions.

System capability: SystemCapability.Communication.NetStack

Name	Value	Description
TLSv12	"TLSv1.2"	TLSv1.2.
TLSv13	"TLSv1.3"	TLSv1.3.

X509CertRawData⁹⁺

type X509CertRawData = cert.EncodingBlob

Defines the certificate raw data.

System capability: SystemCapability.Communication.NetStack

Type	Description
cert.EncodingBlob	Certificate encoding BLOB type.

socket.constructTLSSocketServerInstance¹⁰⁺

constructTLSSocketServerInstance(): TLSSocketServer

Creates a TLSSocketServer object.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
TLSSocketServer	TLSSocketServer object.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();

TLSSocketServer¹⁰⁺

Defines a TLS socket server connection. Before calling TLSSocketServer APIs, you need to call socket.constructTLSSocketServerInstance to create a TLSSocketServer object.

listen¹⁰⁺

listen(options: TLSConnectOptions, callback: AsyncCallback<void>): void

Listens for client connections after bind is successfully called to bind the IP address and port of TLSSocketServer. This API uses an asynchronous callback to return the result. After a connection is established, a TLS session will be created and initialized and a certificate key will be loaded and verified.

NOTE

If the IP address is set to 0.0.0.0, all local IP addresses can be listened on.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TLSConnectOptions	Yes	Parameters required for the connection.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.
2303109	Bad file number.
2303111	Resource temporarily unavailable. Try again.
2303198	Address already in use.
2303199	Cannot assign requested address.
2303501	SSL is null.
2303502	An error occurred when reading data on the TLS socket.
2303503	An error occurred when writing data on the TLS socket.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"],
  skipRemoteValidation: false
}
tlsServer.listen(tlsConnectOptions, (err: BusinessError) => {
  console.error("listen callback error" + err);
});

listen¹⁰⁺

listen(options: TLSConnectOptions): Promise<void>

Listens for client connections after bind is successfully called to bind the IP address and port of TLSSocketServer. This API uses an asynchronous callback to return the result. After a connection is established, a TLS session will be created and initialized and a certificate key will be loaded and verified.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TLSConnectOptions	Yes	Parameters required for the connection.

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
201	Permission denied.
2300002	System internal error.
2303109	Bad file number.
2303111	Resource temporarily unavailable. Try again.
2303198	Address already in use.
2303199	Cannot assign requested address.
2303501	SSL is null.
2303502	An error occurred when reading data on the TLS socket.
2303503	An error occurred when writing data on the TLS socket.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"],
  skipRemoteValidation: false
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed: " + JSON.stringify(err));
});

getState¹⁰⁺

getState(callback: AsyncCallback<SocketStateBase>): void

Obtains the status of the TLS socket server connection upon successful listening. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<SocketStateBase>	Yes	Callback used to return the result. If the operation is successful, the status of the TLS socket server connection is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed: " + JSON.stringify(err));
});
tlsServer.getState((err: BusinessError, data: socket.SocketStateBase) => {
  if (err) {
    console.error('getState fail');
    return;
  }
  console.info('getState success:' + JSON.stringify(data));
});

getState¹⁰⁺

getState(): Promise<SocketStateBase>

Obtains the status of the TLS socket server connection upon successful listening. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<SocketStateBase>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed: " + JSON.stringify(err));
});
tlsServer.getState().then(() => {
  console.info('getState success');
}).catch((err: BusinessError) => {
  console.error('getState fail');
});

getSocketFd²³⁺

getSocketFd(): Promise<number>

Obtains the file descriptor bound to the TLSSocketServer listening port. This API uses a promise to return the result.

NOTE

• This method can be called only after the listen method is successfully called. When listen is called for multiple times, the file descriptor bound to the latest listening port is obtained.
• This API returns -1 in abnormal cases such as listening exceptions or socket closed (for example, after close is called).
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the socket file descriptor.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen success");
  tlsServer.getSocketFd().then((fd: number) => {
    console.info(`Socket FD: ${fd}`);
  }).catch((err: BusinessError) => {
    console.error(`getSocketFd fail: ${err.message}, errorCode: ${err.code}`);
  });
}).catch((err: BusinessError) => {
  console.error(`listen failed: ${JSON.stringify(err)}`);
});

setExtraOptions¹⁰⁺

setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback<void>): void

Sets other properties of the TLSSocketServer object after listen is successfully called. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPExtraOptions	Yes	Other properties of the TLSSocketServer object.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

interface SocketLinger {
  on: boolean;
  linger: number;
}

let tcpExtraOptions: socket.TCPExtraOptions = {
  keepAlive: true,
  OOBInline: true,
  TCPNoDelay: true,
  socketLinger: { on: true, linger: 10 } as SocketLinger,
  receiveBufferSize: 8192,
  sendBufferSize: 8192,
  reuseAddress: true,
  socketTimeout: 3000
}
tlsServer.setExtraOptions(tcpExtraOptions, (err: BusinessError) => {
  if (err) {
    console.error('setExtraOptions fail');
    return;
  }
  console.info('setExtraOptions success');
});

setExtraOptions¹⁰⁺

setExtraOptions(options: TCPExtraOptions): Promise<void>

Sets other properties of the TLSSocketServer object after listen is successfully called. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
options	TCPExtraOptions	Yes	Other properties of the TLSSocketServer object.

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

interface SocketLinger {
  on: boolean;
  linger: number;
}

let tcpExtraOptions: socket.TCPExtraOptions = {
  keepAlive: true,
  OOBInline: true,
  TCPNoDelay: true,
  socketLinger: { on: true, linger: 10 } as SocketLinger,
  receiveBufferSize: 8192,
  sendBufferSize: 8192,
  reuseAddress: true,
  socketTimeout: 3000
}
tlsServer.setExtraOptions(tcpExtraOptions).then(() => {
  console.info('setExtraOptions success');
}).catch((err: BusinessError) => {
  console.error('setExtraOptions fail');
});

getCertificate¹⁰⁺

getCertificate(callback: AsyncCallback<X509CertRawData>): void

Obtains the local digital certificate after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<X509CertRawData>	Yes	Callback used to return the result. If the operation is successful, the local certificate is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303504	An error occurred when verifying the X.509 certificate.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { util } from '@kit.ArkTS';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed: " + JSON.stringify(err));
});
tlsServer.getCertificate((err: BusinessError, data: socket.X509CertRawData) => {
  if (err) {
    console.error("getCertificate callback error = " + err);
  } else {
    const decoder = util.TextDecoder.create();
    const str = decoder.decodeToString(data.data);
    console.info("getCertificate callback: " + str);
  }
});

getCertificate¹⁰⁺

getCertificate():Promise<X509CertRawData>

Obtains the local digital certificate after a TLSSocketServer connection is established. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<X509CertRawData>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303504	An error occurred when verifying the X.509 certificate.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { util } from '@kit.ArkTS';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed: " + JSON.stringify(err));
});
tlsServer.getCertificate().then((data: socket.X509CertRawData) => {
  const decoder = util.TextDecoder.create();
  const str = decoder.decodeToString(data.data);
  console.info("getCertificate: " + str);
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});

getProtocol¹⁰⁺

getProtocol(callback: AsyncCallback<string>): void

Obtains the communication protocol version after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<string>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303505	An error occurred in the TLS system call.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed: " + JSON.stringify(err));
});
tlsServer.getProtocol((err: BusinessError, data: string) => {
  if (err) {
    console.error("getProtocol callback error = " + err);
  } else {
    console.info("getProtocol callback = " + data);
  }
});

getProtocol¹⁰⁺

getProtocol():Promise<string>

Obtains the communication protocol version after a TLSSocketServer connection is established. This API uses a promise to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<string>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303505	An error occurred in the TLS system call.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed: " + JSON.stringify(err));
});
tlsServer.getProtocol().then((data: string) => {
  console.info(data);
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});

getLocalAddress¹²⁺

getLocalAddress(): Promise<NetAddress>

Obtains the local socket address of a TLSSocketServer connection. This API uses a promise to return the result.

NOTE Call this API only after the TLSSocketServer connection is successfully established.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result.

Error codes

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
tlsServer.getLocalAddress().then((localAddress: socket.NetAddress) => {
  console.info("Get success: " + JSON.stringify(localAddress));
}).catch((err: BusinessError) => {
  console.error("Get failed, error: " + JSON.stringify(err));
})

on('connect')¹⁰⁺

on(type: 'connect', callback: Callback<TLSSocketConnection>): void

Subscribes to TLS socket server connection events. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. connect: connection event.
callback	Callback<TLSSocketConnection>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
  tlsServer.on('connect', (data: socket.TLSSocketConnection) => {
    console.info(JSON.stringify(data));
  });
}).catch((err: BusinessError) => {
  console.error("failed: " + JSON.stringify(err));
});

off('connect')¹⁰⁺

off(type: 'connect', callback?: Callback<TLSSocketConnection>): void

Unsubscribes from connect events of the TLSSocketServer object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. connect: connection event.
callback	Callback<TLSSocketConnection>	No	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

let callback = (data: socket.TLSSocketConnection) => {
  console.info('on connect message: ' + JSON.stringify(data));
}
tlsServer.on('connect', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tlsServer.off('connect', callback);
tlsServer.off('connect');

on('error')¹⁰⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the TLSSocketServer object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed: " + JSON.stringify(err));
});
tlsServer.on('error', (err: BusinessError) => {
  console.error("on error, err:" + JSON.stringify(err))
});

off('error')¹⁰⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the TLSSocketServer object. This API uses an asynchronous callback to return the result.

NOTE This API can be called only after listen is successfully called. You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	No	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

let callback = (err: BusinessError) => {
  console.error("on error, err:" + JSON.stringify(err));
}
tlsServer.on('error', callback);
// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
tlsServer.off('error', callback);
tlsServer.off('error');

close²⁰⁺

close(): Promise<void>

Stops listening for events of the TLSSocketServer object and releases the port bound by listen. This API uses a promise to return the result.

NOTE This API does not close existing connections. To close the connection, call the close API of TLSSocketConnection.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Socket Error Codes and Universal Error Codes.

ID	Error Message
201	Permission denied.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.on('connect', (connection: socket.TLSSocketConnection) => {
  console.info("connection clientId: " + connection.clientId);
  // Logical processing
  tlsServer.close(); // Stop event listening.
  connection.close(); // Close the current connection.
});
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("listen failed: " + err.code);
});

TLSSocketConnection¹⁰⁺

Defines a TLSSocketConnection object, that is, the connection between the TLSSocket client and the server. Before calling TLSSocketConnection APIs, you need to obtain a TLSSocketConnection object.

NOTE The TLSSocket client can call related APIs through the TLSSocketConnection object only after a connection is successfully established between the TLSSocket client and the server.

System capability: SystemCapability.Communication.NetStack

Attributes

Name	Type	Read-Only	Optional	Description
clientId	number	No	No	ID of the connection between the client and TLSSocketServer.

send¹⁰⁺

send(data: string | ArrayBuffer, callback: AsyncCallback<void>): void

Sends a message to the client after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
data	string | ArrayBuffer	Yes	Parameters for sending data over a TLS socket server connection.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303503	An error occurred when writing data on the TLS socket.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.send('Hello, client!', (err: BusinessError) => {
    if (err) {
      console.error('send fail');
      return;
    }
    console.info('send success');
  });
});

send¹⁰⁺

send(data: string | ArrayBuffer): Promise<void>

Sends a message to the server after a TLSSocketServer connection is established. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
data	string | ArrayBuffer	Yes	Parameters for sending data over a TLS socket server connection.

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303503	An error occurred when writing data on the TLS socket.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.send('Hello, client!').then(() => {
    console.info('send success');
  }).catch((err: BusinessError) => {
    console.error('send fail');
  });
});

close¹⁰⁺

close(callback: AsyncCallback<void>): void

Closes a TLSSocketServer connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.close((err: BusinessError) => {
    if (err) {
      console.error('close fail');
      return;
    }
    console.info('close success');
  });
});

close¹⁰⁺

close(): Promise<void>

Closes a TLSSocketServer connection. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<void>	Promise used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303505	An error occurred in the TLS system call.
2303506	Failed to close the TLS connection.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.close().then(() => {
    console.info('close success');
  }).catch((err: BusinessError) => {
    console.error('close fail');
  });
});

getRemoteAddress¹⁰⁺

getRemoteAddress(callback: AsyncCallback<NetAddress>): void

Obtains the remote address of a TLS socket server connection. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<NetAddress>	Yes	Callback used to return the result. If the operation is successful, the remote address is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.getRemoteAddress((err: BusinessError, data: socket.NetAddress) => {
    if (err) {
      console.error('getRemoteAddress fail');
      return;
    }
    console.info('getRemoteAddress success:' + JSON.stringify(data));
  });
});

getRemoteAddress¹⁰⁺

getRemoteAddress(): Promise<NetAddress>

Obtains the remote address of a TLS socket server connection. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303188	Socket operation on non-socket.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.getRemoteAddress().then((data: socket.NetAddress) => {
    console.info('getRemoteAddress success:' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error("failed" + err);
  });
});

getRemoteCertificate¹⁰⁺

getRemoteCertificate(callback: AsyncCallback<X509CertRawData>): void

Obtains the digital certificate of the peer end after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result. It applies only to the scenario where the client sends a certificate to the server.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<X509CertRawData>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { util } from '@kit.ArkTS';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.getRemoteCertificate((err: BusinessError, data: socket.X509CertRawData) => {
    if (err) {
      console.error("getRemoteCertificate callback error: " + err);
    } else {
      const decoder = util.TextDecoder.create();
      const str = decoder.decodeToString(data.data);
      console.info("getRemoteCertificate callback: " + str);
    }
  });
});

getRemoteCertificate¹⁰⁺

getRemoteCertificate():Promise<X509CertRawData>

Obtains the digital certificate of the peer end after a TLSSocketServer connection is established. This API uses a promise to return the result. It applies only to the scenario where the client sends a certificate to the server.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<X509CertRawData>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { util } from '@kit.ArkTS';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.getRemoteCertificate().then((data: socket.X509CertRawData) => {
    const decoder = util.TextDecoder.create();
    const str = decoder.decodeToString(data.data);
    console.info("getRemoteCertificate success: " + str);
  }).catch((err: BusinessError) => {
    console.error("failed" + err);
  });
});

getCipherSuite¹⁰⁺

getCipherSuite(callback: AsyncCallback<Array<string>>): void

Obtains the cipher suite negotiated by both communication parties after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<string>>	Yes	Callback used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2303502	An error occurred when reading data on the TLS socket.
2303505	An error occurred in the TLS system call.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.getCipherSuite((err: BusinessError, data: Array<string>) => {
    if (err) {
      console.error("getCipherSuite callback error = " + err);
    } else {
      console.info("getCipherSuite callback = " + data);
    }
  });
});

getCipherSuite¹⁰⁺

getCipherSuite(): Promise<Array<string>>

Obtains the cipher suite negotiated by both communication parties after a TLSSocketServer connection is established. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<Array<string>>	Promise used to return the result. If the operation fails, an error message is returned.

Error codes

ID	Error Message
2303501	SSL is null.
2303502	An error occurred when reading data on the TLS socket.
2303505	An error occurred in the TLS system call.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.getCipherSuite().then((data: Array<string>) => {
    console.info('getCipherSuite success:' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error("failed" + err);
  });
});

getSignatureAlgorithms¹⁰⁺

getSignatureAlgorithms(callback: AsyncCallback<Array<string>>): void

Obtains the signing algorithm negotiated by both communication parties after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<string>>	Yes	Callback used to return the result.

Error codes

ID	Error Message
401	Parameter error.
2303501	SSL is null.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.getSignatureAlgorithms((err: BusinessError, data: Array<string>) => {
    if (err) {
      console.error("getSignatureAlgorithms callback error = " + err);
    } else {
      console.info("getSignatureAlgorithms callback = " + data);
    }
  });
});

getSignatureAlgorithms¹⁰⁺

getSignatureAlgorithms(): Promise<Array<string>>

Obtains the signing algorithm negotiated by both communication parties after a TLSSocketServer connection is established. This API uses a promise to return the result.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<Array<string>>	Promise used to return the result.

Error codes

ID	Error Message
2303501	SSL is null.
2300002	System internal error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.getSignatureAlgorithms().then((data: Array<string>) => {
    console.info("getSignatureAlgorithms success" + data);
  }).catch((err: BusinessError) => {
    console.error("failed" + err);
  });
});

getLocalAddress¹²⁺

getLocalAddress(): Promise<NetAddress>

Obtains the local socket address of a TLSSocketConnection connection. This API uses a promise to return the result.

NOTE Call this API only after the TLSSocketServer connection is successfully established.

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<NetAddress>	Promise used to return the result.

Error codes

ID	Error Message
2300002	System internal error.
2301009	Bad file descriptor.
2303188	Socket operation on non-socket.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.getLocalAddress().then((localAddress: socket.NetAddress) => {
    console.info("Family IP Port: " + JSON.stringify(localAddress));
  }).catch((err: BusinessError) => {
    console.error("TLS Client Get Family IP Port failed, error: " + JSON.stringify(err));
  })
});

getSocketFd²³⁺

getSocketFd(): Promise<number>

Obtains the file descriptor of a TLSSocketConnection connection. This API uses a promise to return the result.

NOTE

• Call this API only after the TLSSocketServer connection is successfully established.
• This API returns -1 in abnormal cases such as disconnection and socket closed (for example, after the close API is called).
• The lifecycle of the file descriptor is managed by the system. The application can use the close method to close the socket connection, instead of directly operating the file descriptor.

Required permissions: ohos.permission.INTERNET

System capability: SystemCapability.Communication.NetStack

Return value

Type	Description
Promise<number>	Promise used to return the socket file descriptor.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
201	Permission denied.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen success");
  tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
    client.getSocketFd().then((fd: number) => {
      console.info(`Socket FD: ${fd}`);
    }).catch((err: BusinessError) => {
      console.error(`getSocketFd fail: ${err.message}, errorCode: ${err.code}`);
    })
  });
}).catch((err: BusinessError) => {
  console.error(`listen failed: ${JSON.stringify(err)}`);
});

on('message')¹⁰⁺

on(type: 'message', callback: Callback<SocketMessageInfo>): void

Subscribes to message events of the TLSSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	Yes	Callback used to return the result. If the operation is successful, the TLS socket connection information is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

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

off('message')¹⁰⁺

off(type: 'message', callback?: Callback<SocketMessageInfo>): void

Unsubscribes from message events of the TLSSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. message: message receiving event.
callback	Callback<SocketMessageInfo>	No	Callback used to return the result. If the operation is successful, the TLS socket connection information is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

let callback = (value: socket.SocketMessageInfo) => {
  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.info('on message message: ' + JSON.stringify(messageView));
  console.info('remoteInfo: ' + JSON.stringify(value.remoteInfo));
}
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.on('message', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  client.off('message', callback);
  client.off('message');
});

on('close')¹⁰⁺

on(type: 'close', callback: Callback<void>): void

Subscribes to close events of the TLSSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. close: close event.
callback	Callback<void>	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tlsServer: socket.TLSSocketServer = socket.constructTLSSocketServerInstance();
let netAddress: socket.NetAddress = {
  address: '192.168.xx.xxx',
  port: 8080
}
let tlsSecureOptions: socket.TLSSecureOptions = {
  key: "xxxx",
  cert: ["xxxx"],
  ca: ["xxxx"],
  password: "xxxx",
  protocols: socket.Protocol.TLSv12,
  useRemoteCipherPrefer: true,
  signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
  cipherSuite: "AES256-SHA256"
}
let tlsConnectOptions: socket.TLSConnectOptions = {
  address: netAddress,
  secureOptions: tlsSecureOptions,
  ALPNProtocols: ["spdy/1", "http/1.1"]
}
tlsServer.listen(tlsConnectOptions).then(() => {
  console.info("listen callback success");
}).catch((err: BusinessError) => {
  console.error("failed" + err);
});
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.on('close', () => {
    console.info("on close success")
  });
});

off('close')¹⁰⁺

off(type: 'close', callback?: Callback<void>): void

Unsubscribes from close events of the TLSSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. close: close event.
callback	Callback<void>	No	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

let callback = () => {
  console.info("on close success");
}
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.on('close', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  client.off('close', callback);
  client.off('close');
});

on('error')¹⁰⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to error events of the TLSSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	Yes	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.on('error', (err: BusinessError) => {
    console.error("on error, err:" + JSON.stringify(err))
  });
});

off('error')¹⁰⁺

off(type: 'error', callback?: ErrorCallback): void

Unsubscribes from error events of the TLSSocketConnection object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Communication.NetStack

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. error: error event.
callback	ErrorCallback	No	Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.

Error codes

ID	Error Message
401	Parameter error.

Example

import { socket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

let callback = (err: BusinessError) => {
  console.error("on error, err:" + JSON.stringify(err));
}
tlsServer.on('connect', (client: socket.TLSSocketConnection) => {
  client.on('error', callback);
  // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events.
  client.off('error', callback);
  client.off('error');
});