#DeviceServices

DeviceServices is a global API on the main thread of App scripts. Do not import it from scripting or a Node package. It connects to a TCP endpoint and exchanges length-prefixed XML or binary property lists. Your script supplies the host, port and application messages. It does not establish TLS.

#Connect and exchange property lists

This complete example expects a plist echo service at the host and port you supply:

async function main() {
  const connection = await DeviceServices.connect({
    host: "192.168.1.10", // Replace with your service endpoint.
    port: 12345,
    timeout: 10000,
  })
  try {
    await connection.writePlist({
      Request: "Echo",
      Payload: new Uint8Array([1, 2, 3]),
      CreatedAt: new Date(),
    }, { format: "binary" })
    console.log(await connection.readPlist({ timeout: 10000 }))
  } finally {
    await connection.close()
  }
}
main().catch(console.error)

connect uses plain TCP. Each message has a four-byte big-endian length followed by an XML or binary plist. writePlist defaults to binary. Plist values support strings, finite numbers, booleans, Date, Uint8Array, arrays, and string-keyed objects. Null, undefined, unsafe integers, cyclic structures and functions are rejected. readPlist returns null for clean EOF before a new message; truncated or invalid messages reject and close the connection.

maximumFrameBytes defaults to 1 MiB and accepts 1024–8388608. Values are limited to 64 nesting levels and 16384 nodes. Deadlines are in milliseconds, default 30000, range 1–300000. An IO timeout or cancellation closes the connection; reconnect before retrying. Run one operation at a time per connection.

#Errors

Errors expose code, including ERR_DEVICE_CLOSED, ERR_DEVICE_BUSY, ERR_DEVICE_PROTOCOL, ERR_DEVICE_TIMEOUT, ERR_DEVICE_CANCELLED, ERR_DEVICE_FRAME_LIMIT, and ERR_INVALID_ARG_VALUE. Check error codes instead of localized messages. close() releases pending IO and remains available for cleanup.