chrome.vpnProvider

Descrizione

Utilizza l'API chrome.vpnProvider per implementare un client VPN.

Autorizzazioni

vpnProvider

Disponibilità

Chrome 43 e versioni successive Solo ChromeOS

Concetti e utilizzo

Di seguito è riportato un utilizzo tipico di chrome.vpnProvider:

  • Crea configurazioni VPN chiamando il numero createConfig(). Una configurazione VPN è una voce persistente all'utente in un'interfaccia utente di ChromeOS. L'utente può selezionare una configurazione VPN da un elenco e connettersi o disconnettersi da quest'ultima.

  • Aggiungi listener agli eventi onPlatformMessage, onPacketReceived e onConfigRemoved.

  • Quando l'utente si connetterà alla configurazione VPN, verrà ricevuto il messaggio onPlatformMessage con il messaggio "connected". Il punto tra i messaggi "connected" e "disconnected" viene chiamato "sessione VPN". In questo periodo di tempo, l'estensione che riceve il messaggio assume la proprietà della sessione VPN.

  • Avvia la connessione al server VPN e avvia il client VPN.

  • Impostare i parametri della connessione chiamando setParameters().

  • Invia una notifica allo stato della connessione come "connected" chiamando notifyConnectionStateChanged().

  • Una volta completati i passaggi precedenti senza errori, viene creato un tunnel virtuale nello stack di rete di ChromeOS. I pacchetti IP possono essere inviati attraverso il tunnel chiamando sendPacket(); tutti i pacchetti che hanno origine sul dispositivo ChromeOS verranno ricevuti utilizzando il gestore di eventi onPacketReceived.

  • Quando l'utente si disconnette dalla configurazione VPN, viene attivato onPlatformMessage con il messaggio "disconnected".

  • Se la configurazione VPN non è più necessaria, può essere eliminata chiamando destroyConfig().

Tipi

Parameters

Proprietà

  • indirizzo

    stringa

    Indirizzo IP per l'interfaccia VPN in notazione CIDR. Al momento, IPv4 è l'unica modalità supportata.

  • broadcastAddress

    stringa facoltativo

    Indirizzo di trasmissione per l'interfaccia VPN. (valore predefinito: dedotto dall'indirizzo e dalla maschera IP)

  • dnsServers

    stringa[]

    Un elenco di IP per i server DNS.

  • domainSearch

    string[] facoltativo

    Un elenco di domini di ricerca. (impostazione predefinita: nessun dominio di ricerca)

  • exclusionList

    stringa[]

    Escludi il traffico di rete dall'elenco dei blocchi IP in notazione CIDR dal tunnel. Questa opzione può essere utilizzata per bypassare il traffico da e verso il server VPN. Quando molte regole corrispondono a una destinazione, vince quella con il prefisso corrispondente più lungo. Le voci che corrispondono allo stesso blocco CIDR vengono trattate come duplicati. I duplicati dell'elenco compresso (exclusionList + inclusionList) vengono eliminati e la voce duplicata esatta che verrà eliminata non è definita.

  • inclusionList

    stringa[]

    Includi il traffico di rete nell'elenco dei blocchi IP nella notazione CIDR del tunnel. Questo parametro può essere utilizzato per configurare un tunnel diviso. Per impostazione predefinita, nessun traffico viene indirizzato al tunnel. Aggiungendo la voce "0.0.0.0/0" a questo elenco, tutto il traffico utente viene reindirizzato al tunnel. Quando molte regole corrispondono a una destinazione, vince quella con il prefisso corrispondente più lungo. Le voci che corrispondono allo stesso blocco CIDR vengono trattate come duplicati. I duplicati dell'elenco compresso (exclusionList + inclusionList) vengono eliminati e la voce duplicata esatta che verrà eliminata non è definita.

  • mtu

    stringa facoltativo

    Impostazione MTU per l'interfaccia VPN. (valore predefinito: 1500 byte)

  • ricollega

    stringa facoltativo

    Chrome 51 e versioni successive

    Indica se l'estensione VPN implementa o meno la riconnessione automatica.

    Se il valore è true, i messaggi della piattaforma linkDown, linkUp, linkChanged, suspend e resume verranno utilizzati per segnalare i rispettivi eventi. Se il valore è false, il sistema disconnette forzatamente la VPN se la topologia di rete cambia e l'utente dovrà riconnettersi manualmente. (valore predefinito: false)

    Questa proprietà è nuova in Chrome 51 e genererà un'eccezione nelle versioni precedenti. provare/catch può essere utilizzato per attivare la funzionalità in modo condizionale in base al supporto del browser.

PlatformMessage

L'enum viene utilizzata dalla piattaforma per notificare al client lo stato della sessione VPN.

Enum

"connesso"
Indica che la configurazione VPN è connessa.

"disconnesso"
Indica che la configurazione VPN è disconnessa.

"error"
Indica che si è verificato un errore nella connessione VPN, ad esempio un timeout. Una descrizione dell'errore viene fornita come argomento di errore in onPlatformMessage.

"linkDown"
Indica che la connessione di rete fisica predefinita non è attiva.

"linkUp"
Indica che è stata ripristinata la connessione di rete fisica predefinita.

"linkChanged"
Indica che è cambiata la connessione di rete fisica predefinita, ad esempio wifi->mobile.

"suspend"
Indica che il sistema operativo è in fase di sospensione, pertanto la VPN dovrebbe interrompere la connessione. Non è garantito che l'estensione riceva questo evento prima della sospensione.

"resume"
Indica che il sistema operativo è stato ripristinato e l'utente ha eseguito di nuovo l'accesso, quindi la VPN dovrebbe provare a riconnettersi.

UIEvent

L'enum viene utilizzata dalla piattaforma per indicare l'evento che ha attivato onUIEvent.

Enum

"showAddDialog"
Richiede che il client VPN mostri all'utente la finestra di dialogo per l'aggiunta della configurazione.

"showConfiguraDialog"
Richiede che il client VPN mostri all'utente la finestra di dialogo delle impostazioni di configurazione.

VpnConnectionState

L'enum viene utilizzata dal client VPN per informare la piattaforma del suo stato attuale. Ciò contribuisce a fornire messaggi significativi all'utente.

Enum

"connesso"
Specifica che la connessione VPN è riuscita.

"failure"
Specifica che la connessione VPN non è riuscita.

Metodi

createConfig()

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

Crea una nuova configurazione VPN che persiste in più sessioni di accesso dell'utente.

Parametri

  • nome

    stringa

    Il nome della configurazione VPN.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (id: string)=>void

    • id

      stringa

      Un ID univoco per la configurazione creata o undefined in caso di errore.

Ritorni

  • Promessa<string>

    Chrome 96 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

destroyConfig()

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

Elimina una configurazione VPN creata dall'estensione.

Parametri

  • id

    stringa

    ID della configurazione VPN da eliminare.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 96 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

notifyConnectionStateChanged()

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

Invia una notifica allo stato della sessione VPN alla piattaforma. Questa operazione avrà esito positivo solo se la sessione VPN è di proprietà dell'estensione.

Parametri

  • Lo stato della sessione VPN del client VPN.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 96 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

sendPacket()

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

Invia un pacchetto IP attraverso il tunnel creato per la sessione VPN. Questa operazione avrà esito positivo solo se la sessione VPN è di proprietà dell'estensione.

Parametri

  • dati

    ArrayBuffer

    Il pacchetto IP da inviare alla piattaforma.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 96 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

setParameters()

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

Imposta i parametri per la sessione VPN. Dovrebbe essere chiamato immediatamente dopo la ricezione di "connected" dalla piattaforma. Questa operazione avrà esito positivo solo se la sessione VPN è di proprietà dell'estensione.

Parametri

  • Parametri

    Parametri

    I parametri per la sessione VPN.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 96 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

Eventi

onConfigCreated

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

Si attiva quando la piattaforma crea una configurazione per l'estensione.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • id

      stringa

    • nome

      stringa

    • dati

      oggetto

onConfigRemoved

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

Si attiva quando una configurazione creata dall'estensione viene rimossa dalla piattaforma.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (id: string)=>void

    • id

      stringa

onPacketReceived

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

Si attiva quando un pacchetto IP viene ricevuto tramite il tunnel per la sessione VPN di proprietà dell'estensione.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (data: ArrayBuffer)=>void

    • dati

      ArrayBuffer

onPlatformMessage

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

Si attiva quando viene ricevuto un messaggio dalla piattaforma per una configurazione VPN di proprietà dell'estensione.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

onUIEvent

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

Si attiva quando si verifica un evento UI per l'estensione. Gli eventi della UI sono indicatori della piattaforma che indicano all'app che è necessario mostrare all'utente una finestra di dialogo dell'interfaccia utente.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • event

      UIEvent

    • id

      stringa facoltativo