API 參考
配對
透過 app.capabilities 判斷功能支援,透過 app.access 和主機權限判斷存取授權。範例使用合成值;呼叫前請替換路徑、ID、輸入和篩選條件。
Device A
plainapp://pair?request=<URL-encoded JSON>Device B
QR
QR payload
簽章演算法: Ed25519 · PAIR_REQUEST
signature = Base64(Ed25519-Sign(Device A private key, signed))Ed25519-Verify(Device A public key, signed, Base64Decode(signature))開啟 JSON 區段,即可檢視此合成範例的完整簽署輸入;接收方以簽署方的公開金鑰驗證簽章。雙方裝放在本機計算,不作為欄位傳輸;請比對所有八位數字,包括前導零。
verificationCode = 73939800digest = SHA256(request.signature encoded as UTF-8)digest (hex) = ff44f60497bc235899f050f272165ec094a2f2c685e776d153a0711424b85dc0number = first 8 digest bytes as an unsigned big-endian integerverificationCode = number mod 100000000, padded to 8 decimal digitsQR 碼:A 顯示,B 掃描。區域網路的 c-id 識別傳送方;藍牙使用獨立傳輸。PAIR_CANCEL 為可選步驟。
將游標移至欄位或點按
固定時間的合成快照;簽章與 requestId 相互符合。192.0.2.0/24 是文件專用位址。8443 為預設 HTTPS 連線埠;實際請求請使用探索到的連線埠。這些請求有時效,不能原樣重放。
在 PlainApp 桌面版管理新裝置或公開金鑰已變更的裝置時,請先明確選擇「信任」。這一步不會顯示核對碼,公開金鑰變更時會顯示警告。接下來,若未使用密碼,請先核對兩台裝置顯示的同一組驗證碼,再於受管理裝置上核准。若已使用密碼驗證,受管理裝置仍可能要求核准,但不顯示驗證碼。
型別定義
graphql
type Subscription {
peersChanged: Boolean!
pairingRequested: PairingRequestNotice!
pairingCompleted: PairingCompletedNotice!
pairingStarted: PairingProgressNotice!
pairingFailed: PairingProgressNotice!
pairingCanceled: PairingProgressNotice!
}
type Mutation {
cancelPairing(peerId: ID!): Boolean!
deletePeer(peerId: ID!): Boolean!
pairPeer(peerId: ID!, input: PairPeerInput!): Boolean!
respondToPairing(peerId: ID!, accepted: Boolean!): Boolean!
unpairPeer(peerId: ID!): Boolean!
}
type Query {
peerFileUrl(peerId: ID!, fileId: String!): String!
peers: [Peer!]!
}
enum DeviceType {
COMPUTER
PHONE
TABLET
TV
NAS
OTHER
}
scalar Instant
input PairPeerInput {
mode: PairingMode!
password: String
}
type PairingCompletedNotice {
deviceId: ID!
deviceName: String!
ip: String!
port: Int
deviceType: DeviceType
requestId: String
}
enum PairingErrorCode {
TIMEOUT
REJECTED
PASSWORD_REQUIRED
INVALID_PASSWORD
PEER_IDENTITY_CHANGED
TOO_MANY_LOGIN_ATTEMPTS
INTERNAL_ERROR
}
enum PairingMode {
CHAT
MANAGE
}
type PairingProgressNotice {
verificationCode: String
deviceId: ID!
deviceName: String!
error: PairingErrorCode
}
type PairingRequestNotice {
fromIp: String!
fromId: ID!
fromName: String!
deviceType: DeviceType!
verificationCode: String!
identityChanged: Boolean!
}
type Peer {
id: ID!
name: String!
ip: String!
status: PeerStatus!
port: Int
deviceType: DeviceType!
createdAt: Instant!
updatedAt: Instant!
online: Boolean!
managed: Boolean!
key: String!
publicKey: String!
token: String!
}
enum PeerStatus {
PAIRED
UNPAIRED
CHANNEL
}操作
subscription
peersChanged
接收對端記錄變更訊號。
graphql
subscription peersChanged {
peersChanged
}subscription
pairingRequested
接收等待接受或拒絕的裝置配對請求。
graphql
subscription pairingRequested {
pairingRequested { fromIp fromId fromName deviceType verificationCode identityChanged }
}subscription
pairingCompleted
接收裝置配對完成通知。
graphql
subscription pairingCompleted {
pairingCompleted { deviceId deviceName ip port deviceType requestId }
}subscription
pairingStarted
接收配對嘗試開始通知。
graphql
subscription pairingStarted {
pairingStarted { verificationCode deviceId deviceName error }
}subscription
pairingFailed
接收配對嘗試失敗通知。
graphql
subscription pairingFailed {
pairingFailed { verificationCode deviceId deviceName error }
}subscription
pairingCanceled
接收配對嘗試取消通知。
graphql
subscription pairingCanceled {
pairingCanceled { verificationCode deviceId deviceName error }
}mutation
cancelPairing
取消指定裝置目前進行中的配對。
graphql
mutation cancelPairing($peerId: ID!) {
cancelPairing(peerId: $peerId)
}mutation
deletePeer
刪除裝置及其一對一聊天記錄;頻道仍參照該裝置時保留頻道裝置記錄。
graphql
mutation deletePeer($peerId: ID!) {
deletePeer(peerId: $peerId)
}mutation
pairPeer
發起聊天配對或管理登入;傳回 true 表示已受理。
graphql
mutation pairPeer($peerId: ID!, $input: PairPeerInput!) {
pairPeer(peerId: $peerId, input: $input)
}mutation
respondToPairing
接受或拒絕該裝置待處理的配對請求或信任確認。
graphql
mutation respondToPairing($peerId: ID!, $accepted: Boolean!) {
respondToPairing(peerId: $peerId, accepted: $accepted)
}mutation
unpairPeer
在本機取消配對並清除管理權限,保留聊天記錄。
graphql
mutation unpairPeer($peerId: ID!) {
unpairPeer(peerId: $peerId)
}query
peerFileUrl
使用裝置目前儲存的位址產生檔案下載連結。
graphql
query peerFileUrl($peerId: ID!, $fileId: String!) {
peerFileUrl(peerId: $peerId, fileId: $fileId)
}query
peers
列出所有已儲存裝置,包括已配對、未配對及僅供頻道參照的記錄。
graphql
query peers {
peers { id name ip status port deviceType createdAt updatedAt }
}