# `Dala.Hardware.NFC`
[🔗](https://github.com/manhvu/dala/blob/main/lib/dala/hardware/nfc.ex#L1)

NFC (Near Field Communication) tag reading.

Reads NDEF tags via the device's NFC reader. Requires the app to have
NFC entitlement (iOS) or `android.permission.NFC` (Android).

## Events

NFC events arrive as `handle_info` messages:

    handle_info({:nfc, :tag, %{tech: "Ndef", raw: "https://...", parsed: %{type: :url, value: "https://..."}}}, socket)
    handle_info({:nfc, :error, %{reason: "NFC is disabled"}}, socket)

The `parsed` field is produced by `Dala.Ui.Scan.parse/1` and contains a
structured representation of the payload. See `Dala.Ui.Scan` for all
supported formats (URL, WiFi, contact, email, phone, geo, text, calendar).

## Platform notes

- **iOS**: Uses `NFCNDEFReaderSession`. The system UI is shown automatically.
  Requires `NFCReaderUsageDescription` in Info.plist and the Near Field
  Communication Tag Reading capability.
- **Android**: Uses `NfcAdapter` foreground dispatch. The hosting Activity
  must forward `onNewIntent` to `DalaBridge.handleNFCIntent(intent)`.
  Requires `android.permission.NFC` in AndroidManifest.xml.

## Usage

    # Start scanning
    Dala.Hardware.NFC.start_scan(socket, message: "Hold near a tag")

    # Stop scanning
    Dala.Hardware.NFC.stop_scan(socket)

    # Check availability
    Dala.Hardware.NFC.available?()

## Parsing tag payloads

Use `Dala.Ui.Scan.parse/1` to decode the raw payload into a structured format:

    def handle_info({:nfc, :tag, %{raw: raw} = tag}, socket) do
      case Dala.Ui.Scan.parse(raw) do
        %{type: :url, value: url} ->
          # Open URL
        %{type: :wifi, value: %{ssid: ssid, password: pw}} ->
          # Connect to WiFi
        %{type: :text, value: text} ->
          # Plain text
      end
      {:noreply, socket}
    end

# `available?`

```elixir
@spec available?() :: boolean()
```

Check if NFC is available and enabled on this device.

# `start_scan`

```elixir
@spec start_scan(
  Dala.Socket.t(),
  keyword()
) :: Dala.Socket.t()
```

Start an NFC scan. The OS presents the scanning UI.

Options:
  - `message: String.t` — prompt shown in the iOS NFC scanner UI
    (default: "Hold near an NFC tag"). Ignored on Android.

Tag reads arrive as `{:nfc, :tag, %{tech: String.t, raw: String.t, parsed: map}}`.
The `parsed` field is `nil` if the payload format is not recognized by `Dala.Ui.Scan.parse/1`.
Errors arrive as `{:nfc, :error, %{reason: String.t}}`.

# `stop_scan`

```elixir
@spec stop_scan(Dala.Socket.t()) :: Dala.Socket.t()
```

Stop the active NFC scan. Dismisses the iOS scanner UI.

---

*Consult [api-reference.md](api-reference.md) for complete listing*