웹 시리얼 API

requestPort() 메서드 단계는 다음과 같습니다:

1. promise를 새로운 Promise로 설정합니다.
2. this의 관련 전역 객체에 연결된 연관된 Document가 해당 정책 제어 기능 "serial"을 사용할 수 없다면, reject promise를 "SecurityError" DOMException와 함께 반환합니다.
3. 관련 전역 객체가 this와 연결되어 있고 임시 활성화가 없다면, reject promise를 "SecurityError" DOMException와 함께 반환합니다.
4. 만약 options["filters"]가 존재한다면, 각 filter에 대해 다음 단계를 수행합니다:
   1. 만약 filter["bluetoothServiceClassId"] 가 존재한다면:
      1. filter["usbVendorId"] 가 있으면, reject promise를 TypeError와 함께 반환합니다.
      2. filter["usbProductId"] 가 있으면, reject promise를 TypeError와 함께 반환합니다.
   2. 만약 filter["usbVendorId"]가 없다면, reject promise를 TypeError와 함께 반환합니다.
      참고

      이 검사 규칙은 SerialPortFilter가 비어 있을 수 없고 usbProductId가 지정되면, usbVendorId도 지정되어야 함을 의미합니다.
5. 다음 단계를 병렬로 실행합니다:
   1. allPorts를 빈 리스트로 설정합니다.
   2. 시스템에 등록된 각 Bluetooth 장치에 대해:
      1. 장치가 지원하는 각 BluetoothServiceUUID를 순회합니다:
         1. uuid가 차단된 Bluetooth 서비스 클래스 UUID가 아니면:
            • 또는 uuid가 시리얼 포트 프로파일 서비스 클래스 ID와 같거나,
            • options["allowedBluetoothServiceClassIds"]가 존재하고 포함한다면 uuid:
              1. port를 해당 Bluetooth 서비스에 해당하는 SerialPort로 생성합니다.
              2. 추가 port를 allPorts에 추가합니다.
   3. 각 Bluetooth가 아닌 시리얼 포트에 대해:
      1. port를 해당 포트를 나타내는 SerialPort로 설정합니다.
      2. 추가 port를 allPorts에 추가합니다.
   4. 사용자에게 사이트가 시리얼 포트에 접근할 수 있도록 허용할 것을 요청하며, allPorts 중 options["filters"]가 있을 시 필터와 일치하는 포트, 그렇지 않으면 모든 포트 목록을 표시합니다.
   5. 사용자가 포트를 선택하지 않은 경우, 전역 작업을 큐에 추가하여 관련 전역 객체에서 reject promise를 "NotFoundError" DOMException와 함께 반환하고 이 단계를 중단합니다.
   6. port를 사용자가 선택한 SerialPort로 설정합니다.
   7. 전역 작업을 큐에 추가하여 관련 전역 객체에서 resolve promise를 port와 함께 반환합니다.
6. promise를 반환합니다.

시리얼 포트는 사용 가능하려면 유선 시리얼 포트가 시스템에 물리적으로 연결되어 있거나, 무선 시리얼 포트가 해당 포트를 호스팅하는 무선 장치가 시스템에 등록되어 있는 경우입니다.

WebIDLdictionary SerialPortRequestOptions {
  sequence<SerialPortFilter> filters;
  sequence<BluetoothServiceUUID> allowedBluetoothServiceClassIds;
};

WebIDLdictionary SerialPortFilter {
  unsigned short usbVendorId;
  unsigned short usbProductId;
  BluetoothServiceUUID bluetoothServiceClassId;
};

getPorts() 메서드 단계는 다음과 같습니다:

1. promise를 새로운 Promise로 설정합니다.
2. this의 관련 전역 객체에 연결된 연관된 Document가 해당 정책 제어 기능 "serial"을 사용할 수 없다면, reject promise를 "SecurityError" DOMException와 함께 반환합니다.
3. 다음 단계를 병렬로 실행합니다:
   1. availablePorts를, 이전 requestPort() 호출 결과로 사용자가 사이트에 접근을 허락한 사용 가능한 시리얼 포트들의 시퀀스로 설정합니다.
   2. ports를, availablePorts에 해당하는 SerialPort의 시퀀스로 설정합니다.
   3. 전역 작업을 큐에 추가하여 관련 전역 객체에서 resolve promise를 ports와 함께 반환합니다.
4. promise를 반환합니다.

사용자가 이전에 requestPort()를 호출한 결과로 사이트가 접근을 허용받은 시리얼 포트가 논리적으로 연결되면, 다음 단계를 수행합니다:

1. port를 포트를 나타내는 SerialPort로 설정합니다.
2. port.[[connected]]를 true로 설정합니다.
3. 이벤트를 발송합니다. 이벤트 이름은 connect이고 대상은 port이며, bubbles 속성은 true로 초기화됩니다.

시리얼 포트가 논리적으로 연결되었다고 판단되는 경우는, 유선 시리얼 포트의 경우 시스템에 물리적으로 연결된 경우거나, 무선 시리얼 포트의 경우 시스템이 무선 장치(예: 활성 Bluetooth L2CAP 채널)에 적극적으로 연결된 경우입니다.

사용자가 이전에 requestPort()를 호출한 결과로 사이트가 접근을 허용받은 시리얼 포트가 더 이상 논리적으로 연결되어 있지 않다면, 다음 단계를 수행합니다:

1. port를 포트를 나타내는 SerialPort로 설정합니다.
2. port.[[connected]]를 false로 설정합니다.
3. 이벤트를 발송합니다. 이벤트 이름은 disconnect이고 대상은 port이며, bubbles 속성은 true로 초기화됩니다.

1. info를 빈 순서가 있는 맵으로 설정합니다.
2. 포트가 USB 장치의 일부라면, 다음 단계를 수행합니다:
   1. info["usbVendorId"]를 장치의 vendor ID 값으로 설정
   2. info["usbProductId"]를 장치의 product ID 값으로 설정
3. 포트가 Bluetooth 장치의 서비스라면, 다음 단계를 수행합니다:
   1. info["bluetoothServiceClassId"] 를 Bluetooth 서비스의 서비스 클래스 UUID로 설정
4. info를 반환합니다.

WebIDLdictionary SerialPortInfo {
  unsigned short usbVendorId;
  unsigned short usbProductId;
  BluetoothServiceUUID bluetoothServiceClassId;
};

open() 메서드 단계는 다음과 같습니다:

1. promise를 새로운 promise로 설정합니다.
2. this.[[state]]가 "closed"가 아니라면, promise를 "InvalidStateError" DOMException과 함께 reject 하고 promise를 반환합니다.
3. options["dataBits"]가 7 또는 8이 아니면, promise를 TypeError와 함께 reject 하고, promise를 반환합니다.
4. options["stopBits"]가 1 또는 2가 아니면, promise를 TypeError와 함께 reject 하고, promise를 반환합니다.
5. options["bufferSize"]가 0이면, promise를 TypeError와 함께 reject 하고, promise를 반환합니다.
6. 선택적으로, options["bufferSize"]가 구현체에서 지원 가능한 크기보다 크면, promise를 TypeError와 함께 reject 하고, promise를 반환합니다.
7. this.[[state]]를 "opening"으로 설정합니다.
8. 병렬로 다음을 수행합니다.
   1. 운영체제에 options에 명시된(또는 기본값인) 연결 파라미터를 사용해 시리얼 포트를 열도록 요청합니다.
   2. 실패할 경우, 글로벌 태스크를 큐잉하여 해당 전역 객체에서, serial port task source를 사용해 reject promise를 "NetworkError" DOMException과 함께 하고, 단계를 중단합니다.
   3. this.[[state]]를 "opened"로 설정합니다.
   4. this.[[bufferSize]]를 options["bufferSize"]로 설정합니다.
   5. 글로벌 태스크를 큐잉하여 해당 전역 객체에서, serial port task source를 사용해 resolve promise를 undefined와 함께 합니다.
9. promise를 반환합니다.

WebIDLdictionary SerialOptions {
  [EnforceRange] required unsigned long baudRate;
  [EnforceRange] octet dataBits = 8;
  [EnforceRange] octet stopBits = 1;
  ParityType parity = "none";
  [EnforceRange] unsigned long bufferSize = 255;
  FlowControlType flowControl = "none";
};

WebIDLenum ParityType {
  "none",
  "even",
  "odd"
};

WebIDLenum FlowControlType {
  "none",
  "hardware"
};

connected getter의 단계는 다음과 같습니다:

1. this.[[connected]]를 반환합니다.

readable getter 단계는 다음과 같습니다:

1. this.[[readable]]가 null이 아니면 this.[[readable]]를 반환한다.
2. this.[[state]]가 "opened"가 아니면, null을 반환한다.
3. this.[[readFatal]]이 true이면 null을 반환한다.
4. stream을 new ReadableStream으로 둔다.
5. pullAlgorithm을 다음 단계로 둔다:
   1. desiredSize를 하이 워터마크까지 채워넣을 바이트 수로 둔다 this.[[readable]]에 대하여.
   2. this.[[readable]]의 현재 BYOB 요청 뷰가 null이 아니면, desiredSize를 this.[[readable]]의 현재 BYOB 요청 뷰의 바이트 길이로 설정한다.
   3. 다음 단계를 병렬로 실행한다:
      1. OS에 포트에서 desiredSize 바이트까지 읽기 요청을 수행하여 결과를 바이트 시퀀스 bytes에 저장한다.
         Note

         this.[[state]] 가 "forgotten" 이 되면 포트가 연결 해제됨과 동일하게 처리해야 합니다.
      2. 글로벌 태스크 큐를 관련 글로벌 객체에 생성한 뒤, this의 serial port task source를 이용해 다음 단계를 수행한다:
         1. 오류가 없다면,
            1. this.[[readable]]의 현재 BYOB 요청 뷰가 null이 아니라면, bytes 를 this.[[readable]]의 현재 BYOB 요청 뷰에 기록하고, view를 this.[[readable]]의 현재 BYOB 요청 뷰로 둔다.
            2. 그 외에는, view를 bytes로부터 Uint8Array를 this의 관련 렐름에서 생성해 대입한다.
            3. view를 enqueue하여 this.[[readable]]에 추가한다.
         2. 버퍼 오버런 발생 시, error 호출, this.[[readable]]에 "BufferOverrunError" DOMException을 전달하고 읽기 스트림 닫기 처리 단계를 실행한다.
         3. 브레이크 조건 발생 시, error 호출, this.[[readable]]에 "BreakError" DOMException을 전달하고 읽기 스트림 닫기 처리 단계를 실행한다.
         4. 프레이밍 오류 발생 시, error 호출, this.[[readable]]에 "FramingError" DOMException을 전달하고 읽기 스트림 닫기 처리 단계를 실행한다.
         5. 패리티 오류 발생 시, error 호출, this.[[readable]]에 "ParityError" DOMException을 전달하고 읽기 스트림 닫기 처리 단계를 실행한다.
         6. 운영체제 오류 발생 시, error 호출, this.[[readable]]에 "UnknownError" DOMException을 전달하고, 읽기 스트림 닫기 처리 단계를 실행한다.
         7. 포트가 연결 해제됨이면, 다음을 실행한다:
            1. this.[[readFatal]]을 true로 설정
            2. error 호출, this.[[readable]]에 "NetworkError" DOMException을 전달한다.
            3. 읽기 스트림 닫기 처리 단계를 실행한다.
   4. undefined로 즉시 resolve된 promise를 반환한다.
   Note

   이 알고리즘에서 반환되는 Promise는 곧바로 resolve되어 스트림 취소를 차단하지 않습니다. [STREAMS]에서는 이 알고리즘이 청크가 enqueue될 때까지 다시 호출되지 않음을 명시합니다.

6. cancelAlgorithm을 다음 단계로 둔다:
   1. promise를 새 promise로 둔다.
   2. 다음 단계를 병렬로 수행한다.
      1. 운영체제에게 해당 포트의 모든 소프트웨어, 하드웨어 수신 버퍼 내용을 폐기하도록 요청한다.
      2. 글로벌 태스크 큐를 관련 글로벌 객체에 생성한 뒤, this의 serial port task source로 다음을 실행한다:
         1. 읽기 스트림 닫기 처리 단계를 실행한다.
         2. promise를 undefined로 resolve한다.
   3. promise를 반환한다.
7. 바이트 읽기 지원으로 stream 설정을 pullAlgorithm 을 pullAlgorithm로, cancelAlgorithm 을 cancelAlgorithm로, highWaterMark 를 this.[[bufferSize]]로 설정하여 stream을 구성한다.
8. this.[[readable]]를 stream으로 둔다.
9. stream을 반환한다.

1. this.[[readable]]를 null로 설정한다.
2. this.[[writable]]가 null이고 this.[[pendingClosePromise]]가 null이 아니면, resolve this.[[pendingClosePromise]]를 undefined로 한다.

writable getter 단계는 다음과 같습니다:

1. this.[[writable]]가 null이 아니면 this.[[writable]]를 반환한다.
2. this.[[state]]가 "opened"가 아니면 null을 반환한다.
3. this.[[writeFatal]]이 true이면 null을 반환한다.
4. stream을 새로운 WritableStream으로 둔다.
5. signal을 stream의 signal로 둔다.
6. writeAlgorithm을 다음 단계로 둔다. chunk가 주어졌을 때:
   1. promise를 새 promise로 둔다.
   2. 단언: signal이 aborted가 아니다.
   3. chunk가 BufferSource 타입의 IDL 값으로 변환될 수 없다면, promise를 TypeError와 함께 reject하고 promise를 반환한다. 그렇지 않으면, 변환 결과를 source에 저장한다.
   4. 버퍼 소스 복사본 가져오기로 source를 복사해 bytes에 저장한다.
   5. 병렬로 다음 단계를 실행한다:
      1. 운영체제에 bytes를 포트에 기록하라고 요청한다. 또는, 이후 병합을 위해 청크를 저장한다.
         참고

         운영체제는 bytes가 실제 전송된 후가 아니라 전송 대기열에 들어간 시점에 이 작업이 반환될 수도 있습니다.
         참고

         this.[[state]] 가 "forgotten"이 되면 포트가 연결 해제됨으로 처리되어야 합니다.
      2. 글로벌 태스크 큐를 관련 글로벌 객체 에 추가하고, this의 serial port task source로 다음 단계들을 실행한다:
         1. 청크가 성공적으로 기록되었거나, 이후 병합을 위해 저장된 경우 promise resolve promise에 undefined를 전달한다.
            참고

            [STREAMS]에서는 writeAlgorithm이 이전에 반환된 Promise가 resolve될 때만 다시 호출된다고 명시합니다. 효율성을 위해 구현은 여러 청크를 내부 큐에 쌓아 운영체제에 단일 요청으로 보내기 위해 Promise를 미리 resolve해도 됩니다.
         2. 운영체제 에러 발생 시, promise reject promise에 "UnknownError" DOMException을 전달한다.
         3. 포트가 연결 해제됨이면 다음을 실행한다:
            1. this.[[writeFatal]]을 true로 설정한다.
            2. promise reject promise에 "NetworkError" DOMException을 전달한다.
            3. 쓰기 스트림 닫기 처리 단계를 실행한다.
         4. signal이 aborted면 promise reject promise에 signal의 abort reason을 전달한다.
   6. promise를 반환한다.
7. abortAlgorithm을 다음과 같이 둔다:
   1. promise를 새 promise로 둔다.
   2. 다음 단계를 병렬로 실행한다.
      1. 운영체제가 포트의 모든 소프트웨어 및 하드웨어 전송 버퍼를 폐기하도록 한다.
      2. 글로벌 태스크 큐를 관련 글로벌 객체에 추가하고, this의 serial port task source로 다음 단계를 실행한다:
         1. 쓰기 스트림 닫기 처리 단계를 실행한다.
         2. promise resolve로 promise에 undefined를 전달한다.
   3. promise를 반환한다.
8. closeAlgorithm을 다음과 같이 둔다:
   1. promise를 새 promise로 둔다.
   2. 다음 단계를 병렬로 실행한다.
      1. 운영체제에 포트의 모든 소프트웨어 및 하드웨어 전송 버퍼를 비우도록 명령한다.
      2. 글로벌 태스크 큐를 관련 글로벌 객체에 추가하고, this의 serial port task source로 다음 단계를 실행한다:
         1. 쓰기 스트림 닫기 처리 단계를 실행한다.
         2. signal이 aborted라면 promise reject promise에 signal의 abort reason을 전달한다.
         3. 그 외에는 promise resolve로 promise에 undefined를 전달한다.
   3. promise를 반환한다.
9. stream 설정 stream에 writeAlgorithm을 writeAlgorithm으로, abortAlgorithm을 abortAlgorithm으로, closeAlgorithm을 closeAlgorithm으로, highWaterMark를 this.[[bufferSize]]로, sizeAlgorithm을 바이트 단위 사이즈 계산 알고리즘으로 설정한다.
10. 다음 abort 단계를 signal에 추가한다:
    1. 운영체제에 포트 쓰기 요청이 얼마나 데이터가 기록되었든 최대한 빨리 반환되게 한다.
11. this.[[writable]]를 stream으로 설정한다.
12. stream을 반환한다.

1. this.[[writable]]를 null로 설정한다.
2. this.[[readable]]가 null이고 this.[[pendingClosePromise]]가 null이 아니면, resolve this.[[pendingClosePromise]]를 undefined로 한다.

setSignals() 메서드의 단계는 다음과 같습니다:

1. promise를 새로운 promise로 둡니다.
2. this.[[state]]가 "opened"가 아니라면, promise를 "InvalidStateError" DOMException으로 reject하고 promise를 반환합니다.
3. signals에 지정된 멤버가 하나도 존재하지 않으면, promise를 TypeError로 reject하고 promise를 반환합니다.
4. 다음 단계들을 병렬로 수행합니다:
   참고

   원래는 signals에 명시된 변경사항이 원자적으로 적용되는 것이 이상적이지만, 이는 POSIX나 Windows API에서는 지원되지 않으며, 사용자 에이전트는 이러한 단계를 구현할 때 해당 API를 사용하게 됩니다. 따라서 아래에 나오는 순서가 실제 애플리케이션에서 의존되는 순서일 가능성이 높습니다.
   1. signals["dataTerminalReady"] 가 존재하면, 운영체제에 시리얼 포트의 "data terminal ready" 또는 "DTR" 신호를 assert(true일 때)하거나 deassert(false일 때)하도록 요청합니다.
   2. signals["requestToSend"]가 존재하면, 운영체제에 시리얼 포트의 "request to send" 또는 "RTS" 신호를 assert(true일 때)하거나 deassert(false일 때)하도록 요청합니다.
   3. signals["break"]가 존재하면, 운영체제에 시리얼 포트의 "break" 신호를 assert(true일 때)하거나 deassert(false일 때)하도록 요청합니다.
      참고

      "break" 신호는 일반적으로 송신선을 "mark" 전압에 고정하여 구현되며, assert되어 있는 동안 데이터 전송이 중단됩니다.
   4. 운영체제가 어떤 이유로든 이러한 신호의 상태 변경에 실패하면, 글로벌 태스크 큐를 관련 글로벌 객체에 생성하고, this의 serial port task source로 promise를 "NetworkError" DOMException으로 reject합니다.
   5. 글로벌 태스크 큐를 관련 글로벌 객체에 생성하고, this의 serial port task source로 resolve promise에 undefined를 전달합니다.
5. promise를 반환합니다.

WebIDLdictionary SerialOutputSignals {
  boolean dataTerminalReady;
  boolean requestToSend;
  boolean break;
};

1. promise를 새로운 promise로 둡니다.
2. this.[[state]]가 "opened"가 아니라면, promise를 "InvalidStateError" DOMException으로 reject하고 promise를 반환합니다.
3. 다음 단계들을 병렬로 수행합니다:
   1. 연결된 장치가 assert할 수 있는 제어 신호들의 상태를 운영체제에 쿼리합니다.
   2. 운영체제가 어떠한 이유로든 이러한 신호의 상태를 결정하지 못하면, 글로벌 태스크 큐를 관련 글로벌 객체에 생성하고, this의 serial port task source로 promise를 "NetworkError" DOMException으로 reject하며 이 단계를 중단합니다.
   3. "data carrier detect" 또는 "DCD" 신호가 장치에서 assert되었으면 dataCarrierDetect를 true, 아니면 false로 둡니다.
   4. "clear to send" 또는 "CTS" 신호가 assert되었으면 clearToSend를 true, 아니면 false로 둡니다.
   5. "ring indicator" 또는 "RI" 신호가 assert되었으면 ringIndicator를 true, 아니면 false로 둡니다.
   6. "data set ready" 또는 "DSR" 신호가 assert되었으면 dataSetReady를 true, 아니면 false로 둡니다.
   7. signals를 ordered map «[ "dataCarrierDetect" → dataCarrierDetect, "clearToSend" → clearToSend, "ringIndicator" → ringIndicator, "dataSetReady" → dataSetReady ]»로 둡니다.
   8. 글로벌 태스크 큐를 관련 글로벌 객체에 생성하고, this의 serial port task source로 resolve promise에 signals를 전달합니다.
4. promise를 반환합니다.

WebIDLdictionary SerialInputSignals {
  required boolean dataCarrierDetect;
  required boolean clearToSend;
  required boolean ringIndicator;
  required boolean dataSetReady;
};

close() 메서드의 단계는 다음과 같습니다:

1. promise를 새 promise로 둔다.
2. this.[[state]]가 "opened"가 아니면, promise를 "InvalidStateError" DOMException으로 reject하고 promise를 반환한다.
3. cancelPromise를 cancel을 this.[[readable]]에 호출한 결과값 또는 undefined로 resolve된 promise로 둔다. this.[[readable]]가 null일 경우.
4. abortPromise를 abort를 this.[[writable]]에 호출한 결과값 또는 undefined로 resolve된 promise로 둔다. this.[[writable]]가 null일 경우.
5. pendingClosePromise를 새 promise로 둔다.
6. this.[[readable]]와 this.[[writable]] 모두 null이면, pendingClosePromise를 undefined로 resolve한다.
7. this.[[pendingClosePromise]]를 pendingClosePromise로 설정한다.
8. combinedPromise를 여러 promise를 모두 기다리는 promise로서 «cancelPromise, abortPromise, pendingClosePromise»로 둔다.
9. this.[[state]]를 "closing"으로 둔다.
10. combinedPromise 반응으로 다음을 실행한다.
    • combinedPromise가 fulfilled일 경우:
      1. 다음 단계를 병렬로 실행한다:
         1. 시리얼 포트를 운영체제에 닫으라고 요청하고 관련 자원도 해제한다.
         2. this.[[state]] 를 "closed"로 둔다.
         3. this.[[readFatal]]와 this.[[writeFatal]]를 false로 둔다.
         4. this.[[pendingClosePromise]] 를 null로 둔다.
         5. 글로벌 태스크 큐 생성을 관련 글로벌 객체에 하고, this의 serial port task source로 promise resolve한다 promise값을 undefined로.
    • combinedPromise가 r로 reject된 경우:
      1. this.[[pendingClosePromise]] 를 null로 둔다.
      2. 글로벌 태스크 큐 생성을 관련 글로벌 객체에 하고, this의 serial port task source로 promise reject promise에 r을 전달한다.
11. promise를 반환한다.

forget() 메서드의 단계는 다음과 같습니다:

1. 사용자 에이전트가 이 동작을 수행할 수 없다면(예: 관리자가 허용한 권한일 때), undefined로 resolve된 promise를 반환한다.
2. 다음 단계를 병렬로 실행한다:
   1. this.[[state]]를 "forgetting"으로 설정한다.
   2. 기존에 requestPort() 호출 결과로 사이트에 접근 허가된 시리얼 포트 목록에서 this를 제거한다.
   3. this.[[state]]를 "forgotten"으로 설정한다.
   4. 글로벌 태스크 큐 생성을 관련 글로벌 객체에 하고 this의 serial port task source로 promise resolve에 promise를 undefined로 한다.
3. promise를 반환한다.

이 명세는 serial 속성이 Navigator 객체에 노출할 메서드의 사용 여부를 제어하는 기능을 정의합니다.

이 기능의 이름은 "serial"입니다.

이 기능에 대한 기본 허용 사용 목록(allowlist)은 'self'입니다.