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 que antes era encontrada 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 de soquete criados com outras APIs, como a API [socket](../socket/), que foi descontinuada.

DnsQueryType

Chrome 103+

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

    número optional

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

  • resultCode

    número

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

SocketInfo

Propriedades

  • bufferSize

    número 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, contém o endereço IPv4/6 local.

  • localPort

    número optional

    Se o soquete subjacente estiver vinculado, contém a porta local dele.

  • nome

    string opcional

    String definida pelo aplicativo associada ao soquete.

  • pausado

    booleano

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

  • permanente

    booleano

    Sinalização 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 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.

  • permanente

    booleano opcional

    Sinalização que indica se o soquete é deixado aberto quando a página de evento 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,
): void

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

Depois que 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 vincular a uma porta livre.

  • callback

    função

    O parâmetro callback é semelhante a: 

    (result: number) => void

    • resultado

      número

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

close()

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

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

Parâmetros

  • socketId

    número

    O ID do soquete.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<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()

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

Cria um soquete UDP com as propriedades fornecidas.

Parâmetros

  • propriedades

    SocketProperties opcional

    As propriedades do soquete (opcional).

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (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()

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

Recupera o estado do soquete fornecido.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (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()

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

Recebe os endereços de grupo multicast aos quais o soquete está conectado no momento.

Parâmetros

  • socketId

    número

    O ID do soquete.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (groups: string[]) => void

    • grupos

      string[]

      Matriz de grupos em que o soquete entrou.

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()

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

Recupera a lista de soquetes abertos no momento que pertencem ao aplicativo.

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

      Matriz de objeto 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 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

    número

    O ID do soquete.

  • endereço

    string

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

  • callback

    função

    O parâmetro callback é semelhante a: 

    (result: number) => void

    • resultado

      número

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

leaveGroup()

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

Sai do grupo multicast que foi acessado anteriormente usando joinGroup. Isso só é necessário se você planeja continuar usando o soquete depois, já que isso será feito automaticamente pelo SO quando o soquete for 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 do qual você quer sair. Não é possível usar nomes de domínio.

  • callback

    função

    O parâmetro callback é semelhante a: 

    (result: number) => void

    • resultado

      número

      O código de resultado retornado da 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,
): void

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

    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+

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

  • callback

    função

    O parâmetro callback é semelhante a: 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      Resultado do método send.

setBroadcast()

Chrome 44+ 
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, false para desativá-los.

  • callback

    função

    O parâmetro callback é semelhante a: 

    (result: number) => void

    • resultado

      número

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

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 os sistemas Windows e Unix. A inconsistência acontece apenas quando há mais de um aplicativo no mesmo host associado ao mesmo grupo de multicast, mas 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 do tipo 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 requer 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 é semelhante a: 

    (result: number) => void

    • resultado

      número

      O código de resultado retornado da chamada de rede. 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 requer 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 é semelhante a: 

    (result: number) => void

    • resultado

      número

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

setPaused()

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

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

Parâmetros

  • socketId

    número

    O ID do soquete.

  • pausado

    booleano

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

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<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()

Promessa 
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.

  • propriedades

    SocketProperties

    As propriedades a serem atualizadas.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<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 em questão.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (info: ReceiveInfo) => void

onReceiveError

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

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

Parâmetros