chrome.sockets.udp

Описание

Используйте chrome.sockets.udp API, чтобы отправлять и получать данные по сети с помощью UDP-подключений. Этот API заменяет функции UDP, которые ранее были доступны в API socket.

Манифест

Чтобы использовать этот API, в манифесте нужно объявить следующие ключи:

"sockets"

Типы

CreateInfo

Свойства

  • socketId

    число

    Идентификатор созданного сокета. Обратите внимание, что идентификаторы сокетов, созданные с помощью этого API, несовместимы с идентификаторами сокетов, созданными с помощью других API, например устаревшего API [socket](../socket/).

DnsQueryType

Chrome 103 и более поздних версий;

Настройки DNS-преобразования. По умолчанию используется значение any и текущая конфигурация ОС, которая может возвращать IPv4 или IPv6. ipv4 принудительно использует IPv4, а ipv6 – IPv6.

Перечисление

"any"

"ipv4"

"ipv6"

ReceiveErrorInfo

Свойства

  • resultCode

    число

    Код результата, возвращенный базовым вызовом recvfrom().

  • socketId

    число

    Идентификатор сокета.

ReceiveInfo

Свойства

  • делал.

    ArrayBuffer

    Содержимое пакета UDP (усеченное до текущего размера буфера).

  • remoteAddress

    string

    Адрес хоста, от которого поступает пакет.

  • remotePort

    число

    Порт хоста, с которого поступает пакет.

  • socketId

    число

    Идентификатор сокета.

SendInfo

Свойства

  • bytesSent

    number (необязательно)

    Количество отправленных байтов (если result == 0).

  • resultCode

    число

    Код результата, возвращенный из базового сетевого вызова. Отрицательное значение указывает на ошибку.

SocketInfo

Свойства

  • bufferSize

    number (необязательно)

    Размер буфера, используемого для получения данных. Если размер буфера не указан явно, значение не предоставляется.

  • localAddress

    Строка (необязательно)

    Если базовый сокет привязан, содержит его локальный адрес IPv4/6.

  • localPort

    number (необязательно)

    Если базовый сокет привязан, содержит его локальный порт.

  • name

    Строка (необязательно)

    Строка, определенная приложением и связанная с сокетом.

  • приостановлено

    Логическое значение

    Флаг, указывающий, заблокирован ли сокет для запуска событий onReceive.

  • постоянный

    Логическое значение

    Флаг, указывающий, остается ли сокет открытым, когда приложение приостановлено (см. SocketProperties.persistent).

  • socketId

    число

    Идентификатор сокета.

SocketProperties

Свойства

  • bufferSize

    number (необязательно)

    Размер буфера, используемого для получения данных. Если буфер слишком мал для приема пакета UDP, данные теряются. Значение по умолчанию – 4096.

  • name

    Строка (необязательно)

    Определенная приложением строка, связанная с сокетом.

  • постоянный

    Логическое значение (необязательно)

    Флаг, указывающий, остается ли сокет открытым, когда страница событий приложения выгружается (см. раздел Управление жизненным циклом приложения). Значение по умолчанию – false. При загрузке приложения любые сокеты, ранее открытые с параметром persistent=true, можно получить с помощью getSockets.

Методы

bind()

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

Привязывает локальный адрес и порт к сокету. Для клиентского сокета рекомендуется использовать порт 0, чтобы платформа могла выбрать свободный порт.

После успешного завершения операции bind при поступлении UDP-пакетов на указанный адрес или порт генерируются события onReceive (если сокет не приостановлен).

Параметры

  • socketId

    число

    Идентификатор сокета.

  • Обращаться (к определенному вопросу)

    string

    Адрес локального компьютера. Поддерживаются DNS-имена, а также форматы IPv4 и IPv6. Чтобы принимать пакеты от всех доступных локальных сетевых интерфейсов, используйте значение "0.0.0.0".

  • порт

    число

    Порт локального компьютера. Чтобы привязать к свободному порту, укажите "0".

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (result: number) => void

    • Результат

      число

      Код результата, возвращенный из базового сетевого вызова. Отрицательное значение указывает на ошибку.

close()

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

Закрывает сокет и освобождает адрес/порт, к которому он привязан. Каждый созданный сокет должен быть закрыт после использования. Идентификатор сокета перестает быть действительным сразу после вызова функции. Однако сокет гарантированно закрывается только при вызове обратного вызова.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 121 и более поздних версий

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

create()

Promise 
chrome.sockets.udp.create(
  properties?: SocketProperties,
  callback?: function,
): Promise<CreateInfo>

Создает сокет UDP с заданными свойствами.

Параметры

  • объекты

    SocketProperties необязательный

    Свойства сокета (необязательно).

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      Результат создания сокета.

Возвраты

  • Promise<CreateInfo>

    Chrome 121 и более поздних версий

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getInfo()

Promise 
chrome.sockets.udp.getInfo(
  socketId: number,
  callback?: function,
): Promise<SocketInfo>

Получает состояние указанного сокета.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      Объект, содержащий информацию о сокете.

Возвраты

  • Promise<SocketInfo>

    Chrome 121 и более поздних версий

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getJoinedGroups()

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

Получает адреса групп многоадресной рассылки, к которым в данный момент подключен сокет.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (groups: string[]) => void

    • группы

      string[]

      Массив групп, к которым присоединился сокет.

Возвраты

  • Promise<string[]>

    Chrome 121 и более поздних версий

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getSockets()

Promise 
chrome.sockets.udp.getSockets(
  callback?: function,
): Promise<SocketInfo[]>

Получает список открытых сокетов, принадлежащих приложению.

Параметры

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

      Массив объектов, содержащих информацию о сокетах.

Возвраты

  • Promise<SocketInfo[]>

    Chrome 121 и более поздних версий

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

joinGroup()

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

Присоединяется к группе многоадресной рассылки и начинает получать пакеты от этой группы. Перед вызовом этого метода сокет должен быть привязан к локальному порту.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • Обращаться (к определенному вопросу)

    string

    Адрес группы, к которой нужно присоединиться. Доменные имена не поддерживаются.

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (result: number) => void

    • Результат

      число

      Код результата, возвращенный из базового сетевого вызова. Отрицательное значение указывает на ошибку.

leaveGroup()

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

Покидает группу многоадресной рассылки, к которой ранее присоединился с помощью joinGroup. Вызывать этот метод нужно, только если вы планируете использовать сокет в дальнейшем. В противном случае операционная система автоматически выполнит эту операцию при закрытии сокета.

После выхода из группы маршрутизатор перестанет отправлять многоадресные датаграммы на локальный хост, если к группе не подключен другой процесс на хосте.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • Обращаться (к определенному вопросу)

    string

    Адрес группы, которую нужно покинуть. Доменные имена не поддерживаются.

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (result: number) => void

    • Результат

      число

      Код результата, возвращенный из базового сетевого вызова. Отрицательное значение указывает на ошибку.

send()

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

Отправляет данные по указанному сокету на указанный адрес и порт. Перед вызовом этого метода сокет должен быть привязан к локальному порту.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • делал.

    ArrayBuffer

    Данные для отправки.

  • Обращаться (к определенному вопросу)

    string

    Адрес удаленного компьютера.

  • порт

    число

    Порт удаленного компьютера.

  • dnsQueryType

    DnsQueryType необязательный

    Chrome 103 и более поздних версий;

    Предпочтительный способ разрешения адресов.

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      Результат метода send.

setBroadcast()

Chrome 44 и более поздних версий; 
chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
): void

Включает или отключает широковещательные пакеты в этом сокете.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • включено

    Логическое значение

    true, чтобы включить широковещательные пакеты, и false, чтобы отключить их.

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (result: number) => void

    • Результат

      число

      Код результата, возвращенный из базового сетевого вызова.

setMulticastLoopbackMode()

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

Определяет, будут ли пакеты многоадресной рассылки, отправленные с хоста в группу многоадресной рассылки, возвращаться на хост.

Примечание. Поведение setMulticastLoopbackMode в Windows и Unix-подобных системах немного различается. Несоответствие возникает, только если на одном хосте есть несколько приложений, присоединенных к одной группе многоадресной рассылки, но имеющих разные настройки режима обратной связи многоадресной рассылки. В Windows приложения с отключенной обратной связью не будут ПОЛУЧАТЬ пакеты обратной связи, а в Unix-подобных системах – не будут ОТПРАВЛЯТЬ их другим приложениям на том же хосте. Подробнее: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2.

Для вызова этого метода не требуются разрешения на многоадресную рассылку.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • включено

    Логическое значение

    Укажите, нужно ли включить режим обратной связи.

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (result: number) => void

    • Результат

      число

      Код результата, возвращенный из базового сетевого вызова. Отрицательное значение указывает на ошибку.

setMulticastTimeToLive()

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

Задает время жизни пакетов, отправляемых в группу многоадресной рассылки.

Для вызова этого метода не требуются разрешения на многоадресную рассылку.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • ttl

    число

    Значение времени жизни.

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (result: number) => void

    • Результат

      число

      Код результата, возвращенный из базового сетевого вызова. Отрицательное значение указывает на ошибку.

setPaused()

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

Приостанавливает или возобновляет работу сокета. Приостановленный сокет не может активировать события onReceive.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • приостановлено

    Логическое значение

    Пометка, указывающая, нужно ли приостановить или возобновить показ.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 121 и более поздних версий

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

update()

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

Обновляет свойства сокета.

Параметры

  • socketId

    число

    Идентификатор сокета.

  • объекты

    SocketProperties

    Свойства, которые нужно обновить.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 121 и более поздних версий

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onReceive

chrome.sockets.udp.onReceive.addListener(
  callback: function,
)

Событие, которое происходит при получении UDP-пакета для указанного сокета.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (info: ReceiveInfo) => void

onReceiveError

chrome.sockets.udp.onReceiveError.addListener(
  callback: function,
)

Событие возникает, когда при ожидании данных на адресе сокета и порте происходит ошибка сети. После этого сокет приостанавливается и события onReceive для него не генерируются, пока он не будет возобновлен.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (info: ReceiveErrorInfo) => void