chrome.vpnProvider

설명

chrome.vpnProvider API를 사용하여 VPN 클라이언트를 구현합니다.

권한

vpnProvider

지원 대상

Chrome 43 이상 ChromeOS만 해당

개념 및 사용법

chrome.vpnProvider의 일반적인 사용법은 다음과 같습니다.

  • createConfig()를 호출하여 VPN 구성을 만듭니다. VPN 구성은 ChromeOS UI에서 사용자에게 표시되는 영구 항목입니다. 사용자는 목록에서 VPN 구성을 선택하여 해당 구성에 연결하거나 연결 해제할 수 있습니다.

  • onPlatformMessage, onPacketReceived, onConfigRemoved 이벤트에 리스너를 추가합니다.

  • 사용자가 VPN 구성에 연결되면 onPlatformMessage이(가) "connected" 메시지와 함께 수신됩니다. "connected" 메시지와 "disconnected" 메시지 사이의 기간을 'VPN 세션'이라고 합니다. 이 기간에 메시지를 수신하는 확장 프로그램이 VPN 세션을 소유한다고 말합니다.

  • VPN 서버 연결을 시작하고 VPN 클라이언트를 시작합니다.

  • setParameters()를 호출하여 연결의 매개변수를 설정합니다.

  • notifyConnectionStateChanged()를 호출하여 연결 상태를 "connected"로 알립니다.

  • 이전 단계가 오류 없이 완료되면 ChromeOS의 네트워크 스택에 가상 터널이 생성됩니다. IP 패킷은 sendPacket()를 호출하여 터널을 통해 전송할 수 있으며 ChromeOS 기기에서 시작되는 모든 패킷은 onPacketReceived 이벤트 핸들러를 사용하여 수신됩니다.

  • 사용자가 VPN 구성에서 연결을 해제하면 "disconnected" 메시지와 함께 onPlatformMessage가 실행됩니다.

  • VPN 구성이 더 이상 필요하지 않으면 destroyConfig()를 호출하여 삭제할 수 있습니다.

유형

Parameters

속성

  • 주소

    string

    CIDR 표기법으로 표시된 VPN 인터페이스의 IP 주소입니다. IPv4가 현재 지원되는 유일한 모드입니다.

  • broadcastAddress

    문자열 선택사항

    VPN 인터페이스의 브로드캐스트 주소입니다. (기본값: IP 주소 및 마스크에서 추론)

  • dnsServers

    문자열[]

    DNS 서버의 IP 목록입니다.

  • domainSearch

    string[] 선택사항

    검색 도메인 목록입니다. (기본값: 검색 도메인 없음)

  • exclusionList

    문자열[]

    터널에서 CIDR 표기법으로 IP 블록 목록에 네트워크 트래픽을 제외합니다. 이는 VPN 서버와 주고받는 트래픽을 우회하는 데 사용할 수 있습니다. 여러 규칙이 연결 대상과 일치하는 경우 일치하는 접두사가 가장 긴 규칙이 우선합니다. 동일한 CIDR 블록에 해당하는 항목은 중복으로 처리됩니다. 대조 목록 (exclusionList + IncludeList) 목록에서 이러한 중복 항목은 제거되며 제거될 정확한 중복 항목은 정의되지 않습니다.

  • inclusionList

    문자열[]

    터널에 대한 CIDR 표기법으로 IP 블록 목록에 대한 네트워크 트래픽을 포함합니다. 이 매개변수를 사용하여 분할 터널을 설정할 수 있습니다. 기본적으로 터널로 전달되는 트래픽은 없습니다. 이 목록에 '0.0.0.0/0' 항목을 추가하면 모든 사용자 트래픽이 터널로 리디렉션됩니다. 여러 규칙이 연결 대상과 일치하는 경우 일치하는 접두사가 가장 긴 규칙이 우선합니다. 동일한 CIDR 블록에 해당하는 항목은 중복으로 처리됩니다. 대조 목록 (exclusionList + IncludeList) 목록에서 이러한 중복 항목은 제거되며 제거될 정확한 중복 항목은 정의되지 않습니다.

  • mtu

    문자열 선택사항

    VPN 인터페이스의 MTU 설정 (기본값: 1500바이트)

  • 다시 연결

    문자열 선택사항

    Chrome 51 이상

    VPN 확장 프로그램이 자동 재연결을 구현하는지 여부입니다.

    true인 경우 linkDown, linkUp, linkChanged, suspend, resume 플랫폼 메시지가 각 이벤트를 알리는 데 사용됩니다. false인 경우 네트워크 토폴로지가 변경되면 시스템에서 VPN의 연결을 강제로 해제하므로 사용자가 수동으로 다시 연결해야 합니다. (기본값: false)

    이 속성은 Chrome 51에 새로 도입된 속성으로 이전 버전에서는 예외가 발생합니다. try/catch를 사용하면 브라우저 지원에 따라 이 기능을 조건부로 사용 설정할 수 있습니다.

PlatformMessage

enum은 플랫폼에서 클라이언트에 VPN 세션 상태를 알리는 데 사용됩니다.

열거형

"connected"
VPN 구성이 연결되었음을 나타냅니다.

"disconnected"
VPN 구성이 연결 해제되었음을 나타냅니다.

"error"
VPN 연결에서 오류(예: 시간 초과)가 발생했음을 나타냅니다. 오류에 관한 설명은 onPlatformMessage에 오류 인수로 제공됩니다.

"linkDown"
기본 물리적 네트워크 연결이 다운되었음을 나타냅니다.

"linkUp"
기본 실제 네트워크 연결이 백업되었음을 나타냅니다.

"linkChanged"
기본 실제 네트워크 연결(예: wifi->mobile)이 변경되었음을 나타냅니다.

"suspend"
OS에서 정지를 준비 중이므로 VPN에서 연결을 중단해야 함을 나타냅니다. 확장 프로그램이 정지 전에 이 이벤트 수신을 보장하지 않습니다.

"resume"
OS가 재개되었고 사용자가 다시 로그인하여 VPN에서 다시 연결을 시도해야 함을 나타냅니다.

UIEvent

enum은 플랫폼에서 onUIEvent를 트리거한 이벤트를 나타내는 데 사용됩니다.

열거형

"showAddDialog"
VPN 클라이언트가 사용자에게 구성 추가 대화상자를 표시하도록 요청합니다.

"showConfigureDialog"
VPN 클라이언트가 사용자에게 구성 설정 대화상자를 표시하도록 요청합니다.

VpnConnectionState

enum은 VPN 클라이언트가 플랫폼에 현재 상태를 알리는 데 사용합니다. 이렇게 하면 사용자에게 의미 있는 메시지를 제공하는 데 도움이 됩니다.

열거형

"connected"
VPN 연결이 성공했다고 지정합니다.

"failure"
VPN 연결이 실패했음을 지정합니다.

방법

createConfig()

프로미스 
chrome.vpnProvider.createConfig(
  name: string,
  callback?: function,
)

사용자의 여러 로그인 세션에서 유지되는 새 VPN 구성을 만듭니다.

매개변수

  • 이름

    string

    VPN 구성의 이름입니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (id: string)=>void

    • id

      string

      생성된 구성의 고유 ID 또는 실패 시 undefined.

반환 값

  • 프로미스<string>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

destroyConfig()

프로미스 
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
)

확장 프로그램에서 만든 VPN 구성을 폐기합니다.

매개변수

  • id

    string

    삭제할 VPN 구성의 ID입니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

notifyConnectionStateChanged()

프로미스 
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
)

VPN 세션 상태를 플랫폼에 알립니다. VPN 세션을 확장 프로그램에서 소유한 경우에만 성공합니다.

매개변수

  • VPN 클라이언트의 VPN 세션 상태입니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

sendPacket()

프로미스 
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
)

VPN 세션에 대해 생성된 터널을 통해 IP 패킷을 전송합니다. VPN 세션을 확장 프로그램에서 소유한 경우에만 성공합니다.

매개변수

  • 데이터

    ArrayBuffer

    플랫폼으로 전송될 IP 패킷입니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

setParameters()

프로미스 
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
)

VPN 세션의 매개변수를 설정합니다. 이는 플랫폼에서 "connected"를 수신한 직후에 호출해야 합니다. VPN 세션을 확장 프로그램에서 소유한 경우에만 성공합니다.

매개변수

  • 매개변수

    매개변수

    VPN 세션의 매개변수입니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

이벤트

onConfigCreated

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

확장 프로그램의 플랫폼에서 구성이 생성될 때 트리거됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

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

    • id

      string

    • 이름

      string

    • 데이터

      객체

onConfigRemoved

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

확장 프로그램에서 만든 구성이 플랫폼에서 삭제될 때 트리거됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (id: string)=>void

    • id

      string

onPacketReceived

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

확장 프로그램에서 소유한 VPN 세션의 터널을 통해 IP 패킷이 수신될 때 트리거됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (data: ArrayBuffer)=>void

    • 데이터

      ArrayBuffer

onPlatformMessage

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

확장 프로그램에서 소유한 VPN 구성에 대해 메시지가 플랫폼에서 수신될 때 트리거됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

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

onUIEvent

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

확장 프로그램의 UI 이벤트가 있을 때 트리거됩니다. UI 이벤트는 UI 대화상자를 사용자에게 표시해야 한다고 앱에 알리는 플랫폼의 신호입니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

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

    • event

      UIEvent

    • id

      문자열 선택사항