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

module device.nfc;

enum NFCErrorType {
  SECURITY,
  NOT_SUPPORTED,
  DEVICE_DISABLED,
  NOT_FOUND,
  INVALID_MESSAGE,
  OPERATION_CANCELLED,
  TIMER_EXPIRED,
  CANNOT_CANCEL,
  IO_ERROR
};

enum NFCRecordType {
  EMPTY,
  TEXT,
  URL,
  JSON,
  OPAQUE_RECORD
};

enum NFCPushTarget {
  // The target of a push operation must be the NFC tag.
  TAG,
  // The target of a push operation must be the NFC peer (device to device).
  PEER,
  // The target of a push operation must be either NFC tag or peer.
  ANY
};

enum NFCWatchMode {
  // Restricts scope of the watch operation. Only Web NFC messages must be
  // used by matching algorithm.
  WEBNFC_ONLY,
  // Allows performing watch operation for all NFC messages. For example, NFC
  // tags with valid NDEF messages.
  ANY
};

struct NFCError {
  NFCErrorType error_type;
};

struct NFCRecord {
  // The type of NFCRecord.
  NFCRecordType record_type;

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

  // Payload of the NFCRecord.
  array<uint8> data;
};

struct NFCMessage {
  // The body of the NFCMessage is a collection of NFCRecord objects.
  array<NFCRecord> data;

  // The |url| field is an ASCII serialized origin, optionally followed by a URL
  // path. It represents Web NFC id, that can be used for matching Web NFC
  // content with the filter specified by |url| field in NFCWatchOptions.
  string? url;
};

struct NFCPushOptions {
  // The target of the push operation.
  NFCPushTarget target;

  // The timeout for the push operation, in milliseconds.
  double timeout;

  // If the property is true, the push operation will suspend active watchers
  // until its completion.
  bool ignore_read;
};

struct NFCRecordTypeFilter {
  NFCRecordType record_type;
};

struct NFCWatchOptions {
  // Defines filtering constraint for NFC messages with specified |url|.
  string? url;

  // Defines filtering constraint for NFC records with specified record type.
  NFCRecordTypeFilter? record_filter;

  // Defines media type filtering constraint.
  string? media_type;

  // Defines mode of watch operation.
  NFCWatchMode mode;
};

interface NFC {
  // NFCClient interface is used to notify |client| when NFCMessage matches one
  // or more pending watch operations.
  SetClient(NFCClient client);

  // Pushes data to NFC device.
  // NFCPushOptions specify timeout and type of device where data should be
  // pushed. If timeout is defined and data is not pushed before timeout is
  // expired, callback with corresponding error is called.
  Push(NFCMessage message, NFCPushOptions? options) => (NFCError? error);

  // Cancels pending push request.
  CancelPush(NFCPushTarget target) => (NFCError? error);

  // Starts watching for nearby NFC devices with data that matches
  // NFCWatchOptions filtering criteria. On success, watch id is returned.
  Watch(NFCWatchOptions options) => (uint32 id, NFCError? error);

  // Cancels watch operation with provided id.
  CancelWatch (uint32 id) => (NFCError? error);

  // Cancels all watch operations.
  CancelAllWatches () => (NFCError? error);

  // Suspends all pending NFC operations. Could be used when web page
  // visibility or focus is lost.
  SuspendNFCOperations();

  // Resumes all suspended NFC operations.
  ResumeNFCOperations();
};

interface NFCClient {
  OnWatch(array<uint32> watch_ids, NFCMessage message);
};