說明
使用 chrome.sockets.tcp
API 透過 TCP 連線透過網路傳送及接收資料。這個 API 會取代先前在 chrome.socket
API 中找到的 TCP 功能。
資訊清單
類型
CreateInfo
屬性
-
socketId
號碼
新建通訊端的 ID。請注意,透過此 API 建立的通訊端 ID 與透過其他 API (例如已淘汰的
[
socket](../socket/)
API) 建立的通訊端 ID 不相容。
DnsQueryType
DNS 解析偏好設定。預設值為 any
,且採用目前的 OS 設定,可能會傳回 IPv4 或 IPv6。ipv4
會強制使用 IPv4,ipv6
則會強制使用 IPv6。
列舉
"any"
"ipv4"
「ipv6」
ReceiveErrorInfo
屬性
-
resultCode
號碼
基礎網路呼叫傳回的結果代碼。
-
socketId
號碼
通訊端 ID。
ReceiveInfo
屬性
-
資料或曾存取這類資料的人員
ArrayBuffer
接收的資料,大小上限為
bufferSize
。 -
socketId
號碼
通訊端 ID。
SecureOptions
屬性
-
tlsVersion
SendInfo
屬性
-
bytesSent
數字 選填
傳送的位元組數量 (如果結果 == 0)
-
resultCode
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
SocketInfo
屬性
-
bufferSize
數字 選填
用於接收資料的緩衝區大小。如果沒有明確指定緩衝區大小,系統就不會提供該值。
-
已連線。
boolean
此標記可註明通訊端是否已連線至遠端對等節點。
-
localAddress
字串 選用
如果已連線基礎通訊端,則包含其本機 IPv4/6 位址。
-
localPort
數字 選填
如果已連接基礎通訊端,則包含其本機通訊埠。
-
名稱
字串 選用
與通訊端相關聯的應用程式定義字串。
-
已暫停
boolean
此標記可註明已連線通訊端是否阻止通訊端傳送更多資料 (請參閱
setPaused
)。 -
peerAddress
字串 選用
如果已連線至基礎通訊端,則包含對等/ IPv4/6 位址。
-
peerPort
數字 選填
如果已連接基礎通訊端,則包含對等通訊埠。
-
永久
boolean
此標記可註明應用程式暫停時,通訊端是否處於開啟狀態 (請參閱
SocketProperties.persistent
)。 -
socketId
號碼
通訊端 ID。
SocketProperties
屬性
-
bufferSize
數字 選填
用於接收資料的緩衝區大小。預設值為 4096。
-
名稱
字串 選用
與通訊端相關聯的應用程式定義字串。
-
永久
布林值 (選用)
此標記可表示當應用程式的事件頁面卸載時,通訊端是否處於開啟狀態 (請參閱「管理應用程式生命週期」)。預設值為「false」。應用程式載入時,可使用
getSockets
擷取先前以 persistent=true 開啟的任何通訊端。
TLSVersionConstraints
屬性
-
最高
字串 選用
-
分鐘
字串 選用
可接受的最低和最高版本傳輸層安全標準 (TLS) 版本。支援的值為
tls1.2
或tls1.3
。不再支援
tls1
和tls1.1
值。如果將min
設為其中一個值,系統會自動將該值限制為tls1.2
。如果將max
設為其中一個值或任何其他無法辨識的值,系統會自動忽略該值。
方法
close()
chrome.sockets.tcp.close(
socketId: number,
callback?: function,
)
關閉通訊端並釋放通訊端所繫結的位址/通訊埠。使用之後,建立的每個通訊端都應該關閉。呼叫函式後,通訊端 ID 就會立即失效。但是,通訊端保證只有在叫用回呼時才會關閉。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
connect()
chrome.sockets.tcp.connect(
socketId: number,
peerAddress: string,
peerPort: number,
dnsQueryType?: DnsQueryType,
callback: function,
)
將通訊端連接到遠端機器。connect
作業成功完成後,當從對等點接收資料時,就會引發 onReceive
事件。如果執行階段收到封包時發生網路錯誤,系統會引發 onReceiveError
事件,此時到呼叫 resume
方法之前,系統才會針對此通訊端發出其他 onReceive
事件。
參數
-
socketId
號碼
通訊端 ID。
-
peerAddress
字串
遠端機器的位址。系統支援 DNS 名稱、IPv4 和 IPv6 格式。
-
peerPort
號碼
遠端電腦的通訊埠。
-
dnsQueryType
DnsQueryType 選用
Chrome 103 以上版本地址解析度偏好設定。
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
-
create()
chrome.sockets.tcp.create(
properties?: SocketProperties,
callback?: function,
)
建立 TCP 通訊端。
參數
-
資源
通訊端屬性 (選用)。
-
回呼
函式選用
callback
參數如下所示:(createInfo: CreateInfo) => void
-
createInfo
通訊端建立的結果。
-
傳回
-
Promise<CreateInfo>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
disconnect()
chrome.sockets.tcp.disconnect(
socketId: number,
callback?: function,
)
拔除通訊端。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getInfo()
chrome.sockets.tcp.getInfo(
socketId: number,
callback?: function,
)
擷取指定通訊端的狀態。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:(socketInfo: SocketInfo) => void
-
socketInfo
包含通訊端資訊的物件。
-
傳回
-
Promise<SocketInfo>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getSockets()
chrome.sockets.tcp.getSockets(
callback?: function,
)
擷取應用程式擁有的通訊端清單。
參數
-
回呼
函式選用
callback
參數如下所示:(socketInfos: SocketInfo[]) => void
-
socketInfos
包含通訊端資訊的物件陣列。
-
傳回
-
Promise<SocketInfo[]>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
secure()
chrome.sockets.tcp.secure(
socketId: number,
options?: SecureOptions,
callback: function,
)
透過已連線的 TCP 用戶端通訊端啟動 TLS 用戶端連線。
參數
-
socketId
號碼
目前使用的現有已連線通訊端。
-
選項
TLS 連線的限制和參數。
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
-
send()
chrome.sockets.tcp.send(
socketId: number,
data: ArrayBuffer,
callback: function,
)
透過指定的 TCP 通訊端傳送資料。
參數
-
socketId
號碼
通訊端 ID。
-
資料或曾存取這類資料的人員
ArrayBuffer
要傳送的資料。
-
回呼
功能
callback
參數如下所示:(sendInfo: SendInfo) => void
-
sendInfo
send
方法的結果。
-
setKeepAlive()
chrome.sockets.tcp.setKeepAlive(
socketId: number,
enable: boolean,
delay?: number,
callback: function,
)
啟用或停用 TCP 連線的保持運作功能。
參數
-
socketId
號碼
通訊端 ID。
-
enable
boolean
如果為 true,請啟用保持運作功能。
-
delay
數字 選填
設定在最後一個資料封包接收到與第一次保持運作探測之間之間的延遲時間 (秒)。預設值為 0。
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
-
setNoDelay()
chrome.sockets.tcp.setNoDelay(
socketId: number,
noDelay: boolean,
callback: function,
)
設定或清除 TCP 連線的 TCP_NODELAY
。設定 TCP_NODELAY
後,系統就會停用 Nagle 的演算法。
參數
-
socketId
號碼
通訊端 ID。
-
noDelay
boolean
如果為 true,則會停用 Nagle 的演算法。
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
-
setPaused()
chrome.sockets.tcp.setPaused(
socketId: number,
paused: boolean,
callback?: function,
)
啟用或停用應用程式接收來自對等點的訊息。預設值為「false」。暫停通訊端通常用於應用程式,以限制其傳送的資料。當通訊端暫停時,不會發出 onReceive
事件。當通訊端連線並取消暫停時,接收訊息時會再次引發 onReceive
事件。
參數
-
socketId
號碼
-
已暫停
boolean
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
update()
chrome.sockets.tcp.update(
socketId: number,
properties: SocketProperties,
callback?: function,
)
更新通訊端屬性。
參數
-
socketId
號碼
通訊端 ID。
-
要更新的屬性。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
活動
onReceive
chrome.sockets.tcp.onReceive.addListener(
callback: function,
)
系統收到特定通訊端的資料時引發的事件。
參數
-
回呼
功能
callback
參數如下所示:(info: ReceiveInfo) => void
-
資訊
-
onReceiveError
chrome.sockets.tcp.onReceiveError.addListener(
callback: function,
)
當執行階段等待通訊端位址和通訊埠上的資料時,發生網路錯誤時引發事件。引發此事件後,通訊端會設為 paused
,不再針對此通訊端引發其他 onReceive
事件。
參數
-
回呼
功能
callback
參數如下所示:(info: ReceiveErrorInfo) => void