sendMessage(friendId:message:timeout:)

@discardableResult func sendMessage(friendId: String, message: String, timeout: TimeInterval = 10) async throws -> UInt32

Parameters

friendId

好友 Base58 ID

message

訊息內容（UTF-8）

timeout

等待 delivery receipt 的最長秒數。範圍 5～30 秒，預設 10 秒； 超出範圍不報錯、自動限制：大於 30 用 30，小於 5（含 0、負數）用 5； NaN 沒有大小可比，用預設的 10 秒

Return Value

對方裝置已收到時回傳 toxcore 分配的 messageId

Discussion

此方法會 await 直到兩種情況之一發生：

1. 對方裝置的 toxcore 收到封包並回 ACK → return messageId

2. 超過 timeout 秒數沒收到 ACK → throw .timeout(messageId:)

v0.17.0 起送出前不以 paths 預判可達性（契約 @invariant 3：bitmap 歸零期間 C 層 仍在重連）：送出前不檢查 isOnline，一律直接交給 C 層、由回傳碼決定成敗。 送出之後 paths 歸零則提前以 .timeout 收尾（見 handleFriendPathsChange）。

並行呼叫支援：多筆 sendMessage 可以並行呼叫，每筆獨立 await，互不影響。

接收端不去重：如果發送端 timeout 後重送，對方 toxcore 可能實際上已經收到第一筆， 導致對方 App 收到兩筆相同內容。去重邏輯由應用層在 message payload 中自行處理。

Throws

• FriendMessageError.invalidArgument — 好友不存在、ID 格式錯誤或訊息為空（C -1/-2）

• FriendMessageError.notInitialized — SDK 尚未初始化（C -4）

• FriendMessageError.friendNotReachable — 對方無可用 path（C -20，可重試）

• FriendMessageError.messageTooLong — 訊息過長（C -30）

• FriendMessageError.sendQueueFull — 發送佇列已滿（C -34，可重試）

• FriendMessageError.failed(code:) — C 層回傳未對映的錯誤碼

• FriendMessageError.timeout(messageId:) — 等待超過 timeout 秒數

• CancellationError — Revue.shared.destroy() 觸發 cancelAllPending

好友存在性不再由本方法預先檢查，一律交給 C 層判定（回 -2 → .invalidArgument）：原前置檢查 isFriendExists 需解析整份好友清單， 是 async 暫停點、多則併發時造成 msgId 亂序配發。