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

L'utilizzo tipico di chrome.vpnProvider è il seguente:

  • Crea configurazioni VPN chiamando createConfig(). Una configurazione VPN è una voce permanente mostrata all'utente in una UI 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 connette alla configurazione VPN, onPlatformMessage riceverà il messaggio con il messaggio "connected". Il periodo tra i messaggi "connected" e "disconnected" è chiamato "sessione VPN". In questo periodo di tempo, si dice che l'estensione che riceve il messaggio sia la proprietaria della sessione VPN.

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

  • Imposta i parametri della connessione chiamando setParameters().

  • Avvisa lo stato della connessione come "connected" chiamando notifyConnectionStateChanged().

  • Una volta completati i passaggi precedenti senza errori, viene creato un tunnel virtuale per lo stack di rete di ChromeOS. I pacchetti IP possono essere inviati attraverso il tunnel chiamando sendPacket() e tutti i pacchetti provenienti dal dispositivo ChromeOS verranno ricevuti utilizzando il gestore di eventi onPacketReceived.

  • Quando l'utente si disconnette dalla configurazione VPN, onPlatformMessage viene attivato 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. IPv4 è attualmente l'unica modalità supportata.

  • broadcastAddress

    stringa facoltativo

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

  • dnsServers

    stringa[]

    Un elenco di IP per i server DNS.

  • domainSearch

    string[] facoltativo

    Un elenco di domini di ricerca. (predefinito: nessun dominio di ricerca)

  • exclusionList

    stringa[]

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

  • inclusionList

    stringa[]

    Includi il traffico di rete verso l'elenco dei blocchi IP in notazione CIDR verso il tunnel. Questo parametro può essere utilizzato per configurare un tunnel di suddivisione. Per impostazione predefinita, nessun traffico viene indirizzato al tunnel. Aggiunta della voce "0.0.0.0/0" a questo elenco viene reindirizzato tutto il traffico degli utenti al tunnel. Quando molte regole corrispondono a una destinazione, vince la regola con il prefisso corrispondente più lungo. Le voci che corrispondono allo stesso blocco CIDR vengono trattate come duplicate. Tali duplicati nell'elenco compresso (exclusionList + inclusionList) vengono eliminati e l'esatta voce duplicata 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 disconnetterà forzatamente la VPN se la topologia di rete cambia e l'utente dovrà riconnettersi manualmente. (valore predefinito: false)

    Questa proprietà è nuova nella versione 51 di Chrome verrà generata un'eccezione nelle versioni precedenti. provi/catch può essere usato per abilitare la funzionalità in modo condizionale in base al supporto del browser.

PlatformMessage

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

Enum

"connected"
Indica che la configurazione VPN è connessa.

"disconnected"
Indica che la configurazione VPN è disconnessa.

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

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

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

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

"suspend"
Indica che il sistema operativo sta preparando la sospensione, quindi la VPN dovrebbe interrompere la connessione. Non è garantito che l'estensione riceva questo evento prima della sospensione.

"resume"
Indica che il sistema operativo è stato ripreso e l'utente ha eseguito nuovamente 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 Aggiungi configurazione.

"showConfigureDialog"
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 all'utente messaggi significativi.

Enum

"connected"
Specifica che la connessione VPN è riuscita.

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

Metodi

createConfig()

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

Crea una nuova configurazione VPN che persiste per 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 oppure undefined in caso di errore.

Resi

  • Promise<string>

    Chrome 96 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

destroyConfig()

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

Distrugge 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

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

notifyConnectionStateChanged()

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

Informa la piattaforma sullo stato della sessione VPN. 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

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

sendPacket()

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

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

setParameters()

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

Consente di impostare i parametri per la sessione VPN. Questo deve essere chiamato immediatamente dopo che "connected" viene ricevuto 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

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

    Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato 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 viene ricevuto un pacchetto IP 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 dalla piattaforma viene ricevuto un messaggio 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 esiste un evento UI per l'estensione. Gli eventi UI sono indicatori della piattaforma che indicano all'app che una finestra di dialogo dell'interfaccia utente deve essere mostrata all'utente.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • evento

      UIEvent

    • id

      stringa facoltativo