nfcim / ndef

A Dart library to decode & encode NDEF records, supporting multiple types.

ndef

ndef is a Dart library to decode & encode NDEF records, supporting multiple types including (grouped by Type Name Format):

• NFC Well-known Records (TNF 1 / urn:nfc:wkt:), with:
  • Text (class T)
  • URI with well-known prefix (class U)
  • Digital signature (class Sig)
  • Smart poster (class Sp), including sub-record:
    • Action (class act)
    • Size (class s)
    • Type (class t)
  • Connection handover (class Hr/Hs/Hm/Hi/Hc/ac/cr)
• Media Records (TNF 2, containing MIME data), with:
  • Bluetooth easy pairing (class application/vnd.bluetooth.ep.oob)
  • Bluetooth low energy (class application/vnd.bluetooth.le.oob)
• Absolute URI Records (TNF 3)
• External Records (TNF 4 / urn:nfc:ext:), with:
  • Android application record (class android.com:pkg)

This library is still under active development and subject to breaking API changes and malfunction. Pull requests and issues are most welcomed, especially on:

• Bug fixes
• New support for other record types

Usage

import 'package:ndef/ndef.dart' as ndef;

// encoding
var uriRecord = new ndef.UriRecord.fromString("https://github.com/nfcim/ndef");
var textRecord = new ndef.TextRecord(text: "Hello");
var encodedUriRecord = uriRecord.encode().toHexString(); /// encode a single record, and use our extension method on [Uint8List]
var encodedAllRecords = ndef.encodeNdefMessage([uriRecord, textRecord]).toHexString(); // encode several records as a message

// decoding
var encodedTextRecord = "d1010f5402656e48656c6c6f20576f726c6421";
var decodedRecords = ndef.decodeRawNdefMessage(encodedTextRecord.toBytes());
assert(decodedRecords.length == 1);
if (decodedRecords[0] is ndef.TextRecord) {
  assert(decodeRecords[0].text == "Hello");
}  else {
  // we will not reach here
}

// data-binding (by implementing payload as dynamic getter / setter)
var origPayload = uriRecord.payload!;
print(origPayload.toHexString());
uriRecord.content = "github.com/nfcim/flutter_nfc_kit";
print(uriRecord.payload!.toHexString()); // changed
uriRecord.payload = origPayload;
print(uriRecord.content); // changed back

// decoding by providing parts of a record
var partiallyDecodedUrlRecord = ndef.decodePartialNdefMessage(ndef.TypeNameFormat.nfcWellKnown, utf8.encode("U"), origPayload, id: Uint8List.fromList([0x1, 0x2]));

See example code for a more complete example.

Refer to the documentation for detailed usage.

ndef's Issues

Reading AbsoluteURI record throws exception

I got an error when reading AbsoluteURIRecord

flutter: Invalid argument(s): AbsoluteURI record has no payload, don't set it
flutter:
#0      AbsoluteUriRecord.payload=
package:ndef/record/absoluteUri.dart:43
nfcim/flutter_nfc_kit#1      NDEFRecord.doDecode
package:ndef/record.dart:275
nfcim/flutter_nfc_kit#2      decodePartialNdefMessage
package:ndef/ndef.dart:42
nfcim/flutter_nfc_kit#3      NDEFRecordConvert.fromRaw
package:flutter_nfc_kit/flutter_nfc_kit.dart:147
nfcim/flutter_nfc_kit#4      FlutterNfcKit.readNDEFRecords.<anonymous closure>
package:flutter_nfc_kit/flutter_nfc_kit.dart:241
nfcim/flutter_nfc_kit#5      MappedListIterable.elementAt (dart:_internal[/iterable.dart:413:31]())
nfcim/flutter_nfc_kit#6      ListIterator.moveNext (dart:_internal[/iterable.dart:342:26]())
nfcim/flutter_nfc_kit#7      new _GrowableList._ofEfficientLengthIterable (dart:core-patch[/growable_array.dart:188:27]())
nfcim/flutter_nfc_kit#8      new _GrowableList.of (dart:core-patch[/growable_array.dart:150:28]())
nfcim/flutter_nfc_kit#9      new List.of (dart:core-patch[/array_patch.dart:51:28]())
nfcim/flutter_nfc_kit#10     ListIterable.toList (dart:_internal[/iterable.dart:213:44]())
nfcim/flutter_nfc_kit#11     FlutterNfcKit.readNDEFRecords
package:flutter_nfc_kit/flutter_nfc_kit.dart:242
<asynchronous suspension>
...

The issue is because NDEFRecord.doDecode set the payload after creating the record instance.

  static NDEFRecord doDecode(
      TypeNameFormat tnf, Uint8List type, Uint8List payload,
      {Uint8List? id,
      TypeFactory typeFactory = NDEFRecord.defaultTypeFactory}) {
    var record = typeFactory(tnf, utf8.decode(type));
    if (payload.length < record.minPayloadLength) {
      throw ArgumentError(
          "Payload length must be >= ${record.minPayloadLength}");
    }
    if (record.maxPayloadLength != null &&
        payload.length < record.maxPayloadLength!) {
      throw ArgumentError(
          "Payload length must be <= ${record.maxPayloadLength}");
    }
    record.id = id;
    record.type = type;
    // use setter for implicit decoding
    record.payload = payload;
    return record;
  }

And AbsoluteUriRecord has the following implementation:

//absoluteURI record has no payload
  Uint8List? get payload {
    return null;
  }

  set payload(Uint8List? payload) {
    throw ArgumentError("AbsoluteURI record has no payload, don't set it");
  }

I'm not sure how to fix the issue, as it either breaks the AbsoluteUri definition or there is some heavy rewriting needed on the NDEF decoding side.

flutter_nfc_kit broken with 0.3.3

In version 0.3.3 export 'utilities.dart'; was removed and this broke flutter_nfc_kit (all versions):

../../../.pub-cache/hosted/pub.dev/flutter_nfc_kit-3.3.3/lib/flutter_nfc_kit.dart:146:30: Error: The method 'toHexString' isn't defined for the class 'Uint8List'.
 - 'Uint8List' is from 'dart:typed_data'.
Try correcting the name to the name of an existing method, or defining a method named 'toHexString'.
    return NDEFRawRecord(id?.toHexString() ?? '', payload?.toHexString() ?? '',
                             ^^^^^^^^^^^
../../../.pub-cache/hosted/pub.dev/flutter_nfc_kit-3.3.3/lib/flutter_nfc_kit.dart:146:60: Error: The method 'toHexString' isn't defined for the class 'Uint8List'.
 - 'Uint8List' is from 'dart:typed_data'.
Try correcting the name to the name of an existing method, or defining a method named 'toHexString'.
    return NDEFRawRecord(id?.toHexString() ?? '', payload?.toHexString() ?? '',
                                                           ^^^^^^^^^^^
../../../.pub-cache/hosted/pub.dev/flutter_nfc_kit-3.3.3/lib/flutter_nfc_kit.dart:147:15: Error: The method 'toHexString' isn't defined for the class 'Uint8List'.
 - 'Uint8List' is from 'dart:typed_data'.
Try correcting the name to the name of an existing method, or defining a method named 'toHexString'.
        type?.toHexString() ?? '', this.tnf);
              ^^^^^^^^^^^
../../../.pub-cache/hosted/pub.dev/flutter_nfc_kit-3.3.3/lib/flutter_nfc_kit.dart:154:38: Error: The method 'toBytes' isn't defined for the class 'String'.
Try correcting the name to the name of an existing method, or defining a method named 'toBytes'.
        raw.typeNameFormat, raw.type.toBytes(), raw.payload.toBytes(),
                                     ^^^^^^^
../../../.pub-cache/hosted/pub.dev/flutter_nfc_kit-3.3.3/lib/flutter_nfc_kit.dart:154:61: Error: The method 'toBytes' isn't defined for the class 'String'.
Try correcting the name to the name of an existing method, or defining a method named 'toBytes'.
        raw.typeNameFormat, raw.type.toBytes(), raw.payload.toBytes(),
                                                            ^^^^^^^
../../../.pub-cache/hosted/pub.dev/flutter_nfc_kit-3.3.3/lib/flutter_nfc_kit.dart:155:58: Error: The method 'toBytes' isn't defined for the class 'String'.
Try correcting the name to the name of an existing method, or defining a method named 'toBytes'.
        id: raw.identifier == "" ? null : raw.identifier.toBytes());
                                                         ^^^^^^^
Target kernel_snapshot failed: Exception


FAILURE: Build failed with an exception.

I suggest adding back the export of the utilities, or at least a shrinked version with the extensions, so that flutter_nfc_kit (and possibly other packages depending on ndef) work again.

Thanks!

Updated dependencies needed

This package needs updated dependencies, e.g.

Because ndef >=0.3.0 depends on uuid ^3.0.4 and *** depends on uuid ^4.1.0, ndef >=0.3.0 is forbidden.

I forced the new uuid version and it works, so it should just be a matter of changing the number in the pybspec.yaml.

Null Safety Support

Add support for MAD sector

Could you also support reading of Mifare Application Directory MAD (sector 0), as it indicates the sector that contains NDEF record (AID==E103)?

(here is a handy video that explaines MAD in detail)

Null check error if no language set in text record

Language is nullable in TextRecord but it is null-checked later, resulting in an exception. The text property shows as correct, but payload is null.

ndef/lib/record/text.dart

Line 52 in 937be97

if (language!.length >= 64 || language.length <= 0) {