chrome.vpnProvider

Mô tả

Dùng API chrome.vpnProvider để triển khai ứng dụng VPN.

Quyền

vpnProvider

Phạm vi cung cấp

Chrome 43 trở lên Chỉ ChromeOS

Khái niệm và cách sử dụng

Dưới đây là cách sử dụng điển hình của chrome.vpnProvider:

  • Tạo cấu hình VPN bằng cách gọi createConfig(). Cấu hình VPN là một mục nhập cố định mà người dùng nhìn thấy trong giao diện người dùng ChromeOS. Người dùng có thể chọn một cấu hình VPN trong danh sách và kết nối với cấu hình đó hoặc ngắt kết nối khỏi cấu hình đó.

  • Thêm trình nghe vào các sự kiện onPlatformMessage, onPacketReceived và onConfigRemoved.

  • Khi người dùng kết nối với cấu hình VPN, onPlatformMessage sẽ nhận được thông báo "connected". Khoảng thời gian giữa các thông báo "connected" và "disconnected" được gọi là "phiên VPN". Trong khoảng thời gian này, tiện ích nhận được thông báo được coi là sở hữu phiên VPN.

  • Bắt đầu kết nối với máy chủ VPN và khởi động ứng dụng VPN.

  • Đặt các Thông số của kết nối bằng cách gọi setParameters().

  • Thông báo về trạng thái kết nối dưới dạng "connected" bằng cách gọi notifyConnectionStateChanged().

  • Khi bạn hoàn tất các bước trước đó mà không gặp lỗi, một đường hầm ảo sẽ được tạo tới ngăn xếp mạng của ChromeOS. Gói IP có thể được gửi qua đường hầm bằng cách gọi sendPacket() và bất kỳ gói nào bắt nguồn từ thiết bị ChromeOS sẽ được nhận bằng trình xử lý sự kiện onPacketReceived.

  • Khi người dùng ngắt kết nối khỏi cấu hình VPN, onPlatformMessage sẽ được kích hoạt cùng với thông báo "disconnected".

  • Nếu không còn cần thiết, cấu hình VPN (mạng riêng ảo) có thể bị huỷ bằng cách gọi destroyConfig().

Loại

Parameters

Thuộc tính

  • xử lý

    string

    Địa chỉ IP của giao diện VPN trong ký hiệu CIDR. IPv4 hiện là chế độ duy nhất được hỗ trợ.

  • broadcastAddress

    chuỗi không bắt buộc

    Địa chỉ truyền tin cho giao diện VPN. (mặc định: suy ra từ địa chỉ IP và mặt nạ)

  • dnsServers

    chuỗi[]

    Danh sách IP của các máy chủ DNS.

  • domainSearch

    string[] không bắt buộc

    Danh sách các miền tìm kiếm. (mặc định: không có miền tìm kiếm)

  • exclusionList

    chuỗi[]

    Loại trừ lưu lượng truy cập mạng khỏi danh sách các khối IP trong ký hiệu Định tuyến liên miền không phân lớp (CIDR) khỏi đường hầm. Đường liên kết này có thể được dùng để bỏ qua lưu lượng truy cập đến và đi từ máy chủ VPN. Khi có nhiều quy tắc khớp với một đích đến, quy tắc có tiền tố khớp dài nhất sẽ chiến thắng. Các mục nhập tương ứng với cùng một khối CIDR được coi là trùng lặp. Những sự trùng lặp như vậy trong danh sách đối chiếu (exclusionList + includesList) sẽ bị loại bỏ và không xác định được mục nhập trùng lặp chính xác sẽ bị loại bỏ.

  • inclusionList

    chuỗi[]

    Đưa lưu lượng truy cập mạng vào danh sách các khối IP trong ký hiệu Định tuyến liên miền không phân lớp (CIDR) vào đường hầm. Tham số này có thể dùng để thiết lập một đường hầm phân tách. Theo mặc định, không có giao thông nào được hướng đến đường hầm. Thêm mục nhập "0.0.0.0/0" vào danh sách này sẽ chuyển hướng tất cả lưu lượng truy cập của người dùng tới đường hầm. Khi có nhiều quy tắc khớp với một đích đến, quy tắc có tiền tố khớp dài nhất sẽ chiến thắng. Các mục nhập tương ứng với cùng một khối CIDR được coi là trùng lặp. Những sự trùng lặp như vậy trong danh sách đối chiếu (exclusionList + includesList) sẽ bị loại bỏ và không xác định được mục nhập trùng lặp chính xác sẽ bị loại bỏ.

  • mtu

    chuỗi không bắt buộc

    Chế độ cài đặt MTU cho giao diện VPN. (mặc định: 1500 byte)

  • kết nối lại

    chuỗi không bắt buộc

    Chrome 51 trở lên

    Tiện ích VPN có triển khai tính năng tự động kết nối hay không.

    Nếu đúng, các thông báo của nền tảng linkDown, linkUp, linkChanged, suspend và resume sẽ được dùng để báo hiệu các sự kiện tương ứng. Nếu đặt là false, hệ thống sẽ buộc ngắt kết nối VPN nếu cấu trúc liên kết mạng thay đổi và người dùng sẽ cần kết nối lại theo cách thủ công. (mặc định: false)

    Sản phẩm này là sản phẩm mới trong Chrome 51; thì hệ thống sẽ tạo một ngoại lệ trong các phiên bản cũ. Bạn có thể dùng try/catch để bật tính năng này theo điều kiện dựa trên sự hỗ trợ của trình duyệt.

PlatformMessage

Nền tảng sử dụng enum này để thông báo cho ứng dụng về trạng thái phiên VPN.

Enum

"đã kết nối"
Cho biết rằng cấu hình VPN đã kết nối.

"đã ngắt kết nối"
Cho biết rằng cấu hình VPN đã bị ngắt kết nối.

"error"
Cho biết đã xảy ra lỗi trong kết nối VPN, ví dụ: hết thời gian chờ. Nội dung mô tả lỗi được cung cấp làm đối số lỗi cho onPlatformMessage.

"linkDown"
Cho biết kết nối mạng vật lý mặc định bị gián đoạn.

"linkUp"
Cho biết rằng kết nối mạng vật lý mặc định đã được sao lưu.

"linkChanged"
Cho biết rằng kết nối mạng vật lý mặc định đã thay đổi, ví dụ: wifi->di động.

"suspend"
Cho biết hệ điều hành đang chuẩn bị tạm ngưng, vì vậy VPN sẽ huỷ kết nối. Không đảm bảo tiện ích sẽ nhận được sự kiện này trước khi tạm ngưng.

"Tiếp tục"
Cho biết hệ điều hành đã tiếp tục hoạt động và người dùng đã đăng nhập lại, vì vậy, VPN sẽ cố gắng kết nối lại.

UIEvent

Nền tảng sử dụng giá trị enum này để cho biết sự kiện đã kích hoạt onUIEvent.

Enum

"showAddDialog"
Yêu cầu ứng dụng VPN cho người dùng thấy hộp thoại thêm cấu hình.

"showConfigureDialog"
Yêu cầu ứng dụng VPN cho người dùng thấy hộp thoại cài đặt cấu hình.

VpnConnectionState

Ứng dụng VPN sử dụng enum này để thông báo cho nền tảng về trạng thái hiện tại. Điều này giúp truyền tải các thông điệp có ý nghĩa đến người dùng.

Enum

"Đã kết nối"
Chỉ định rằng có kết nối VPN thành công.

"không thành công"
Chỉ định rằng không kết nối được với VPN.

Phương thức

createConfig()

Lời hứa 
chrome.vpnProvider.createConfig(
  name: string,
  callback?: function,
)

Tạo một cấu hình VPN mới vẫn tồn tại qua nhiều phiên đăng nhập của người dùng.

Tham số

  • tên

    string

    Tên của cấu hình VPN.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (id: string) => void

    • id

      string

      Mã nhận dạng duy nhất cho cấu hình đã tạo hoặc undefined khi không thành công.

Giá trị trả về

  • Cam kết<string>

    Chrome 96 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

destroyConfig()

Lời hứa 
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
)

Huỷ cấu hình VPN do tiện ích tạo.

Tham số

  • id

    string

    Mã của cấu hình VPN cần huỷ.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 96 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

notifyConnectionStateChanged()

Lời hứa 
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
)

Thông báo trạng thái phiên VPN cho nền tảng. Thao tác này chỉ thành công khi phiên VPN do tiện ích sở hữu.

Tham số

  • tiểu bang

    VpnConnectionState

    Trạng thái phiên VPN của ứng dụng VPN.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 96 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

sendPacket()

Lời hứa 
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
)

Gửi một gói IP qua đường hầm được tạo cho phiên VPN. Thao tác này chỉ thành công khi phiên VPN do tiện ích sở hữu.

Tham số

  • dữ liệu

    ArrayBuffer

    Gói IP sẽ được gửi đến nền tảng.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 96 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

setParameters()

Lời hứa 
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
)

Đặt các tham số cho phiên VPN. Lệnh này sẽ được gọi ngay sau khi nhận được "connected" từ nền tảng. Thao tác này chỉ thành công khi phiên VPN do tiện ích sở hữu.

Tham số

  • thông số

    Tham số

    Các tham số của phiên VPN.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 96 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

Sự kiện

onConfigCreated

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

Được kích hoạt khi nền tảng tạo cấu hình cho tiện ích.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

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

    • id

      string

    • tên

      string

    • dữ liệu

      đối tượng

onConfigRemoved

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

Được kích hoạt khi nền tảng xoá cấu hình do tiện ích tạo.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (id: string) => void

    • id

      string

onPacketReceived

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

Được kích hoạt khi nhận được gói IP qua đường hầm cho phiên VPN do tiện ích sở hữu.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

    (data: ArrayBuffer) => void

    • dữ liệu

      ArrayBuffer

onPlatformMessage

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

Được kích hoạt khi nhận được thông báo từ nền tảng cho cấu hình VPN do tiện ích sở hữu.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

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

onUIEvent

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

Được kích hoạt khi có một sự kiện trên giao diện người dùng cho phần mở rộng. Sự kiện trên giao diện người dùng là các tín hiệu từ nền tảng, cho ứng dụng biết rằng cần hiển thị hộp thoại trên giao diện người dùng.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

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

    • event

      UIEvent

    • id

      chuỗi không bắt buộc