chrome.sockets.udp

Description

Utilisez l'API chrome.sockets.udp pour envoyer et recevoir des données sur le réseau à l'aide de connexions UDP. Cette API remplace la fonctionnalité UDP précédemment disponible dans l'API "socket".

Fichier manifeste

Les clés suivantes doivent être déclarées dans le fichier manifeste pour utiliser cette API.

"sockets"

Types

CreateInfo

Propriétés

  • socketId

    nombre

    ID du socket nouvellement créé. Notez que les ID de socket créés à partir de cette API ne sont pas compatibles avec les ID de socket créés à partir d'autres API, telles que l'API [socket](../socket/) obsolète.

DnsQueryType

Chrome 103 ou version ultérieure

Préférences de résolution DNS. La valeur par défaut est any et utilise la configuration d'OS actuelle, qui peut renvoyer une adresse IPv4 ou IPv6. ipv4 force l'utilisation d'IPv4, et ipv6 force l'utilisation d'IPv6.

Énumération

"any"

"ipv4"

"ipv6"

ReceiveErrorInfo

Propriétés

  • resultCode

    nombre

    Code de résultat renvoyé par l'appel recvfrom() sous-jacent.

  • socketId

    nombre

    ID du socket.

ReceiveInfo

Propriétés

  • données

    ArrayBuffer

    Le contenu du paquet UDP (tronqué à la taille actuelle de la mémoire tampon).

  • remoteAddress

    chaîne

    Adresse de l'hôte d'où provient le paquet.

  • remotePort

    nombre

    Port de l'hôte d'où provient le paquet.

  • socketId

    nombre

    ID du socket.

SendInfo

Propriétés

  • bytesSent

    number facultatif

    Nombre d'octets envoyés (si result == 0)

  • resultCode

    nombre

    Code de résultat renvoyé par l'appel réseau sous-jacent. Une valeur négative indique une erreur.

SocketInfo

Propriétés

  • bufferSize

    number facultatif

    Taille de la mémoire tampon utilisée pour recevoir les données. Si aucune taille de mémoire tampon n'a été explicitement spécifiée, la valeur n'est pas fournie.

  • localAddress

    chaîne facultatif

    Si le socket sous-jacent est lié, contient son adresse IPv4/6 locale.

  • localPort

    number facultatif

    Si le socket sous-jacent est lié, contient son port local.

  • nom

    chaîne facultatif

    Chaîne définie par l'application associée au socket.

  • mis en veille

    booléen

    Indicateur signalant si le socket est bloqué et ne peut pas déclencher d'événements onReceive.

  • persistant

    booléen

    Indicateur précisant si le socket reste ouvert lorsque l'application est suspendue (voir SocketProperties.persistent).

  • socketId

    nombre

    Identifiant du socket.

SocketProperties

Propriétés

  • bufferSize

    number facultatif

    Taille de la mémoire tampon utilisée pour recevoir les données. Si la mémoire tampon est trop petite pour recevoir le paquet UDP, les données sont perdues. La valeur par défaut est 4096.

  • nom

    chaîne facultatif

    Chaîne définie par l'application associée au socket.

  • persistant

    boolean facultatif

    Indicateur signalant si le socket reste ouvert lorsque la page d'événement de l'application est déchargée (voir Gérer le cycle de vie de l'application). La valeur par défaut est "false". Lorsque l'application est chargée, tous les sockets précédemment ouverts avec persistent=true peuvent être récupérés avec getSockets.

Méthodes

bind()

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

Lie l'adresse et le port locaux pour le socket. Pour un socket client, il est recommandé d'utiliser le port 0 pour laisser la plate-forme choisir un port libre.

Une fois l'opération bind terminée, les événements onReceive sont déclenchés lorsque des paquets UDP arrivent à l'adresse/au port spécifié, sauf si le socket est mis en pause.

Paramètres

  • socketId

    nombre

    ID du socket.

  • adresse

    chaîne

    Adresse de la machine locale. Les formats de nom DNS, IPv4 et IPv6 sont acceptés. Utilisez "0.0.0.0" pour accepter les paquets de toutes les interfaces réseau locales disponibles.

  • port

    nombre

    Port de la machine locale. Utilisez "0" pour lier à un port libre.

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (result: number) => void

    • résultat

      nombre

      Code de résultat renvoyé par l'appel réseau sous-jacent. Une valeur négative indique une erreur.

close()

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

Ferme le socket et libère l'adresse/le port auquel le socket est lié. Chaque socket créé doit être fermé après utilisation. L'ID de socket n'est plus valide dès que la fonction est appelée. Toutefois, la fermeture du socket n'est garantie que lorsque le rappel est appelé.

Paramètres

  • socketId

    nombre

    ID du socket.

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 121 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

create()

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

Crée un socket UDP avec les propriétés données.

Paramètres

  • propriétés

    SocketProperties facultatif

    Propriétés du socket (facultatif).

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      Résultat de la création du socket.

Renvoie

  • Promise<CreateInfo>

    Chrome 121 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getInfo()

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

Récupère l'état du socket donné.

Paramètres

  • socketId

    nombre

    ID du socket.

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      Objet contenant les informations sur le socket.

Renvoie

  • Promise<SocketInfo>

    Chrome 121 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getJoinedGroups()

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

Récupère les adresses de groupe multicast auxquelles le socket est actuellement associé.

Paramètres

  • socketId

    nombre

    ID du socket.

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (groups: string[]) => void

    • groupes

      chaîne[]

      Tableau des groupes que le socket a rejoints.

Renvoie

  • Promise<string[]>

    Chrome 121 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getSockets()

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

Récupère la liste des sockets actuellement ouverts appartenant à l'application.

Paramètres

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

      Tableau d'objets contenant des informations sur les sockets.

Renvoie

  • Promise<SocketInfo[]>

    Chrome 121 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

joinGroup()

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

Rejoint le groupe multicast et commence à recevoir des paquets de ce groupe. Le socket doit être lié à un port local avant d'appeler cette méthode.

Paramètres

  • socketId

    nombre

    ID du socket.

  • adresse

    chaîne

    Adresse du groupe à rejoindre. Les noms de domaine ne sont pas acceptés.

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (result: number) => void

    • résultat

      nombre

      Code de résultat renvoyé par l'appel réseau sous-jacent. Une valeur négative indique une erreur.

leaveGroup()

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

Quitte le groupe multicast précédemment rejoint à l'aide de joinGroup. Vous ne devez l'appeler que si vous prévoyez de continuer à utiliser le socket par la suite, car l'OS l'effectuera automatiquement lorsque le socket sera fermé.

Le fait de quitter le groupe empêche le routeur d'envoyer des datagrammes multicast à l'hôte local, à condition qu'aucun autre processus de l'hôte ne soit encore membre du groupe.

Paramètres

  • socketId

    nombre

    ID du socket.

  • adresse

    chaîne

    Adresse du groupe à quitter. Les noms de domaine ne sont pas acceptés.

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (result: number) => void

    • résultat

      nombre

      Code de résultat renvoyé par l'appel réseau sous-jacent. Une valeur négative indique une erreur.

send()

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

Envoie des données sur le socket donné à l'adresse et au port spécifiés. Le socket doit être lié à un port local avant d'appeler cette méthode.

Paramètres

  • socketId

    nombre

    ID du socket.

  • données

    ArrayBuffer

    Données à envoyer.

  • adresse

    chaîne

    Adresse de la machine distante.

  • port

    nombre

    Port de la machine distante.

  • dnsQueryType

    DnsQueryType facultatif

    Chrome 103 ou version ultérieure

    Préférence de résolution d'adresse.

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      Résultat de la méthode send.

setBroadcast()

Chrome 44 ou version ultérieure 
chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
): void

Active ou désactive les paquets de diffusion sur ce socket.

Paramètres

  • socketId

    nombre

    ID du socket.

  • activé

    booléen

    true pour activer les paquets de diffusion, false pour les désactiver.

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (result: number) => void

    • résultat

      nombre

      Code de résultat renvoyé par l'appel réseau sous-jacent.

setMulticastLoopbackMode()

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

Indique si les paquets multicast envoyés de l'hôte au groupe multicast seront renvoyés à l'hôte.

Remarque : Le comportement de setMulticastLoopbackMode est légèrement différent entre Windows et les systèmes de type Unix. L'incohérence ne se produit que lorsqu'il existe plusieurs applications sur le même hôte, jointes au même groupe multicast, mais avec des paramètres différents en mode de bouclage multicast. Sous Windows, les applications pour lesquelles le bouclage est désactivé ne REÇOIVENT pas les paquets de bouclage. En revanche, sur les systèmes de type Unix, les applications pour lesquelles le bouclage est désactivé n'ENVOIENT pas les paquets de bouclage aux autres applications du même hôte. Consultez MSDN : https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2.

L'appel de cette méthode ne nécessite pas d'autorisations de multidiffusion.

Paramètres

  • socketId

    nombre

    ID du socket.

  • activé

    booléen

    Indiquez si vous souhaitez activer le mode de bouclage.

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (result: number) => void

    • résultat

      nombre

      Code de résultat renvoyé par l'appel réseau sous-jacent. Une valeur négative indique une erreur.

setMulticastTimeToLive()

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

Définit la durée de vie des paquets multicast envoyés au groupe multicast.

L'appel de cette méthode ne nécessite pas d'autorisations de multidiffusion.

Paramètres

  • socketId

    nombre

    ID du socket.

  • ttl

    nombre

    Valeur TTL (Time To Live).

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (result: number) => void

    • résultat

      nombre

      Code de résultat renvoyé par l'appel réseau sous-jacent. Une valeur négative indique une erreur.

setPaused()

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

Met en pause ou réactive un socket. Un socket mis en pause ne peut pas déclencher d'événements onReceive.

Paramètres

  • socketId

    nombre

    ID du socket.

  • mis en veille

    booléen

    Indicateur permettant de suspendre ou de réactiver la diffusion.

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 121 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

update()

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

Met à jour les propriétés du socket.

Paramètres

  • socketId

    nombre

    ID du socket.

  • propriétés

    SocketProperties

    Propriétés à mettre à jour.

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 121 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onReceive

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

Événement déclenché lorsqu'un paquet UDP a été reçu pour le socket donné.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (info: ReceiveInfo) => void

onReceiveError

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

Événement déclenché lorsqu'une erreur réseau s'est produite alors que l'environnement d'exécution attendait des données sur l'adresse et le port du socket. Une fois cet événement déclenché, le socket est mis en pause et aucun autre événement onReceive ne sera déclenché pour ce socket tant qu'il n'aura pas été réactivé.

Paramètres