chrome.vpnProvider

Descrição

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

Permissões

vpnProvider

Disponibilidade

Chrome 43 ou mais recente Somente no ChromeOS

Uso

O uso típico de vpnProvider é o seguinte:

  • Crie configurações de VPN usando o método createConfig. Uma configuração de VPN é uma entrada persistente mostrada ao usuário em uma interface nativa 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". Chamamos o período entre as mensagens "connected" e "disconnected" 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 VPN e inicie o cliente VPN.

  • Defina os parâmetros da conexão usando setParameters.

  • Notifique o estado da conexão como "connected" usando notifyConnectionStateChanged.

  • Quando as etapas acima 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 usando sendPacket, e todos os pacotes originados no dispositivo ChromeOS serão recebidos usando o evento onPacketReceived.

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

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

Tipos

Parameters

Propriedades

  • endereço

    string

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

  • broadcastAddress

    string opcional

    Endereço de transmissão da interface 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: nenhum 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 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. Esses duplicados na lista combinada (exclusionList + inclusionList) são eliminados, e a entrada duplicada exata que será eliminada não é definida.

  • 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. Esses duplicados na lista combinada (exclusionList + inclusionList) são eliminados, e a entrada duplicada exata que será eliminada não é definida.

  • mtu

    string opcional

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

  • reconectar

    string opcional

    Chrome 51 ou mais recente

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

    Se for "true", as mensagens da plataforma linkDown, linkUp, linkChanged, suspend e resume serão usadas para sinalizar os respectivos eventos. Se for "false", 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 gera uma exceção em versões anteriores. try/catch pode ser usado para ativar condicionalmente o recurso com base no suporte do navegador.

PlatformMessage

A enumeração é usada pela plataforma para notificar o cliente sobre o status da sessão de VPN.

Enumeração

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

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

"error"
Indica que ocorreu um erro na conexão VPN, por exemplo, um tempo limite excedido. 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 está funcionando novamente.

"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 deve 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

A enumeração é usada pela plataforma para indicar o evento que acionou onUIEvent.

Enumeração

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

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

VpnConnectionState

A enumeração é usada pelo cliente VPN para informar a plataforma sobre o estado atual. Isso ajuda a fornecer mensagens significativas ao usuário.

Enumeração

"connected"
Especifica que a conexão VPN foi feita sem problemas.

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

Métodos

createConfig()

Promise 
chrome.vpnProvider.createConfig(
  name: string,
  callback?: function,
): Promise<string>

Cria uma 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 de VPN.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (id: string) => void

    • ID

      string

      Um ID exclusivo para a configuração criada ou undefined em caso de falha.

Retorna

  • Promise<string>

    Chrome 96+

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

destroyConfig()

Promise 
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
): 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.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 96+

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

notifyConnectionStateChanged()

Promise 
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
): Promise<void>

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

Parâmetros

  • O estado da sessão VPN do cliente VPN.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 96+

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

sendPacket()

Promise 
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
): Promise<void>

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

Parâmetros

  • dados

    ArrayBuffer

    O pacote IP a ser enviado para a plataforma.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 96+

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

setParameters()

Promise 
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
): 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 da VPN for de propriedade da extensão.

Parâmetros

  • parâmetros

    Parâmetros

    Os parâmetros da sessão de VPN.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 96+

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

Eventos

onConfigCreated

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

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

    • ID

      string

    • nome

      string

    • dados

      objeto

onConfigRemoved

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

    (id: string) => void

    • ID

      string

onPacketReceived

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (data: ArrayBuffer) => void

    • dados

      ArrayBuffer

onPlatformMessage

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

onUIEvent

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • evento

      UIEvent

    • ID

      string opcional