PlainApp
API 参考

配对

通过 app.capabilities 判断功能支持,通过 app.access 和宿主权限判断访问授权。示例使用合成数据,调用前请替换路径、ID、输入和筛选条件。

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

QR

QR payload

二维码:A 展示,B 扫描。局域网 c-id 为发送方;蓝牙使用独立传输。PAIR_CANCEL 为可选步骤。

悬停或点按字段
1 / 2

固定时间的合成快照;签名与 requestId 相互匹配。192.0.2.0/24 为文档示例地址;8443 为默认 HTTPS 端口,实际使用发现结果中的 port。请求有时效,不能原样重放。

在 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 }
}