<br />

<br />

## Description

Use the `chrome.sockets.udp` API to send and receive data over the network using UDP connections. This API supersedes the UDP functionality previously found in the "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 recvfrom() call.
- socketId number

  The socket ID.

### ReceiveInfo

#### Properties

- data ArrayBuffer

  The UDP packet content (truncated to the current buffer size).
- remoteAddress string

  The address of the host the packet comes from.
- remotePort number

  The port of the host the packet comes from.
- socketId number

  The socket ID.

### 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.
- localAddress string optional

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

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

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

  Flag indicating whether the socket is blocked from firing onReceive events.
- 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. If the buffer is too small to receive the UDP packet, data is lost. 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`.

## Methods

### bind()

```typescript
chrome.sockets.udp.bind(
  socketId: number,
  address: string,
  port: number,
  callback: function,
): void
```

Binds the local address and port for the socket. For a client socket, it is recommended to use port 0 to let the platform pick a free port.

Once the `bind` operation completes successfully, `onReceive` events are raised when UDP packets arrive on the address/port specified -- unless the socket is paused.

#### Parameters

- socketId number

  The socket ID.
- address string

  The address of the local machine. DNS name, IPv4 and IPv6 formats are supported. Use "0.0.0.0" to accept packets from all local available network interfaces.
- port number

  The port of the local machine. Use "0" to bind to a free port.
- 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.

### close()

Promise

```typescript
chrome.sockets.udp.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 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 ID.
- 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.

### create()

Promise

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

Creates a UDP socket with the given properties.

#### Parameters

- properties [SocketProperties](https://developer.chrome.com/docs/apps/reference/sockets/udp#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/udp#type-CreateInfo)

    The result of the socket creation.

#### Returns

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


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

### getInfo()

Promise

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

Retrieves the state of the given socket.

#### Parameters

- socketId number

  The socket ID.
- callback function optional


  The `callback` parameter looks like:

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

  <br />

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

    Object containing the socket information.

#### Returns

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


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

### getJoinedGroups()

Promise

```typescript
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
): Promise<string[]>
```

Gets the multicast group addresses the socket is currently joined to.

#### Parameters

- socketId number

  The socket ID.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (groups: string[]) => void
  ```

  <br />

  - groups string\[\]

    Array of groups the socket joined.

#### Returns

- Promise\<string\[\]\>
  Chrome 121+


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

### getSockets()

Promise

```typescript
chrome.sockets.udp.getSockets(
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/sockets/udp#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/udp#type-SocketInfo)\[\]

    Array of object containing socket information.

#### Returns

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


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

### joinGroup()

```typescript
chrome.sockets.udp.joinGroup(
  socketId: number,
  address: string,
  callback: function,
): void
```

Joins the multicast group and starts to receive packets from that group. The socket must be bound to a local port before calling this method.

#### Parameters

- socketId number

  The socket ID.
- address string

  The group address to join. Domain names are not supported.
- 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.

### leaveGroup()

```typescript
chrome.sockets.udp.leaveGroup(
  socketId: number,
  address: string,
  callback: function,
): void
```

Leaves the multicast group previously joined using `joinGroup`. This is only necessary to call if you plan to keep using the socketafterwards, since it will be done automatically by the OS when the socket is closed.

Leaving the group will prevent the router from sending multicast datagrams to the local host, presuming no other process on the host is still joined to the group.

#### Parameters

- socketId number

  The socket ID.
- address string

  The group address to leave. Domain names are not supported.
- 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.

### send()

```typescript
chrome.sockets.udp.send(
  socketId: number,
  data: ArrayBuffer,
  address: string,
  port: number,
  dnsQueryType?: DnsQueryType,
  callback: function,
): void
```

Sends data on the given socket to the given address and port. The socket must be bound to a local port before calling this method.

#### Parameters

- socketId number

  The socket ID.
- data ArrayBuffer

  The data to send.
- address string

  The address of the remote machine.
- port number

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

  The address resolution preference.
- callback function


  The `callback` parameter looks like:

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

  <br />

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

    Result of the `send` method.

### setBroadcast()

Chrome 44+

```typescript
chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
): void
```

Enables or disables broadcast packets on this socket.

#### Parameters

- socketId number

  The socket ID.
- enabled boolean

  `true` to enable broadcast packets, `false` to disable them.
- callback function


  The `callback` parameter looks like:

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

  <br />

  - result number

    The result code returned from the underlying network call.

### setMulticastLoopbackMode()

```typescript
chrome.sockets.udp.setMulticastLoopbackMode(
  socketId: number,
  enabled: boolean,
  callback: function,
): void
```

Sets whether multicast packets sent from the host to the multicast group will be looped back to the host.

Note: the behavior of `setMulticastLoopbackMode` is slightly different between Windows and Unix-like systems. The inconsistency happens only when there is more than one application on the same host joined to the same multicast group while having different settings on multicast loopback mode. On Windows, the applications with loopback off will not RECEIVE the loopback packets; while on Unix-like systems, the applications with loopback off will not SEND the loopback packets to other applications on the same host. See MSDN: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

Calling this method does not require multicast permissions.

#### Parameters

- socketId number

  The socket ID.
- enabled boolean

  Indicate whether to enable loopback mode.
- 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.

### setMulticastTimeToLive()

```typescript
chrome.sockets.udp.setMulticastTimeToLive(
  socketId: number,
  ttl: number,
  callback: function,
): void
```

Sets the time-to-live of multicast packets sent to the multicast group.

Calling this method does not require multicast permissions.

#### Parameters

- socketId number

  The socket ID.
- ttl number

  The time-to-live value.
- 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.udp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
): Promise<void>
```

Pauses or unpauses a socket. A paused socket is blocked from firing `onReceive` events.

#### Parameters

- socketId number

  The socket ID.
- paused boolean

  Flag to indicate whether to pause or unpause.
- 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.udp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
): Promise<void>
```

Updates the socket properties.

#### Parameters

- socketId number

  The socket ID.
- properties [SocketProperties](https://developer.chrome.com/docs/apps/reference/sockets/udp#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.udp.onReceive.addListener(
  callback: function,
)
```

Event raised when a UDP packet has been received for the 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/udp#type-ReceiveInfo)

### onReceiveError

```typescript
chrome.sockets.udp.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 paused and no more `onReceive` events will be raised for this socket until the socket is resumed.

#### Parameters

- callback function


  The `callback` parameter looks like:

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

  <br />

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

<br />