How it works
SocialCard exposes a Java API. Your application calls methods on domain objects and on a reader service. Card operations go through PC/SC to the local reader.
Follow a URL through the code
Section titled “Follow a URL through the code”IReaderService.writeURI(uri) └─ ReaderService.encodeURI(uri) → NDefEncoder → NDefMessage └─ ReaderService.write(message) └─ ReaderRepository.write(message) ├─ TlvEncoder → bytes for tag storage ├─ PC/SC card channel → NTAG215 pages └─ ReaderRepository.read() → compare NDEF bytes1. Encode the record
Section titled “1. Encode the record”IReaderService.writeURI(uri) is a convenience method that calls write(encodeURI(uri)). ReaderService.encodeURI() delegates to NDefEncoder, which represents the input as a URI record and serializes it into an NDefMessage. This step works without hardware.
With multiple records, use NDefMessageCreator to add them in order. The encoder records which item starts and ends the message. The domain types validate their own input so invalid data can be caught before you talk to a reader.
2. Connect and pass the message to the repository
Section titled “2. Connect and pass the message to the repository”ReaderService manages the connection lifecycle. connect() opens a connection to the selected card, and write() checks that the service is connected before delegating to ReaderRepository. The repository uses the Smart Card I/O channel to exchange card commands through PC/SC.
3. Wrap the NDEF bytes for tag memory
Section titled “3. Wrap the NDEF bytes for tag memory”An NDefMessage holds the NDEF bytes alone. TlvEncoder adds the NDEF TLV type, a length and a terminator. The repository checks the tag’s capability container, which describes the available memory and access conditions. The bytes are then sized to the tag’s four-byte pages.
That is why message.data().length and the number of bytes used on the tag can differ. The factory NTAG215’s 496 bytes are shared with the TLV overhead.
4. Write in order and verify the result
Section titled “4. Write in order and verify the result”The repository temporarily marks the start of the tag data as an empty NDEF message. It writes the remaining pages and clears leftover bytes from a previously longer message. It writes the final first page last, then reads the message back and compares its NDEF bytes with the intended message.
If the tag is removed during a write, it can be left with an empty NDEF message. A later SocialCard write can use the stored page count to finish clearing affected pages. Applications should report the failure so the user can place the tag back on the reader and retry.
The read path
Section titled “The read path”ReaderRepository.read() reads the TLV and passes the bytes to TlvDecoder, which returns an NDefMessage. IReaderService.readContents() then uses NDefDecoder to reconstruct supported Java record types. readURIs() returns just the URI strings. This separation lets you encode or decode messages in tests without opening a card connection.
Where to look next
Section titled “Where to look next”- IReaderService defines the public read, write and connection methods.
- ReaderService handles reader selection and connection lifecycle.
- ReaderRepository handles the supported tag-memory layout and verification.
- Published 1.0.3 source archive contains the exact implementation described here.