chrome.sockets.udp

Descrição

Use a API chrome.sockets.udp para enviar e receber dados pela rede usando conexões UDP. Essa API substitui a funcionalidade UDP encontrada anteriormente na API de "socket".

Manifesto

As chaves a seguir precisam ser declaradas no manifesto para o uso dessa API.

"sockets"

Tipos

CreateInfo

Propriedades

  • socketId

    number

    O ID do soquete recém-criado. Os IDs de soquete criados com base nessa API não são compatíveis com aqueles criados com outras APIs, como a API [socket](../socket/), que foi descontinuada.

DnsQueryType

Chrome 103 ou mais recente

Preferências de resolução de DNS. O padrão é any e usa a configuração atual do SO, que pode retornar IPv4 ou IPv6. ipv4 força o IPv4, e ipv6 força o IPv6.

Tipo enumerado

"ipv4"

"ipv6"

ReceiveErrorInfo

Propriedades

  • resultCode

    number

    O código de resultado retornado da chamada subjacente de recvfrom().

  • socketId

    number

    O ID do soquete.

ReceiveInfo

Propriedades

  • dados

    ArrayBuffer

    O conteúdo do pacote UDP (truncado para o tamanho atual do buffer).

  • remoteAddress

    string

    O endereço do host de origem do pacote.

  • remotePort

    number

    A porta do host de origem do pacote.

  • socketId

    number

    O ID do soquete.

SendInfo

Propriedades

  • bytesSent

    número opcional

    O número de bytes enviados (if result == 0)

  • resultCode

    number

    O código de resultado retornado da chamada de rede subjacente. Um valor negativo indica um erro.

SocketInfo

Propriedades

  • bufferSize

    número opcional

    O tamanho do buffer usado para receber dados. Se nenhum tamanho de buffer tiver sido especificado explicitamente, o valor não será fornecido.

  • localAddress

    string opcional

    Se o soquete subjacente estiver vinculado, conterá seu endereço IPv4/6 local.

  • localPort

    número opcional

    Se o soquete subjacente estiver vinculado, conterá a porta local dele.

  • name

    string opcional

    String definida pelo aplicativo associada ao soquete.

  • pausado

    boolean

    Sinalização que indica se o soquete está impedido de disparar eventos onReceive.

  • permanentes

    boolean

    Sinalização que indica se o soquete foi deixado em aberto quando o aplicativo foi suspenso (consulte SocketProperties.persistent).

  • socketId

    number

    O identificador do soquete.

SocketProperties

Propriedades

  • bufferSize

    número opcional

    O tamanho do buffer usado para receber dados. Se o buffer for muito pequeno para receber o pacote UDP, os dados serão perdidos. O valor padrão é 4.096.

  • name

    string opcional

    Uma string definida pelo aplicativo associada ao soquete.

  • permanentes

    booleano opcional

    Sinalização que indica se o soquete foi deixado em aberto quando a página de eventos do aplicativo é descarregada (consulte Gerenciar o ciclo de vida do app). O valor padrão é "falso". Quando o aplicativo é carregado, todos os soquetes abertos anteriormente com persistent=true podem ser buscados com getSockets.

Métodos

bind()

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

Vincula o endereço local e a porta ao soquete. Para um soquete de cliente, recomendamos usar a porta 0 para que a plataforma escolha uma porta livre.

Após a conclusão da operação bind, eventos onReceive são gerados quando os pacotes UDP chegam ao endereço/porta especificado, a menos que o soquete esteja pausado.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • endereço

    string

    O endereço da máquina local. Há suporte para o nome DNS e os formatos IPv4 e IPv6. Use "0.0.0.0" para aceitar pacotes de todas as interfaces de rede locais disponíveis.

  • porta

    number

    A porta da máquina local. Use "0" para se vincular a uma porta livre.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number)=>void

    • resultado

      number

      O código de resultado retornado da chamada de rede subjacente. Um valor negativo indica um erro.

close()

Promessa 
chrome.sockets.udp.close(
  socketId: number,
  callback?: function,
)

Fecha o soquete e libera o endereço/porta a que o soquete está vinculado. Cada soquete criado deve ser fechado após o uso. O ID do soquete deixa de ser válido assim que a função é chamada. No entanto, há a garantia de que o soquete será fechado somente quando o callback for invocado.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 121 ou mais recente

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

create()

Promessa 
chrome.sockets.udp.create(
  properties?: SocketProperties,
  callback?: function,
)

Cria um soquete UDP com as propriedades especificadas.

Parâmetros

  • properties

    SocketProperties opcional

    As propriedades do soquete (opcional).

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (createInfo: CreateInfo)=>void

    • createInfo

      CreateInfo

      O resultado da criação do soquete.

Retorna

  • Promise<CreateInfo>

    Chrome 121 ou mais recente

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getInfo()

Promessa 
chrome.sockets.udp.getInfo(
  socketId: number,
  callback?: function,
)

Recupera o estado do soquete especificado.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (socketInfo: SocketInfo)=>void

    • socketInfo

      SocketInfo

      Objeto contendo as informações do soquete.

Retorna

  • Promise<SocketInfo>

    Chrome 121 ou mais recente

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getJoinedGroups()

Promessa 
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
)

Recebe os endereços do grupo multicast aos quais o soquete está associado no momento.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (groups: string[])=>void

    • grupos

      string[]

      Matriz de grupos unidos pelo soquete.

Retorna

  • Promessa<string[]>

    Chrome 121 ou mais recente

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getSockets()

Promessa 
chrome.sockets.udp.getSockets(
  callback?: function,
)

Recupera a lista de soquetes abertos no momento pertencentes ao aplicativo.

Parâmetros

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (socketInfos: SocketInfo[])=>void

    • socketInfos

      SocketInfo[]

      Matriz de objeto que contém informações sobre o soquete.

Retorna

  • Promise<SocketInfo[]>

    Chrome 121 ou mais recente

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

joinGroup()

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

entra no grupo de multicast e começa a receber pacotes desse grupo. O soquete precisa estar vinculado a uma porta local antes de chamar esse método.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • endereço

    string

    O endereço do grupo do qual participar. Nomes de domínio não são aceitos.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number)=>void

    • resultado

      number

      O código de resultado retornado da chamada de rede subjacente. Um valor negativo indica um erro.

leaveGroup()

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

Sai do grupo de multicast anteriormente conectado usando joinGroup. Isso só é necessário para chamar se você planeja continuar usando o soquete depois, porque isso será feito automaticamente pelo SO quando o soquete for fechado.

Sair do grupo impedirá que o roteador envie datagramas multicast para o host local, presumindo que nenhum outro processo no host ainda esteja associado ao grupo.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • endereço

    string

    O endereço do grupo de saída. Nomes de domínio não são aceitos.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number)=>void

    • resultado

      number

      O código de resultado retornado da chamada de rede subjacente. Um valor negativo indica um erro.

send()

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

Envia dados no soquete especificado para o endereço e a porta especificados. O soquete precisa estar vinculado a uma porta local antes de chamar esse método.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • dados

    ArrayBuffer

    Os dados a serem enviados.

  • endereço

    string

    O endereço da máquina remota.

  • porta

    number

    A porta da máquina remota.

  • dnsQueryType

    DnsQueryType opcional

    Chrome 103 ou mais recente

    A preferência de resolução de endereço.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (sendInfo: SendInfo)=>void

    • sendInfo

      SendInfo

      Resultado do método send.

setBroadcast()

Chrome 44 ou mais recente 
chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
)

Ativa ou desativa pacotes de transmissão neste soquete.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • ativado

    boolean

    true para ativar pacotes de transmissão e false para desativá-los.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number)=>void

    • resultado

      number

      O código de resultado retornado da chamada de rede subjacente.

setMulticastLoopbackMode()

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

Define se os pacotes multicast enviados do host para o grupo multicast serão repetidos para o host.

Observação: o comportamento de setMulticastLoopbackMode é um pouco diferente entre sistemas Windows e Unix. A inconsistência acontece apenas quando há mais de um aplicativo no mesmo host mesclado no mesmo grupo multicast com configurações diferentes no modo de loopback multicast. No Windows, os aplicativos com o loopback desativado não RECEBE os pacotes de loopback. Em sistemas do tipo Unix, os aplicativos com loopback desativado não ENVIAM os pacotes de loopback para outros aplicativos no mesmo host. Consulte a MSDN: http://goo.gl/6vqbj

Não são necessárias permissões multicast para chamar esse método.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • ativado

    boolean

    Indica se o modo de loopback será ativado.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number)=>void

    • resultado

      number

      O código de resultado retornado da chamada de rede subjacente. Um valor negativo indica um erro.

setMulticastTimeToLive()

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

Define a vida útil dos pacotes multicast enviados para o grupo multicast.

Não são necessárias permissões multicast para chamar esse método.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • ttl

    number

    O valor de time to live (TTL).

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number)=>void

    • resultado

      number

      O código de resultado retornado da chamada de rede subjacente. Um valor negativo indica um erro.

setPaused()

Promessa 
chrome.sockets.udp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
)

Pausa ou retoma um soquete. Um soquete pausado está impedido de disparar eventos onReceive.

Parâmetros

  • socketId

    number

  • pausado

    boolean

    Sinalização para indicar se é preciso pausar ou retomar.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 121 ou mais recente

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

update()

Promessa 
chrome.sockets.udp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
)

Atualiza as propriedades do soquete.

Parâmetros

  • socketId

    number

    O ID do soquete.

  • properties

    SocketProperties

    Propriedades a serem atualizadas.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 121 ou mais recente

    Promessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onReceive

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

Evento gerado quando um pacote UDP é recebido para o soquete especificado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (info: ReceiveInfo)=>void

onReceiveError

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

Evento gerado quando ocorre um erro de rede enquanto o tempo de execução aguarda os dados no endereço e na porta do soquete. Quando esse evento for gerado, o soquete será pausado e nenhum evento onReceive será gerado para esse soquete até que ele seja retomado.

Parâmetros