browser.vpnProvider

Descrição

Use a API chrome.vpnProvider para implementar um cliente de VPN.

Permissões

vpnProvider

Disponibilidade

Chrome 43+ browser.* desde o Chrome 148 Somente ChromeOS

Conceitos e uso

O uso típico de browser.vpnProvider é o seguinte:

  • Crie configurações de VPN chamando createConfig(). Uma configuração de VPN é uma entrada persistente mostrada ao usuário em uma interface do ChromeOS. O usuário pode selecionar uma configuração de VPN em uma lista e se conectar ou desconectar dela.

  • Adicione listeners aos eventos onPlatformMessage, onPacketReceived e onConfigRemoved.

  • Quando o usuário se conectar à configuração de VPN, onPlatformMessage será recebido com a mensagem "connected". O período entre as mensagens "connected" e "disconnected" é chamado de "sessão de VPN". Nesse período, a extensão que recebe a mensagem é considerada proprietária da sessão de VPN.

  • Inicie a conexão com o servidor de VPN e inicie o cliente VPN.

  • Defina os parâmetros da conexão chamando setParameters().

  • Notifique o estado da conexão como "connected" chamando notifyConnectionStateChanged().

  • Quando as etapas anteriores são concluídas sem erros, um túnel virtual é criado para a pilha de rede do ChromeOS. Os pacotes IP podem ser enviados pelo túnel chamando sendPacket(), e todos os pacotes originados no dispositivo ChromeOS serão recebidos usando o manipulador de eventos onPacketReceived.

  • Quando o usuário se desconectar da configuração da VPN, onPlatformMessage será acionado com a mensagem "disconnected".

  • Se a configuração da VPN não for mais necessária, ela poderá ser destruída chamando destroyConfig().

Tipos

Parameters

Propriedades

  • endereço

    string

    Endereço IP da interface de VPN na notação CIDR. No momento, o IPv4 é o único modo compatível.

  • broadcastAddress

    string opcional

    Endereço de transmissão da interface da VPN. (padrão: deduzido do endereço IP e da máscara)

  • dnsServers

    string[]

    Uma lista de IPs para os servidores DNS.

  • domainSearch

    string[] opcional

    Uma lista de domínios de pesquisa. (padrão: sem domínio de pesquisa)

  • exclusionList

    string[]

    Exclua do túnel o tráfego de rede para a lista de blocos de IP na notação CIDR. Isso pode ser usado para ignorar o tráfego de e para o servidor de VPN. Quando muitas regras correspondem a um destino, a regra com o prefixo correspondente mais longo vence. As entradas que correspondem ao mesmo bloco CIDR são tratadas como duplicadas. Essas duplicatas na lista agrupada (exclusionList + inclusionList) são eliminadas, e a entrada duplicada exata que será eliminada é indefinida.

  • inclusionList

    string[]

    Inclua o tráfego de rede na lista de blocos de IP na notação CIDR para o túnel. Esse parâmetro pode ser usado para configurar um túnel dividido. Por padrão, nenhum tráfego é direcionado ao túnel. Adicionar a entrada "0.0.0.0/0" a essa lista faz com que todo o tráfego do usuário seja redirecionado para o túnel. Quando muitas regras correspondem a um destino, a regra com o prefixo correspondente mais longo vence. As entradas que correspondem ao mesmo bloco CIDR são tratadas como duplicadas. Essas duplicatas na lista agrupada (exclusionList + inclusionList) são eliminadas, e a entrada duplicada exata que será eliminada é indefinida.

  • mtu

    string opcional

    Configuração de MTU para a interface de VPN. (padrão: 1.500 bytes)

  • reconnect

    string opcional

    Chrome 51+ browser.* desde o Chrome 148

    Se a extensão de VPN implementa a reconexão automática.

    Se for verdadeiro, as mensagens de plataforma linkDown, linkUp, linkChanged, suspend e resume serão usadas para sinalizar os respectivos eventos. Se for falsa, o sistema vai desconectar a VPN à força se a topologia de rede mudar, e o usuário precisará se reconectar manualmente. (padrão: false)

    Essa propriedade é nova no Chrome 51 e vai gerar uma exceção em versões anteriores. try/catch pode ser usado para ativar o recurso condicionalmente com base na compatibilidade do navegador.

PlatformMessage

O tipo enumerado é usado pela plataforma para notificar o cliente sobre o status da sessão de VPN.

Enumeração

"connected"
Indica que a configuração da VPN foi conectada.

"disconnected"
Indica que a configuração da VPN foi desconectada.

"error"
Indica que ocorreu um erro na conexão VPN, por exemplo, um tempo limite. Uma descrição do erro é fornecida como o argumento de erro para onPlatformMessage.

"linkDown"
Indica que a conexão de rede física padrão está inativa.

"linkUp"
Indica que a conexão de rede física padrão foi restabelecida.

"linkChanged"
Indica que a conexão de rede física padrão mudou, por exemplo, de Wi-Fi para celular.

"suspend"
Indica que o SO está se preparando para suspender, então a VPN precisa encerrar a conexão. Não há garantia de que a extensão vai receber esse evento antes da suspensão.

"resume"
Indica que o SO foi retomado e o usuário fez login novamente. Portanto, a VPN deve tentar se reconectar.

UIEvent

O tipo enumerado é usado pela plataforma para indicar o evento que acionou onUIEvent.

Enumeração

"showAddDialog"
Solicita que o cliente de VPN mostre a caixa de diálogo de adição de configuração ao usuário.

"showConfigureDialog"
Solicita que o cliente de VPN mostre a caixa de diálogo de configurações ao usuário.

VpnConnectionState

O tipo enumerado é usado pelo cliente VPN para informar à plataforma o estado atual. Isso ajuda a fornecer mensagens significativas ao usuário.

Enumeração

"connected"
Especifica que a conexão VPN foi bem-sucedida.

"failure"
Especifica que a conexão VPN falhou.

Métodos

createConfig()

browser.vpnProvider.createConfig(
  name: string,
): Promise<string>

Cria uma nova configuração de VPN que persiste em várias sessões de login do usuário.

Parâmetros

  • nome

    string

    O nome da configuração da VPN.

Retorna

  • Promise<string>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida quando a configuração é criada ou rejeitada se houver um erro.

destroyConfig()

browser.vpnProvider.destroyConfig(
  id: string,
): Promise<void>

Destrói uma configuração de VPN criada pela extensão.

Parâmetros

  • ID

    string

    ID da configuração de VPN a ser destruída.

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida quando a configuração é destruída ou rejeitada se houver um erro.

notifyConnectionStateChanged()

browser.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
): Promise<void>

Notifica o estado da sessão de VPN para a plataforma. Isso só vai funcionar quando a sessão de VPN for de propriedade da extensão.

Parâmetros

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida quando a notificação é concluída ou rejeitada se houver um erro.

sendPacket()

browser.vpnProvider.sendPacket(
  data: ArrayBuffer,
): Promise<void>

Envia um pacote IP pelo túnel criado para a sessão de VPN. Isso só vai funcionar quando a sessão de VPN for de propriedade da extensão.

Parâmetros

  • dados

    ArrayBuffer

    O pacote IP a ser enviado à plataforma.

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida quando o pacote é enviado ou rejeitada se houver um erro.

setParameters()

browser.vpnProvider.setParameters(
  parameters: Parameters,
): Promise<void>

Define os parâmetros da sessão de VPN. Ele precisa ser chamado imediatamente após o recebimento de "connected" da plataforma. Isso só vai funcionar quando a sessão de VPN for de propriedade da extensão.

Parâmetros

  • parâmetros

    Parâmetros

    Os parâmetros da sessão de VPN.

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida quando os parâmetros são definidos ou rejeitada se houver um erro.

Eventos

onConfigCreated

browser.vpnProvider.onConfigCreated.addListener(
  callback: function,
)

Acionado quando uma configuração é criada pela plataforma para a extensão.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (id: string, name: string, data: object) => void

    • ID

      string

    • nome

      string

    • dados

      objeto

onConfigRemoved

browser.vpnProvider.onConfigRemoved.addListener(
  callback: function,
)

Acionado quando uma configuração criada pela extensão é removida pela plataforma.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (id: string) => void

    • ID

      string

onPacketReceived

browser.vpnProvider.onPacketReceived.addListener(
  callback: function,
)

Acionado quando um pacote IP é recebido pelo túnel da sessão de VPN que pertence à extensão.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (data: ArrayBuffer) => void

    • dados

      ArrayBuffer

onPlatformMessage

browser.vpnProvider.onPlatformMessage.addListener(
  callback: function,
)

Acionado quando uma mensagem é recebida da plataforma para uma configuração de VPN de propriedade da extensão.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (id: string, message: PlatformMessage, error: string) => void

onUIEvent

browser.vpnProvider.onUIEvent.addListener(
  callback: function,
)

Acionado quando há um evento de interface para a extensão. Os eventos de interface são indicadores da plataforma que mostram ao app que uma caixa de diálogo de interface precisa ser mostrada ao usuário.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (event: UIEvent, id?: string) => void

    • evento

      UIEvent

    • ID

      string opcional