Re: common NFC API draft / base for discussion

Sam,

I also want a high level complete API, but I don't think we should hide the
attributes of the NDEFRecord. The user should have access the tnf, type, id
and raw payload of any record.  These should probably be immutable.

Ideally most users will use NDEFRecordText, NDEFRecordURI, NDEFRecordMIME.
There will be cases where some users want to construct non-standard
NDEFRecords.  I propose that using attributes is clearer than using bytes,
since with attributes the user does not need to know anything about
NDEFMessage and NDEFRecord encoding.

To clarify my point about Android, Android does deal with NDEF, but it also
allows reading and writing bytes with tags like BlackBerry and Windows
Phone. I was attempting to illustrate that getBytes() and setBytes() belong
in NDEFMessage not NDEFRecord.

It would also be nice if we have a way for users to add new types like
NDEFRecordAAR or NDEFRecordFoo.

- Don


On Tue, Apr 16, 2013 at 10:06 AM, Samuel Ortiz <sameo@linux.intel.com>wrote:

> Hi Dan,
>
> On Mon, Apr 15, 2013 at 03:27:09PM -0400, Don Coleman wrote:
> > Here's some feedback based on the latest draft
> >
> > 9. NDEFRecord
> >
> > The binary representation of a NDEFRecord changes depending on the
> position
> > in the message, the length encoding, and chunking.
> For chunking and MB/ME bits, sure. And it would be left to the NDEFMessage
> constructor to set those bits appropriately. However, I'm really not sure
> we
> want to be really smart and decide when to start doing chunking or not.
> This
> really depends on platform specific limitations that we may not have access
> to.
>
> About length encoding, do you mean the SR bit ?
>
> > These are details that
> > are better left to NDEFMessage implementation rather than the NFEFRecord.
> >
> > I propose the following definition
> >
> > [Constructor(byte tnf, DOMString type, byte[] payload, DOMString id)]
> > interface NDEFRecord {
> >     byte tnf;
> >     DOMString type;
> >     byte[] payload;
> >     DOMString id;
> > }
> >
> > TNF is required. Type, payload and id should all be optional.
> >
> > This NDEFRecord definition will make it easier for people to implement
> > custom types like the TNF_External Android Application Record (AAR).
> I think your constructor proposition makes sense, as it would allow
> implementers to focus on the record payload and leave the header
> construction
> to the API implementation.
> However, exporting all those fields is something that needs to be
> discussed.
> Do we want to give the implementer access to thise kind of details, or do
> we
> want to focus on a high level yet complete API ? This is a design decision
> and
> I'm in favor of the latter. I may be completely wrong but I think HTML5 NFC
> app writer would prefer to not bother with understanding the difference
> between NDEF record IDs and types and thus this kind of details should be
> abstracted from them.
> For sure a small fraction of this API users will need and require this
> kind of
> details, and that's what they would get from the getRecordBytes() method.
> If
> they need low level, they most likely know how to parse an encoded NDEF
> record.
>
> If there is a real need (And I guess there is one) for an easy generation
> of e.g. AARs, then we can extend the API with an NDEFRecordAAR interface.
>
>
> > 8. NDEFMessage
> >
> > I'd like an NDEFMessage to be constructed with NDEFRecord[] or the byte[]
> > representation.
> I don't mind building an NDEFMessage from byte[].
>
>
> > Add getBytes() which would be responsible for encoding NDEFRecords.
> Sounds reasonable to me.
>
>
> > Android, Windows Phone and BlackBerry all deal with byte[] for reading
> and
> > writing NDEFMessages
> I may be confused, but as far as I understand Android reads and writes NDEF
> dealing with NdefMessage. Do I misunderstand your point here ?
>
>
> > Android constructs a NdefMessage with bytes[] or NdefRecord[]
> >
> http://developer.android.com/reference/android/nfc/NdefMessage.html#NdefMessage(byte[])
> >
> > Windows Phone write or share tag byte[] with
> > ProximityDevice.PublishBinaryMessage
> > http://msdn.microsoft.com/en-us/library/windows/apps/br241212.aspx
> >
> > BlackBerry Webworks (share byte[])
> > http://developer.blackberry.com/html5/api/blackberry.invoke.html#.invoke
> >
> > The BlackBerry NDK has more comprehensive NFC libraries
> >
> http://developer.blackberry.com/native/reference/bb10/nfc_libref/topic/manual/nfc_lib_nfc_conceptual_overview.html
> >
> > 6. NFCTag
> >
> > Consider adding optional meta data info? Tag Size, Tag Type, Technology
> > Type, Locked State, Lockable
> > This is not available on all platforms be would be nice to access when
> > available.
> Locked state and Lockable is something that could be useful, even UI wise.
> Maybe Tag Size as well.
> But for Tag type and Technology Type, I think we go back to the same
> question:
> Do we want to design an API for an easy general usage or do we want to
> export
> potentially confusing details for a few development apps to enjoy ? The way
> I'm asking this question is obviously biased, but it is a question worth
> answering in order to know where we want this API to go.
>
>
> > 12. NDEFRecordMIME
> >
> > NDEFRecordMIMEMedia may be a better name
> >
> > When the caller has a NDEFRecordMIME, the record (and message) will have
> > been parsed already. Can this return a byte[] instead of a NFCRequest?
> I would agree with that, but maybe I'm missing something that Luc is trying
> to address here.
>
> Thanks a lot for your input and comments.
>
> Cheers,
> Samuel.
>
> --
> Intel Open Source Technology Centre
> http://oss.intel.com/
>