PlainApp
API 參考

配對

透過 app.capabilities 判斷功能支援,透過 app.access 和主機權限判斷存取授權。範例使用合成值;呼叫前請替換路徑、ID、輸入和篩選條件。

Device A
plainapp://pair?request=<URL-encoded JSON>
Device B

QR

QR payload

QR 碼:A 顯示,B 掃描。區域網路的 c-id 識別傳送方;藍牙使用獨立傳輸。PAIR_CANCEL 為可選步驟。

將游標移至欄位或點按
1 / 2

固定時間的合成快照;簽章與 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 }
}