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 IDs criados com outras APIs, como a API [socket](../socket/) obsoleta.

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 da 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

    number optional

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

  • resultCode

    número

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

SocketInfo

Propriedades

  • bufferSize

    number optional

    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, vai conter o endereço IPv4/6 local.

  • localPort

    number optional

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

  • nome

    string opcional

    String definida pelo aplicativo associada ao soquete.

  • pausado

    booleano

    Flag que indica se o soquete está impedido de disparar eventos onReceive.

  • persistente

    booleano

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

  • socketId

    número

    O identificador do soquete.

SocketProperties

Propriedades

  • bufferSize

    number optional

    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 fica 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 sockets 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,
): void

Vincula o endereço e a porta locais ao soquete. Para um soquete de cliente, é recomendável usar a porta 0 para permitir que a plataforma escolha uma porta livre.

Quando a operação bind é concluída, os eventos onReceive são gerados quando os pacotes UDP chegam ao endereço/porta especificados, 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 vincular a uma porta livre.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number) => void

    • resultado

      número

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

close()

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

Fecha o soquete e libera o endereço/porta a que ele está vinculado. Cada soquete criado precisa ser fechado após o uso. O ID do soquete não é mais 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 esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 121+

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

create()

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

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 esta aparência: 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      O resultado da criação do soquete.

Retorna

  • Promise<CreateInfo>

    Chrome 121+

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

getInfo()

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

Recupera o estado do soquete especificado.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

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

Retorna

  • Promise<SocketInfo>

    Chrome 121+

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

getJoinedGroups()

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

Recebe os endereços de grupo multicast a que o soquete está associado no momento.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (groups: string[]) => void

    • grupos

      string[]

      Matriz de grupos a que o soquete se juntou.

Retorna

  • Promise<string[]>

    Chrome 121+

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

getSockets()

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

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

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

      Matriz de objetos que contém informações de soquete.

Retorna

  • Promise<SocketInfo[]>

    Chrome 121+

    As promessas só são compatíveis 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,
): void

Entra no grupo de multicast e começa a receber pacotes dele. O soquete 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 para participar. Não é possível usar nomes de domínio.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number) => void

    • resultado

      número

      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,
): void

Sai do grupo de multicast ao qual você se juntou usando joinGroup. Isso só é necessário se você planeja continuar usando o soquete depois, já que o SO faz isso automaticamente quando o soquete é 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 a ser abandonado. Não é possível usar nomes de domínio.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number) => void

    • resultado

      número

      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,
): void

Envia dados no soquete especificado para o endereço e a porta especificados. O soquete 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 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,
): void

Ativa ou desativa pacotes de transmissão neste soquete.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • ativado

    booleano

    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

      número

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

setMulticastLoopbackMode()

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

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

Observação: o comportamento de setMulticastLoopbackMode é um pouco diferente entre o Windows e sistemas semelhantes ao Unix. A inconsistência ocorre apenas quando há mais de um aplicativo no mesmo host associado ao mesmo grupo multicast, mas com configurações diferentes no modo de loopback 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 MSDN: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

A chamada desse 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 deve ser ativado.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number) => void

    • resultado

      número

      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,
): void

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

A chamada desse método não exige permissões de multicast.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • ttl

    número

    O valor de tempo de vida.

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (result: number) => void

    • resultado

      número

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

setPaused()

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

Pausa ou retoma um soquete. Um soquete pausado é bloqueado de disparar eventos onReceive.

Parâmetros

  • socketId

    número

  • pausado

    booleano

    Flag para indicar se é preciso pausar ou retomar.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 121+

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

update()

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

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 esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 121+

    As promessas só são compatíveis 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 um erro de rede ocorreu enquanto o ambiente de execução aguardava dados no endereço e na porta do soquete. Quando esse evento é gerado, o soquete é pausado e nenhum outro evento onReceive será gerado para ele até que seja retomado.

Parâmetros