chrome.vpnProvider

Descrição

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

Permissões

vpnProvider

Disponibilidade

Chrome 43+ Apenas no ChromeOS

Conceitos e uso

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

  • Chame createConfig() para criar configurações de VPN. A configuração de uma 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.

  • Adicione listeners aos eventos onPlatformMessage, onPacketReceived e onConfigRemoved.

  • Quando o usuário se conectar à configuração da 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 VPN e 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 forem concluídas sem erros, um túnel virtual será criado para a pilha de rede do ChromeOS. Os pacotes IP podem ser enviados pelo túnel chamando sendPacket(). Todos os pacotes originados no dispositivo ChromeOS serão recebidos usando o manipulador de eventos onPacketReceived.

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

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

Tipos

Parameters

Propriedades

  • endereço

    string

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

  • broadcastAddress

    string opcional

    Endereço de transmissão para a 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: nenhum domínio de pesquisa)

  • exclusionList

    string[]

    Exclua do túnel o tráfego de rede da lista de blocos IP na notação CIDR. Isso pode ser usado para ignorar o tráfego de entrada e saída do servidor VPN. Quando muitas regras correspondem a um destino, a regra com o maior prefixo de correspondência ganha. As entradas que correspondem ao mesmo bloco CIDR são tratadas como duplicadas. Essas duplicatas na lista mesclada (exclusionList + includeList) são eliminadas e a entrada duplicada exata que será eliminada fica 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 para o túnel. Adicionar a entrada "0.0.0.0/0" a essa lista faz com que todo o tráfego de usuários seja redirecionado para o túnel. Quando muitas regras correspondem a um destino, a regra com o maior prefixo de correspondência ganha. As entradas que correspondem ao mesmo bloco CIDR são tratadas como duplicadas. Essas duplicatas na lista mesclada (exclusionList + includeList) são eliminadas e a entrada duplicada exata que será eliminada fica indefinida.

  • mtu

    string opcional

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

  • reconectar

    string opcional

    Chrome 51 ou mais recente

    Define se a extensão VPN implementa ou não a reconexão automática.

    Se verdadeiro, as mensagens das plataformas linkDown, linkUp, linkChanged, suspend e resume vão ser usadas para sinalizar os respectivos eventos. Se definido como "false", o sistema forçará a desconexão da VPN se a topologia da rede mudar e o usuário precisará se reconectar manualmente. (padrão: falso)

    Essa propriedade é nova no Chrome 51. Ela 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.

Tipo enumerado

"conectado"
Indica que a configuração de VPN está conectada.

"desconectado"
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 está armazenada em backup.

"linkChanged"
Indica que a conexão de rede física padrão mudou, por exemplo, wifi->mobile.

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

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

UIEvent

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

Tipo enumerado

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

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

VpnConnectionState

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

Tipo enumerado

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

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

Métodos

createConfig()

Promessa 
chrome.vpnProvider.createConfig(
  name: string,
  callback?: function,
)

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

Parâmetros

  • name

    string

    O nome da configuração da VPN.

  • callback

    função optional

    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

  • Promessa<string>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

destroyConfig()

Promessa 
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
)

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 optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

notifyConnectionStateChanged()

Promessa 
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
)

Notifica o estado da sessão VPN para a plataforma. Isso só funciona quando a sessão de VPN é de propriedade da extensão.

Parâmetros

  • O estado da sessão do cliente VPN.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

sendPacket()

Promessa 
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
)

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

Parâmetros

  • dados

    ArrayBuffer

    O pacote de IP a ser enviado para a plataforma.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

setParameters()

Promessa 
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
)

Define os parâmetros para a sessão de VPN. Ele precisa ser chamado imediatamente depois que "connected" é recebido da plataforma. Isso só funciona quando a sessão de VPN é de propriedade da extensão.

Parâmetros

  • parâmetros

    Parâmetros

    Parâmetros para a sessão de VPN.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

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

    • name

      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 da 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 de propriedade da 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 IU para a extensão. Os eventos de interface são sinais da plataforma que indicam ao app que uma caixa de diálogo da interface precisa ser mostrada ao usuário.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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