chrome.vpnProvider

refresh date: 2026-09-25 robots: noindex

Importante: questa API funziona solo su ChromeOS.

Descrizione

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

Autorizzazioni

vpnProvider

Disponibilità

Chrome 43 e versioni successive Solo ChromeOS

Utilizzo

L'utilizzo tipico di vpnProvider è il seguente:

• Crea configurazioni VPN utilizzando il metodo createConfig. Una configurazione VPN è una voce persistente mostrata all'utente in una UI nativa di ChromeOS. L'utente può selezionare una configurazione VPN da un elenco e connettersi o disconnettersi.

• Aggiungi listener agli eventi onPlatformMessage, onPacketReceived e onConfigRemoved.

• Quando l'utente si connette alla configurazione VPN, onPlatformMessage verrà ricevuto 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 possiede la sessione VPN.

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

• Imposta i parametri della connessione utilizzando setParameters.

• Notifica lo stato della connessione come "connected" utilizzando notifyConnectionStateChanged.

• Quando i passaggi precedenti vengono completati senza errori, viene creato un tunnel virtuale verso lo stack di rete di ChromeOS. I pacchetti IP possono essere inviati tramite il tunnel utilizzando sendPacket e tutti i pacchetti provenienti dal dispositivo ChromeOS verranno ricevuti utilizzando l'evento onPacketReceived.

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

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

Tipi

Parameters

Proprietà

• indirizzo

  stringa

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

• broadcastAddress

  stringa facoltativa

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

• dnsServers

  string[]

  Un elenco di IP per i server DNS.

• domainSearch

  string[] facoltativo

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

• exclusionList

  string[]

  Escludi dal tunnel il traffico di rete verso l'elenco di blocchi IP in notazione CIDR. Questa opzione può essere utilizzata per bypassare il traffico da e verso il server VPN. Quando più 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 duplicati. Questi duplicati nell'elenco combinato (exclusionList + inclusionList) vengono eliminati e la voce duplicata esatta che verrà eliminata non è definita.

• inclusionList

  string[]

  Includi il traffico di rete nell'elenco di blocchi IP in notazione CIDR nel tunnel. Questo parametro può essere utilizzato per configurare uno split tunnel. Per impostazione predefinita, nessun traffico viene indirizzato al tunnel. Se aggiungi la voce "0.0.0.0/0" a questo elenco, tutto il traffico degli utenti viene reindirizzato al tunnel. Quando più 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 duplicati. Questi duplicati nell'elenco combinato (exclusionList + inclusionList) vengono eliminati e la voce duplicata esatta che verrà eliminata non è definita.

• mtu

  stringa facoltativa

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

• riconnetti

  stringa facoltativa

  Chrome 51 e versioni successive

  Indica se l'estensione VPN implementa la riconnessione automatica.

  Se impostato su true, i messaggi della piattaforma linkDown, linkUp, linkChanged, suspend e resume verranno utilizzati per segnalare i rispettivi eventi. Se impostato su 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 in Chrome 51; genererà un'eccezione nelle versioni precedenti. try/catch può essere utilizzato per attivare la funzionalità in modo condizionale in base al supporto del browser.

PlatformMessage

L'enum viene utilizzato 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 è stata 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 per onPlatformMessage.

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

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

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

"suspend"
Indica che il sistema operativo si sta preparando alla sospensione, quindi la VPN deve 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 nuovamente l'accesso, pertanto la VPN deve provare a riconnettersi.

UIEvent

L'enum viene utilizzato 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.

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

VpnConnectionState

L'enum viene utilizzato dal client VPN per informare la piattaforma del suo stato attuale. In questo modo, l'utente riceve messaggi significativi.

Enum

"connected"
Specifica che la connessione VPN è riuscita.

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

Metodi

createConfig()

Promise

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

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

Parametri

• nome

  stringa

  Il nome della configurazione VPN.

• callback

  funzione elemento facoltativo

  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.

Resi

• Promise<string>

  Chrome 96 e versioni successive

  Restituisce una Promise che si risolve quando la configurazione viene creata o viene rifiutata se si verifica un errore.

  Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

destroyConfig()

Promise

chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
): Promise<void>

Elimina una configurazione VPN creata dall'estensione.

Parametri

• id

  stringa

  ID della configurazione VPN da eliminare.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 96 e versioni successive

  Restituisce una Promise che si risolve quando la configurazione viene eliminata o rifiutata se si verifica un errore.

  Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

notifyConnectionStateChanged()

Promise

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

Notifica lo stato della sessione VPN alla piattaforma. L'operazione riuscirà solo se la sessione VPN è di proprietà dell'estensione.

Parametri

• stato

  VpnConnectionState

  Lo stato della sessione VPN del client VPN.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 96 e versioni successive

  Restituisce una Promise che viene risolta quando la notifica è completa o rifiutata se si verifica un errore.

  Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

sendPacket()

Promise

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

Invia un pacchetto IP tramite il tunnel creato per la sessione VPN. L'operazione riuscirà solo se la sessione VPN è di proprietà dell'estensione.

Parametri

• dati

  ArrayBuffer

  Il pacchetto IP da inviare alla piattaforma.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 96 e versioni successive

  Restituisce una Promise che si risolve quando il pacchetto viene inviato o viene rifiutata se si verifica un errore.

  Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

setParameters()

Promise

chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
): Promise<void>

Imposta i parametri per la sessione VPN. Questo metodo deve essere chiamato immediatamente dopo la ricezione di "connected" dalla piattaforma. L'operazione riuscirà solo se la sessione VPN è di proprietà dell'estensione.

Parametri

• Parametri

  Parametri

  I parametri per la sessione VPN.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 96 e versioni successive

  Restituisce una Promise che si risolve quando i parametri vengono impostati o rifiuta se si verifica un errore.

  Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i 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,
)

Attivato 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 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

  • id

    stringa

  • messaggio

    PlatformMessage

  • errore

    stringa

onUIEvent

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

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

Parametri

• callback

  funzione

  Il parametro callback ha il seguente aspetto:

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

  • evento

    UIEvent

  • id

    stringa facoltativa