services/device/public/mojom/nfc.mojom

// Copyright 2015 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module device.mojom;

enum NDEFErrorType {
  // No permission.
  NOT_ALLOWED,
  // No hardware support, no NFC adapter, the connection cannot be established,
  // or operation is not supported by the NFC Adapter.
  NOT_SUPPORTED,
  // NFC adapter is disabled.
  NOT_READABLE,
  INVALID_MESSAGE,
  OPERATION_CANCELLED,
  // Transfer data error.
  IO_ERROR
};

// https://w3c.github.io/web-nfc/#the-record-type-string
enum NDEFRecordTypeCategory {
  // Standardized well known types, including "empty", "text", "url",
  // "smart-poster", "absolute-url", "mime", and "unknown", etc.
  // https://w3c.github.io/web-nfc/#dfn-well-known-type-name
  kStandardized,

  // External types that follow the rule defined by
  // https://w3c.github.io/web-nfc/#dfn-external-type-name.
  kExternal,

  // Local types that follow the rule defined by
  // https://w3c.github.io/web-nfc/#dfn-local-type-name.
  kLocal
};

// Used to notify errors when pushing/watching.
struct NDEFError {
  NDEFErrorType error_type;

  // Detailed information about how/why the error happened.
  string error_message;
};

// https://w3c.github.io/web-nfc/#dom-ndefrecord
struct NDEFRecord {
  // The category |record_type| belongs to. This field is not exposed to JS, but
  // is used to transfer information internally and make code more readable.
  NDEFRecordTypeCategory category;

  // The type of NDEFRecord.
  // https://w3c.github.io/web-nfc/#the-record-type-string
  string record_type;

  // Represents the IANA media type of the NDEFRecord data field.
  string? media_type;

  // The id of NDEFRecord. https://w3c.github.io/web-nfc/#dom-ndefrecord-id
  string? id;

  // The encoding name used for encoding the payload in the case it is textual
  // data.
  string? encoding;

  // The language tag of the NDEFRecord payload in the case that was encoded.
  // Example: "en-US"
  string? lang;

  // Payload of the NDEFRecord.
  array<uint8> data;

  // This field may be set for some "smart-poster", external, or local type
  // records.
  // On the writing direction (passed from inside Blink), if this field is
  // non-null, |data| will be empty and the receiver is expected to make out the
  // payload raw bytes from this field.
  // On the reading direction (passed towards Blink), |data| always carries the
  // payload raw bytes, this field is non-null only if |data| can be parsed as
  // an NDEFMessage.
  NDEFMessage? payload_message;
};

// Mojo has a maximum size limit usually in megabytes for messages sent/received
// via message pipes, possibly like 256M or 128M.
//
// On the reading direction, the NDEFMessage is read from an NFC tag which can
// never have so large storage, so we'll never exceed the size limit above.
//
// On the writing direction, if the NDEFMessage input from users exceeds the
// limit, Mojo will raise a crash for the sender process, which is specifically
// the renderer process for our WebNFC impl.
struct NDEFMessage {
  // The body of the NDEFMessage is a collection of NDEFRecord objects.
  array<NDEFRecord> data;
};

struct NDEFWriteOptions {
  // Only the case of |overwrite| being |false| matters: the push operation will
  // read the NFC tag to determine if it has NDEF records on it, and if yes, do
  // not execute write.
  bool overwrite;
};

// Interface used by Web NFC to push data to NFC devices, make an NFC tag
// read-only, and get notified of nearby NFC devices.
interface NFC {
  // NFCClient interface is used to notify |client| when watching for nearby
  // NFC devices.
  SetClient(pending_remote<NFCClient> client);

  // Pushes data to NFC device.
  // NDEFWriteOptions specify options of the pending push operation.
  Push(NDEFMessage message, NDEFWriteOptions? options) => (NDEFError? error);

  // Cancels pending push request.
  CancelPush();

  // Make an NFC tag permanently read-only.
  MakeReadOnly() => (NDEFError? error);

  // Cancels pending make read-only request.
  CancelMakeReadOnly();

  // Starts watching for nearby NFC devices. |id| identifies each watch request
  // on the current Mojo connection.
  Watch(uint32 id) => (NDEFError? error);

  // Cancels watch operation with provided id.
  CancelWatch(uint32 id);
};

// Interface that client of the NFC interface must implement to get notified of
// nearby NFC devices.
interface NFCClient {
  // Sends |message| to those readers that have registered |watch_ids| via
  // NFC.Watch(), i.e. |message| matches their filtering criteria.
  // |serial_number| is the serial number of the nfc device used for
  // anti-collision and identification, or empty string in case none is
  // available.
  OnWatch(array<uint32> watch_ids, string? serial_number, NDEFMessage message);

  // Sends |error| to all readers that are trying to read some data from the nfc
  // tag coming nearby.
  OnError(NDEFError error);
};