Skip to content

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.

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 bytes

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.

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.

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.

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.