<br />

<br />

## Description

Use the `chrome.sockets.tcp` API to send and receive data over the network using TCP connections. This API supersedes the TCP functionality previously found in the `chrome.socket` API.

<br />

<br />

<br />

<br />

## Manifest

The following keys must be declared [in the manifest](https://developer.chrome.com/docs/extensions/mv3/manifest) to use this API.
`"sockets"`  

<br />

<br />

## Types

### CreateInfo

#### Properties

- socketId number

  The ID of the newly created socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the deprecated `[`socket`](../socket/)` API.

### DnsQueryType

Chrome 103+

DNS resolution preferences. The default is `any` and uses the current OS config which may return IPv4 or IPv6. `ipv4` forces IPv4, and `ipv6` forces IPv6.

#### Enum

"any"   
"ipv4"   
"ipv6"   

<br />

### ReceiveErrorInfo

#### Properties

- resultCode number

  The result code returned from the underlying network call.
- socketId number

  The socket identifier.

### ReceiveInfo

#### Properties

- data ArrayBuffer

  The data received, with a maxium size of `bufferSize`.
- socketId number

  The socket identifier.

### SecureOptions

#### Properties

- tlsVersion [TLSVersionConstraints](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-TLSVersionConstraints) optional

### SendInfo

#### Properties

- bytesSent number optional

  The number of bytes sent (if result == 0)
- resultCode number

  The result code returned from the underlying network call. A negative value indicates an error.

### SocketInfo

#### Properties

- bufferSize number optional

  The size of the buffer used to receive data. If no buffer size has been specified explicitly, the value is not provided.
- connected boolean

  Flag indicating whether the socket is connected to a remote peer.
- localAddress string optional

  If the underlying socket is connected, contains its local IPv4/6 address.
- localPort number optional

  If the underlying socket is connected, contains its local port.
- name string optional

  Application-defined string associated with the socket.
- paused boolean

  Flag indicating whether a connected socket blocks its peer from sending more data (see `setPaused`).
- peerAddress string optional

  If the underlying socket is connected, contains the peer/ IPv4/6 address.
- peerPort number optional

  If the underlying socket is connected, contains the peer port.
- persistent boolean

  Flag indicating whether the socket is left open when the application is suspended (see `SocketProperties.persistent`).
- socketId number

  The socket identifier.

### SocketProperties

#### Properties

- bufferSize number optional

  The size of the buffer used to receive data. The default value is 4096.
- name string optional

  An application-defined string associated with the socket.
- persistent boolean optional

  Flag indicating if the socket is left open when the event page of the application is unloaded (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is "false". When the application is loaded, any sockets previously opened with persistent=true can be fetched with `getSockets`.

### TLSVersionConstraints

#### Properties

- max string optional
- min string optional

  The minimum and maximum acceptable versions of TLS. Supported values are `tls1.2` or `tls1.3`.

  The values `tls1` and `tls1.1` are no longer supported. If `min` is set to one of these values, it will be silently clamped to `tls1.2`. If `max` is set to one of those values, or any other unrecognized value, it will be silently ignored.

## Methods

### close()

Promise

```typescript
chrome.sockets.tcp.close(
  socketId: number,
  callback?: function,
): Promise<void>
```

Closes the socket and releases the address/port the socket is bound to. Each socket created should be closed after use. The socket id is no no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked.

#### Parameters

- socketId number

  The socket identifier.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  () => void
  ```

  <br />

#### Returns

- Promise\<void\>
  Chrome 121+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### connect()

```typescript
chrome.sockets.tcp.connect(
  socketId: number,
  peerAddress: string,
  peerPort: number,
  dnsQueryType?: DnsQueryType,
  callback: function,
): void
```

Connects the socket to a remote machine. When the `connect` operation completes successfully, `onReceive` events are raised when data is received from the peer. If a network error occurs while the runtime is receiving packets, a `onReceiveError` event is raised, at which point no more `onReceive` event will be raised for this socket until the `resume` method is called.

#### Parameters

- socketId number

  The socket identifier.
- peerAddress string

  The address of the remote machine. DNS name, IPv4 and IPv6 formats are supported.
- peerPort number

  The port of the remote machine.
- dnsQueryType [DnsQueryType](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-DnsQueryType) optional
  Chrome 103+

  The address resolution preference.
- callback function


  The `callback` parameter looks like:

  ```typescript
  (result: number) => void
  ```

  <br />

  - result number

    The result code returned from the underlying network call. A negative value indicates an error.

### create()

Promise

```typescript
chrome.sockets.tcp.create(
  properties?: SocketProperties,
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-CreateInfo>
```

Creates a TCP socket.

#### Parameters

- properties [SocketProperties](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SocketProperties) optional

  The socket properties (optional).
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (createInfo: CreateInfo) => void
  ```

  <br />

  - createInfo [CreateInfo](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-CreateInfo)

    The result of the socket creation.

#### Returns

- Promise\<[CreateInfo](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-CreateInfo)\>
  Chrome 121+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### disconnect()

Promise

```typescript
chrome.sockets.tcp.disconnect(
  socketId: number,
  callback?: function,
): Promise<void>
```

Disconnects the socket.

#### Parameters

- socketId number

  The socket identifier.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  () => void
  ```

  <br />

#### Returns

- Promise\<void\>
  Chrome 121+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### getInfo()

Promise

```typescript
chrome.sockets.tcp.getInfo(
  socketId: number,
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SocketInfo>
```

Retrieves the state of the given socket.

#### Parameters

- socketId number

  The socket identifier.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (socketInfo: SocketInfo) => void
  ```

  <br />

  - socketInfo [SocketInfo](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SocketInfo)

    Object containing the socket information.

#### Returns

- Promise\<[SocketInfo](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SocketInfo)\>
  Chrome 121+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### getSockets()

Promise

```typescript
chrome.sockets.tcp.getSockets(
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SocketInfo[]>
```

Retrieves the list of currently opened sockets owned by the application.

#### Parameters

- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (socketInfos: SocketInfo[]) => void
  ```

  <br />

  - socketInfos [SocketInfo](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SocketInfo)\[\]

    Array of object containing socket information.

#### Returns

- Promise\<[SocketInfo](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SocketInfo)\[\]\>
  Chrome 121+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### secure()

```typescript
chrome.sockets.tcp.secure(
  socketId: number,
  options?: SecureOptions,
  callback: function,
): void
```

Start a TLS client connection over the connected TCP client socket.

#### Parameters

- socketId number

  The existing, connected socket to use.
- options [SecureOptions](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SecureOptions) optional

  Constraints and parameters for the TLS connection.
- callback function


  The `callback` parameter looks like:

  ```typescript
  (result: number) => void
  ```

  <br />

  - result number

### send()

```typescript
chrome.sockets.tcp.send(
  socketId: number,
  data: ArrayBuffer,
  callback: function,
): void
```

Sends data on the given TCP socket.

#### Parameters

- socketId number

  The socket identifier.
- data ArrayBuffer

  The data to send.
- callback function


  The `callback` parameter looks like:

  ```typescript
  (sendInfo: SendInfo) => void
  ```

  <br />

  - sendInfo [SendInfo](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SendInfo)

    Result of the `send` method.

### setKeepAlive()

```typescript
chrome.sockets.tcp.setKeepAlive(
  socketId: number,
  enable: boolean,
  delay?: number,
  callback: function,
): void
```

Enables or disables the keep-alive functionality for a TCP connection.

#### Parameters

- socketId number

  The socket identifier.
- enable boolean

  If true, enable keep-alive functionality.
- delay number optional

  Set the delay seconds between the last data packet received and the first keepalive probe. Default is 0.
- callback function


  The `callback` parameter looks like:

  ```typescript
  (result: number) => void
  ```

  <br />

  - result number

    The result code returned from the underlying network call. A negative value indicates an error.

### setNoDelay()

```typescript
chrome.sockets.tcp.setNoDelay(
  socketId: number,
  noDelay: boolean,
  callback: function,
): void
```

Sets or clears `TCP_NODELAY` for a TCP connection. Nagle's algorithm will be disabled when `TCP_NODELAY` is set.

#### Parameters

- socketId number

  The socket identifier.
- noDelay boolean

  If true, disables Nagle's algorithm.
- callback function


  The `callback` parameter looks like:

  ```typescript
  (result: number) => void
  ```

  <br />

  - result number

    The result code returned from the underlying network call. A negative value indicates an error.

### setPaused()

Promise

```typescript
chrome.sockets.tcp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
): Promise<void>
```

Enables or disables the application from receiving messages from its peer. The default value is "false". Pausing a socket is typically used by an application to throttle data sent by its peer. When a socket is paused, no `onReceive` event is raised. When a socket is connected and un-paused, `onReceive` events are raised again when messages are received.

#### Parameters

- socketId number
- paused boolean
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  () => void
  ```

  <br />

#### Returns

- Promise\<void\>
  Chrome 121+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### update()

Promise

```typescript
chrome.sockets.tcp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
): Promise<void>
```

Updates the socket properties.

#### Parameters

- socketId number

  The socket identifier.
- properties [SocketProperties](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-SocketProperties)

  The properties to update.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  () => void
  ```

  <br />

#### Returns

- Promise\<void\>
  Chrome 121+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

## Events

### onReceive

```typescript
chrome.sockets.tcp.onReceive.addListener(
  callback: function,
)
```

Event raised when data has been received for a given socket.

#### Parameters

- callback function


  The `callback` parameter looks like:

  ```typescript
  (info: ReceiveInfo) => void
  ```

  <br />

  - info [ReceiveInfo](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-ReceiveInfo)

### onReceiveError

```typescript
chrome.sockets.tcp.onReceiveError.addListener(
  callback: function,
)
```

Event raised when a network error occurred while the runtime was waiting for data on the socket address and port. Once this event is raised, the socket is set to `paused` and no more `onReceive` events are raised for this socket.

#### Parameters

- callback function


  The `callback` parameter looks like:

  ```typescript
  (info: ReceiveErrorInfo) => void
  ```

  <br />

  - info [ReceiveErrorInfo](https://developer.chrome.com/docs/apps/reference/sockets/tcp#type-ReceiveErrorInfo)

<br />