RTCPeerConnection: phương thức setLocalDescription()

Cú pháp

setLocalDescription()
setLocalDescription(sessionDescription)

setLocalDescription(sessionDescription, successCallback, errorCallback) // deprecated

Tham số

sessionDescription Optional

Một đối tượng chỉ định cấu hình sẽ được áp dụng cho đầu cục bộ của kết nối. Nó nên chứa các thuộc tính sau:

type Optional

Chuỗi cho biết loại của mô tả phiên. Nếu bạn không cung cấp rõ một mô tả phiên, môi trường chạy WebRTC sẽ cố gắng xử lý đúng cách. Nếu trạng thái báo hiệu là stable, have-local-offer hoặc have-remote-pranswer, môi trường chạy WebRTC sẽ tự động tạo một offer mới và đặt nó làm mô tả cục bộ mới. Ngược lại, setLocalDescription() sẽ tạo một answer, và answer đó sẽ trở thành mô tả cục bộ mới.

sdp Optional

Chuỗi chứa SDP mô tả phiên. Nếu không cung cấp sdp, giá trị mặc định là chuỗi rỗng. Nếu type là "rollback", sdp phải là null hoặc chuỗi rỗng.

Nếu mô tả bị bỏ qua, môi trường chạy WebRTC sẽ cố tự làm điều đúng.

Bạn cũng có thể truyền một thể hiện RTCSessionDescription thực sự, nhưng không có khác biệt nào. Vì lý do này, hàm tạo RTCSessionDescription đã bị loại bỏ.

Trong mã và tài liệu cũ, bạn có thể thấy một phiên bản dựa trên callback của hàm này. Cách này đã bị loại bỏ và rất không nên dùng, vì nó sẽ bị xóa trong tương lai. Bạn nên cập nhật mọi mã hiện có để dùng phiên bản dựa trên Promise của setLocalDescription() thay thế. Các tham số của dạng cũ được mô tả dưới đây để hỗ trợ cập nhật mã hiện có.

successCallback Deprecated

Một Function của JavaScript không nhận tham số đầu vào, được gọi sau khi mô tả đã được đặt thành công. Lúc đó, offer có thể được gửi tới máy ngang hàng từ xa qua máy chủ báo hiệu.

errorCallback Deprecated

Hàm khớp với chữ ký RTCPeerConnectionErrorCallback, được gọi nếu mô tả không thể được đặt. Nó nhận một đối tượng DOMException duy nhất giải thích lý do yêu cầu thất bại.

Phiên bản lỗi thời này của phương thức trả về ngay lập tức mà không đợi việc đặt thực sự hoàn tất: nếu thành công, successCallback sẽ được gọi; nếu thất bại, errorCallback sẽ được gọi.

Giá trị trả về

Một Promise được thực thi khi giá trị của RTCPeerConnection.localDescription được thay đổi thành công hoặc bị từ chối nếu thay đổi không thể áp dụng (ví dụ, nếu mô tả được chỉ định không tương thích với một hoặc cả hai máy ngang hàng trong kết nối). Handler khi promise được thực thi không nhận tham số đầu vào.

Ngoại lệ lỗi thời

Khi dùng phiên bản dựa trên callback đã lỗi thời của setLocalDescription(), có thể xảy ra các ngoại lệ sau:

InvalidStateError DOMException Deprecated

Ném ra nếu signalingState của kết nối là "closed", cho biết kết nối hiện không mở nên không thể thương lượng.

InvalidSessionDescriptionError DOMException Deprecated

Ném ra nếu tham số sessionDescription không hợp lệ.

Ví dụ

Mô tả ngầm định

Một trong những lợi thế của dạng setLocalDescription() không có tham số là nó cho phép bạn đơn giản hóa đáng kể mã thương lượng. Đây gần như chỉ là những gì trình xử lý sự kiện negotiationneeded của bạn cần trông như thế nào. Chỉ cần thêm mã máy chủ báo hiệu, ở đây được biểu diễn bằng lời gọi signalRemotePeer().

pc.addEventListener("negotiationneeded", async (event) => {
  await pc.setLocalDescription();
  signalRemotePeer({ description: pc.localDescription });
});

Ngoài xử lý lỗi ra thì gần như chỉ có vậy!

Cung cấp offer hoặc answer của riêng bạn

Ví dụ dưới đây cho thấy việc triển khai trình xử lý cho sự kiện negotiationneeded tạo offer một cách rõ ràng, thay vì để setLocalDescription() tự làm việc đó.

async function handleNegotiationNeededEvent() {
  try {
    const offer = await pc.createOffer();
    pc.setLocalDescription(offer);
    signalRemotePeer({ description: pc.localDescription });
  } catch (err) {
    window.reportError(err);
  }
}

Đoạn này bắt đầu bằng việc tạo một offer bằng cách gọi createOffer(); khi thành công, chúng ta gọi setLocalDescription(). Sau đó, chúng ta có thể gửi offer vừa tạo tới máy ngang hàng còn lại bằng máy chủ báo hiệu, ở đây được thực hiện bằng cách gọi hàm signalRemotePeer().

Thông số kỹ thuật

Tương thích trình duyệt

Xem thêm

• WebRTC API
• RTCSessionDescription