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 "socket".

Manifesto

As chaves a seguir precisam ser declaradas no manifesto para usar essa API.

"sockets"

Tipos

CreateInfo

Propriedades

  • socketId

    número

    O ID do soquete recém-criado. Os IDs de soquete criados com essa API não são compatíveis com os criados em outras APIs, como a API [socket](../socket/) 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.

Enumeração

"any"

"ipv4"

"ipv6"

ReceiveErrorInfo

Propriedades

  • resultCode

    número

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

  • socketId

    número

    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

    número

    A porta do host de origem do pacote.

  • socketId

    número

    O ID do soquete.

SendInfo

Propriedades

  • bytesSent

    número opcional

    O número de bytes enviados (se o resultado for 0)

  • resultCode

    número

    O código de resultado retornado pela chamada de rede. 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 socket subjacente estiver vinculado, ele conterá o endereço IPv4/6 local.

  • localPort

    número opcional

    Se o socket subjacente estiver vinculado, ele conterá a porta local.

  • nome

    string opcional

    String definida pelo aplicativo associada ao soquete.

  • pausado

    booleano

    Flag que indica se o soquete está bloqueado para disparar eventos onReceive.

  • persistente

    booleano

    Flag que indica se o soquete é deixado aberto quando o aplicativo é suspenso (consulte SocketProperties.persistent).

  • socketId

    número

    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 é 4096.

  • nome

    string opcional

    Uma string definida pelo aplicativo associada ao soquete.

  • persistente

    booleano opcional

    Flag que indica se o soquete é deixado aberto quando a página de eventos do aplicativo é descarregada (consulte Gerenciar o ciclo de vida do app). O valor padrão é "false". 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 do socket. Para um socket de cliente, é recomendável usar a porta 0 para permitir que a plataforma escolha uma porta disponível.

Quando a operação bind é concluída, os 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

    número

    O ID do soquete.

  • endereço

    string

    O endereço da máquina local. Os formatos de nome DNS, IPv4 e IPv6 são aceitos. Use "0.0.0.0" para aceitar pacotes de todas as interfaces de rede locais disponíveis.

  • porta

    número

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

  • callback

    função

    O parâmetro callback tem este formato: 

    (result: number) => void

    • resultado

      número

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

close()

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

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

Parâmetros

  • socketId

    número

    O ID do soquete.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 121 e versões mais recentes

    As promessas têm suporte apenas para 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 opcional

    O parâmetro callback tem este formato: 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      O resultado da criação do soquete.

Retorna

  • Promise<CreateInfo>

    Chrome 121 e versões mais recentes

    As promessas têm suporte apenas para 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 fornecido.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      Objeto que contém as informações do soquete.

Retorna

  • Promessa<SocketInfo>

    Chrome 121 e versões mais recentes

    As promessas têm suporte apenas para 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 de grupo multicast aos quais o soquete está conectado.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (groups: string[]) => void

    • grupos

      string[]

      Matriz de grupos que o soquete entrou.

Retorna

  • Promise<string[]>

    Chrome 121 e versões mais recentes

    As promessas têm suporte apenas para 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 atualmente que pertencem ao aplicativo.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

      Matriz de objeto que contém informações do socket.

Retorna

  • Promise<SocketInfo[]>

    Chrome 121 e versões mais recentes

    As promessas têm suporte apenas para 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 dele. O socket precisa ser vinculado a uma porta local antes de chamar esse método.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • endereço

    string

    O endereço do grupo a ser adicionado. Não é possível usar nomes de domínio.

  • callback

    função

    O parâmetro callback tem este formato: 

    (result: number) => void

    • resultado

      número

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

leaveGroup()

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

Sai do grupo multicast adicionado anteriormente usando joinGroup. Isso só é necessário se você planeja continuar usando o socket depois, já que isso será feito automaticamente pelo SO quando o socket estiver fechado.

Sair do grupo impede 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

    número

    O ID do soquete.

  • endereço

    string

    O endereço do grupo que você quer deixar. Não é possível usar nomes de domínio.

  • callback

    função

    O parâmetro callback tem este formato: 

    (result: number) => void

    • resultado

      número

      O código de resultado retornado pela chamada de rede. 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 socket precisa ser vinculado a uma porta local antes de chamar esse método.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • dados

    ArrayBuffer

    Os dados a serem enviados.

  • endereço

    string

    O endereço da máquina remota.

  • porta

    número

    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 este formato: 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      Resultado do método send.

setBroadcast()

Chrome 44 e versões mais recentes 
chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
)

Ativa ou desativa pacotes de transmissão neste soquete.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • ativado

    booleano

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

  • callback

    função

    O parâmetro callback tem este formato: 

    (result: number) => void

    • resultado

      número

      O código de resultado retornado pela chamada de rede.

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 só acontece quando há mais de um aplicativo no mesmo host conectado ao mesmo grupo de multicast e com configurações diferentes no modo de loopback de multicast. No Windows, os aplicativos com loopback desativado não RECEBEM os pacotes de loopback. Já em sistemas semelhantes ao Unix, os aplicativos com loopback desativado não ENVIAM os pacotes de loopback para outros aplicativos no mesmo host. Consulte o MSDN: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

Chamar esse método não exige permissões de multicast.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • ativado

    booleano

    Indica se o modo de loopback está ativado.

  • callback

    função

    O parâmetro callback tem este formato: 

    (result: number) => void

    • resultado

      número

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

setMulticastTimeToLive()

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

Define o tempo de vida dos pacotes multicast enviados para o grupo multicast.

Chamar esse método não exige permissões de multicast.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • ttl

    número

    O valor de time to live.

  • callback

    função

    O parâmetro callback tem este formato: 

    (result: number) => void

    • resultado

      número

      O código de resultado retornado pela chamada de rede. 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 é bloqueado para acionar eventos onReceive.

Parâmetros

  • socketId

    número

  • pausado

    booleano

    Flag para indicar se a pausa deve ser ativada ou desativada.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 121 e versões mais recentes

    As promessas têm suporte apenas para 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

    número

    O ID do soquete.

  • properties

    SocketProperties

    As propriedades a serem atualizadas.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 121 e versões mais recentes

    As promessas têm suporte apenas para 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 socket especificado.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    (info: ReceiveInfo) => void

onReceiveError

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

Evento gerado quando um erro de rede ocorreu enquanto o ambiente de execução aguardava dados no endereço e na porta do soquete. Depois que esse evento é gerado, o socket é pausado, e nenhum outro evento onReceive é gerado até que o socket seja retomado.

Parâmetros