webnfc.md

#API brainstorming

For next versions.

Now that p2p was dropped, here is a brain dump for an alternative API. For future development considerations.

[SecureContext, Exposed=Window]
interface NfcManager {
   attribute EventHandler onproximity;   // simple event for "some NFC tag is here"
   sequence<NfcTag> tags;  // get tag object(s) (from multiple adapters)
};

enum { "ndef", "nfc-a", ... "isodep", ... } NfcTechnology;

[SecureContext, Exposed=Window]
interface NfcTag {
   readonly attribute NfcTechnology tech;
    readonly attribute boolean connected;
   Promise<void> connect();  // start I/O with that tag
   Promise<void> close();  // release I/O resources
};

[SecureContext, Exposed=Window]
interface NDEFTag: NfcTag {
    readonly attribute boolean formattable;
   Promise<void> format(NDEFMessageSource message,  optional NfcFormatOptions options={});
   Promise<void> write(NDEFMessageSource message, optional NDEFWriteOptions options={});
   Promise<void> read(optional NDEFReadOptions options={});
   attribute EventHandler onerror;
   attribute EventHandler onreading;
};

// example other tech
[SecureContext, Exposed=Window]
interface NfcATag: NfcTag {
   Promise<void> transceive(BufferSource data, optional TransceiveOptions options);
   Promise<long> getMaxDataSize();
};

dictionary TransceiveOptions {
    AbortSignal? signal;
    long timeout;  // [ms], NFC specific timeout to be passed to impl
};

[SecureContext, Exposed=Window]
interface NDEFMessage {
  constructor(NDEFMessageInit messageInit);
  readonly attribute FrozenArray<NDEFRecord> records;
};

dictionary NDEFMessageInit {
  required sequence<NDEFRecordInit> records;
};

typedef (DOMString or BufferSource or NDEFMessageInit) NDEFRecordDataSource;

[SecureContext, Exposed=Window]
interface NDEFRecord {
  constructor(NDEFRecordInit recordInit);

  readonly attribute USVString recordType;
  readonly attribute USVString? mediaType;
  readonly attribute USVString? id;
  readonly attribute DataView? data;

  readonly attribute USVString? encoding;
  readonly attribute USVString? lang;

  sequence<NDEFRecord>? toRecords();
};

dictionary NDEFRecordInit {
  required USVString recordType;
  USVString mediaType;
  USVString id;

  USVString encoding;
  USVString lang;

  NDEFRecordDataSource data;
};

typedef (DOMString or BufferSource or NDEFMessageInit) NDEFMessageSource;


[SecureContext, Exposed=Window]
interface NDEFReadingEvent : Event {
  constructor(DOMString type, NDEFReadingEventInit readingEventInitDict);

  readonly attribute DOMString serialNumber;
  [SameObject] readonly attribute NDEFMessage message;
};

dictionary NDEFReadingEventInit : EventInit {
  DOMString? serialNumber = "";
  required NDEFMessageInit message;
};

dictionary NDEFPushOptions {
  boolean ignoreRead = true;
  boolean overwrite = true;
  AbortSignal? signal;
};

dictionary NDEFScanOptions {
  USVString id;
  USVString recordType;
  USVString mediaType;
  AbortSignal? signal;
};