說明
透過 chrome.sockets.tcpServer
API,使用 TCP 連線建立伺服器應用程式。這個 API 會取代先前在 chrome.socket
API 中找到的 TCP 功能。
資訊清單
類型
AcceptErrorInfo
屬性
-
resultCode
號碼
基礎網路呼叫傳回的結果代碼。
-
socketId
號碼
伺服器通訊端 ID。
AcceptInfo
屬性
-
clientSocketId
號碼
用戶端通訊端 ID,即新建立連線的通訊端 ID。這個通訊端 ID 只能與
chrome.sockets.tcp
命名空間中的函式搭配使用。請注意,用戶端通訊端一開始會暫停,應用程式必須明確取消暫停才能開始接收資料。 -
socketId
號碼
伺服器通訊端 ID。
CreateInfo
屬性
-
socketId
號碼
新建伺服器通訊端的 ID。請注意,透過此 API 建立的通訊端 ID 與透過其他 API (例如已淘汰的
[
socket](../socket/)
API) 建立的通訊端 ID 不相容。
SocketInfo
屬性
-
localAddress
字串 選用
如果通訊端正在監聽,請加入其本機 IPv4/6 位址。
-
localPort
數字 選填
如果通訊端正在監聽,則包含本機通訊埠。
-
名稱
字串 選用
與通訊端相關聯的應用程式定義字串。
-
已暫停
boolean
此標記可註明監聽通訊端的連線要求是否透過
onAccept
事件分派,還是排入監聽佇列待處理工作中。查看《setPaused
》。預設值為「false」。 -
永久
boolean
此標記表示當應用程式的事件頁面卸載時,通訊端是否保持開啟 (請參閱
SocketProperties.persistent
)。預設值為「false」。 -
socketId
號碼
通訊端 ID。
SocketProperties
屬性
-
名稱
字串 選用
與通訊端相關聯的應用程式定義字串。
-
永久
布林值 (選用)
此標記可表示當應用程式的事件頁面卸載時,通訊端是否保持開啟狀態 (請參閱「管理應用程式生命週期」)。預設值為「false」。應用程式載入時,可使用
getSockets
擷取先前以 persistent=true 開啟的任何通訊端。
方法
close()
chrome.sockets.tcpServer.close(
socketId: number,
callback?: function,
)
中斷連線並銷毀通訊端。使用之後,建立的每個通訊端都應該關閉。呼叫函式後,通訊端 ID 就會立即失效。但是,通訊端保證只有在叫用回呼時才會關閉。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
create()
chrome.sockets.tcpServer.create(
properties?: SocketProperties,
callback?: function,
)
建立 TCP 伺服器通訊端。
參數
-
資源
通訊端屬性 (選用)。
-
回呼
函式選用
callback
參數如下所示:(createInfo: CreateInfo) => void
-
createInfo
通訊端建立的結果。
-
傳回
-
Promise<CreateInfo>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
disconnect()
chrome.sockets.tcpServer.disconnect(
socketId: number,
callback?: function,
)
中斷監聽通訊端,例如停止接受新連線,並釋放通訊端所繫結的位址/通訊埠。通訊端 ID 仍然有效,例如可與 listen
搭配使用,以接受新通訊埠和位址的連線。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getInfo()
chrome.sockets.tcpServer.getInfo(
socketId: number,
callback?: function,
)
擷取指定通訊端的狀態。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:(socketInfo: SocketInfo) => void
-
socketInfo
包含通訊端資訊的物件。
-
傳回
-
Promise<SocketInfo>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getSockets()
chrome.sockets.tcpServer.getSockets(
callback?: function,
)
擷取應用程式擁有的通訊端清單。
參數
-
回呼
函式選用
callback
參數如下所示:(socketInfos: SocketInfo[]) => void
-
socketInfos
包含通訊端資訊的物件陣列。
-
傳回
-
Promise<SocketInfo[]>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
listen()
chrome.sockets.tcpServer.listen(
socketId: number,
address: string,
port: number,
backlog?: number,
callback: function,
)
監聽指定的通訊埠和位址的連線。如果通訊埠/地址正在使用中,回呼會指出失敗。
參數
-
socketId
號碼
通訊端 ID。
-
地址
字串
本機電腦的位址。
-
通訊埠
號碼
本機電腦的通訊埠。如果設為
0
,系統會動態選擇免費通訊埠。呼叫getInfo
即可找到動態分配的通訊埠。 -
待處理
數字 選填
通訊端的監聽佇列長度。預設值取決於作業系統 (SOMAXCONN),可確保大部分的應用程式都有合理的佇列長度。
-
回呼
功能
callback
參數如下所示:(result: number) => void
-
結果
號碼
基礎網路呼叫傳回的結果代碼。負值表示發生錯誤。
-
setPaused()
chrome.sockets.tcpServer.setPaused(
socketId: number,
paused: boolean,
callback?: function,
)
啟用或停用監聽通訊端,使其無法接受新連線。暫停時,監聽通訊端會接受新的連線,直到待處理工作 (請參閱 listen
函式) 完全用盡後,才會拒絕其他連線要求。只有在通訊端取消暫停時,才會引發 onAccept
事件。
參數
-
socketId
號碼
-
已暫停
boolean
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
update()
chrome.sockets.tcpServer.update(
socketId: number,
properties: SocketProperties,
callback?: function,
)
更新通訊端屬性。
參數
-
socketId
號碼
通訊端 ID。
-
要更新的屬性。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 121 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
活動
onAccept
chrome.sockets.tcpServer.onAccept.addListener(
callback: function,
)
連線至伺服器通訊端時引發的事件。
參數
-
回呼
功能
callback
參數如下所示:(info: AcceptInfo) => void
-
資訊
-
onAcceptError
chrome.sockets.tcpServer.onAcceptError.addListener(
callback: function,
)
當執行階段在通訊端位址和通訊埠上等待新連線時,發生網路錯誤時引發事件。引發這個事件後,通訊端會設為 paused
,而且在通訊端重新啟動前,通訊端不會再發出其他 onAccept
事件。
參數
-
回呼
功能
callback
參數如下所示:(info: AcceptErrorInfo) => void