HceManager

1. Architettura del sistema

HceManager implementa il profilo NFC Forum Type 4 Tag (T4T) su Android tramite HostApduService. Il dispositivo emula un tag NFC fisico senza hardware dedicato (Secure Element), rispondendo ai comandi APDU del lettore.

2. Ruoli: Trasmettitore vs Ricevitore

3. Protocollo NFC Forum Type 4 Tag (T4T)

Il protocollo T4T definisce una sequenza di comandi APDU che il lettore invia per leggere un messaggio NDEF da un tag (fisico o emulato via HCE).

4. Capability Container (CC File)

Il CC file è un blocco di 15 byte che il lettore legge per conoscere le caratteristiche del tag NDEF. I valori sono critici: valori errati causano link loss su Android 12/13.

5. API pubblica — HceManager

Metodi pubblici

Eventi

6. Flusso APDU dettagliato

Struttura del file NDEF in memoria (_ndefData[])

7. Configurazione Manifest B4A

Incollare nel Manifest Editor (Tools → Manifest Editor) dell'app Sender:

' ── Permesso NFC ──────────────────────────────────────────────
AddPermission(android.permission.NFC)

' ── Registrazione servizio HCE ─────────────────────────────────
' NOTA: AddApplicationText aggiunge dentro <application>
'       AddServiceText è per servizi B4A-compilati (NON usare qui)
AddApplicationText(
<service
    android:name="com.hce.wrapper.HceManager$HceService"
    android:exported="true"
    android:permission="android.permission.BIND_NFC_SERVICE">
    <intent-filter>
        <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE"/>
    </intent-filter>
    <meta-data android:name="android.nfc.cardemulation.host_apdu_service"
        android:resource="@xml/apduservice"/>
</service>)

' ── Descrittore AID (XML risorsa) ──────────────────────────────
' NOTA: namespace OBBLIGATORIO = schemas.android.com (NON android.com)
'       android:description richiede @string (NON testo letterale)
CreateResource(xml, apduservice.xml,
<host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
    android:description="@string/hce_description"
    android:requireDeviceUnlock="false">
    <aid-group android:description="@string/hce_aid_description" android:category="other">
        <aid-filter android:name="D2760000850101"/>
    </aid-group>
</host-apdu-service>)

' ── Stringhe (richieste per android:description) ───────────────
CreateResource(values, strings_hce.xml,
<resources>
    <string name="hce_description">HCE NFC Emulator</string>
    <string name="hce_aid_description">NFC Forum Type 4</string>
</resources>)

8. Codice B4A — Sender (HCE)

' ──────────────────────────────────────────────────────────────
' PROGETTO: HCE Sender
' Libreria richiesta: HceManager (HceManager.jar + HceManager.xml)
' ──────────────────────────────────────────────────────────────

Sub Process_Globals
    ' HceManager usa campi statici: dichiarare a livello di processo
    Private nfc As HceManager
End Sub

Sub Globals
    Dim lblStato   As Label
    Dim edtTesto   As EditText
    Dim btnTesto   As Button
    Dim btnUri     As Button
End Sub

Sub Activity_Create(FirstTime As Boolean)
    If FirstTime Then
        nfc.Initialize(Me, "nfc")
        nfc.SetTagText("Ciao da Android HCE!")   ' default
    End If
    ' ... (aggiunta viste UI) ...
End Sub

Sub Activity_Resume
    ' OBBLIGATORIO: evita il selettore di app ogni scansione
    nfc.SetAsPreferredService
End Sub

Sub Activity_Pause(UserClosed As Boolean)
    ' OBBLIGATORIO: rimuovere la preferenza in background
    nfc.UnsetPreferredService
End Sub

Sub btnTesto_Click
    nfc.SetTagText(edtTesto.Text)            ' Imposta Text Record
End Sub

Sub btnUri_Click
    nfc.SetTagUri(edtTesto.Text)             ' Imposta URI Record
End Sub

' ── Evento: lettore ha selezionato l'applicazione (step 1) ──
Sub nfc_OnReaderConnected
    lblStato.Text = "Lettore connesso!"
    Log("HCE: lettore connesso")
End Sub

' ── Evento: lettore ha letto tutto il file NDEF (step 6) ────
Sub nfc_OnMessageSent
    lblStato.Text = "Messaggio inviato!"
    Log("HCE: messaggio inviato")
End Sub

9. Codice B4A — Reader (NFC)

Manifest Reader: AddPermission(android.permission.NFC) + SetActivityAttribute(android:launchMode, singleTop)
Librerie: NFC + JavaObject (dipendenza obbligatoria della libreria NFC).

' ──────────────────────────────────────────────────────────────
' PROGETTO: NFC Reader
' Legge tag NFC fisici e tag emulati via HCE
' ──────────────────────────────────────────────────────────────

Sub Globals
    ' NFC è owner=activity → dichiarare in Globals
    Dim NFC      As NFC
    Dim lblStato As Label
    Dim lblTesto As Label
End Sub

Sub Activity_Create(FirstTime As Boolean)
    If NFC.IsSupported = False Then
        lblStato.Text = "NFC non disponibile" : Return
    End If
    If NFC.IsEnabled = False Then
        lblStato.Text = "NFC disabilitato" : Return
    End If
    ' Gestisce il caso in cui l'app è stata APERTA da un tag
    HandleIntent(Activity.GetStartingIntent)
End Sub

Sub Activity_Resume
    If NFC.IsSupported And NFC.IsEnabled Then
        NFC.EnableForegroundDispatch(Me)
    End If
End Sub

Sub Activity_Pause(UserClosed As Boolean)
    If NFC.IsSupported Then
        NFC.DisableForegroundDispatch(Me)
    End If
End Sub

' Chiamato quando un tag viene avvicinato con l'app già aperta
Sub Activity_NewIntent(Intent As Intent)
    HandleIntent(Intent)
End Sub

Sub HandleIntent(Intent As Intent)
    If Intent.IsInitialized = False Then Return
    If NFC.IsNdefIntent(Intent) = False Then
        lblStato.Text = "Tag rilevato (non NDEF)" : Return
    End If

    Dim records As List = NFC.GetNdefRecords(Intent)
    Dim sb As StringBuilder
    sb.Initialize

    For i = 0 To records.Size - 1
        Dim rec As NdefRecord       ' shortname della libreria NFC
        rec = records.Get(i)

        Dim testo As String = rec.GetAsTextType   ' "" se non è Text
        Dim uri   As String = rec.GetAsUriType    ' "" se non è URI

        If testo.Length > 0 Then
            sb.Append(testo)
        Else If uri.Length > 0 Then
            sb.Append(uri)
        Else
            Dim payload() As Byte = rec.GetPayload
            sb.Append("[HEX] ").Append(BytesToHex(payload))
        End If
    Next

    lblStato.Text = "Ricevuto! (" & records.Size & " record)"
    lblTesto.Text = sb.ToString
    Log("NFC: " & sb.ToString)
End Sub

Private Sub BytesToHex(data() As Byte) As String
    Dim sb As StringBuilder
    sb.Initialize
    For i = 0 To data.Length - 1
        Dim b As Int = Bit.AND(data(i), 0xFF)
        If b < 16 Then sb.Append("0")
        sb.Append(Bit.ToHexString(b)).Append(" ")
    Next
    Return sb.ToString.Trim
End Sub

10. Limitazioni e note importanti