Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

주석이 달린 URL

서식이 지정된 NFC 데이터 교환 형식(NDEF) 메시지를 읽습니다.

'주석이 달린 URL' 예제는 Qt NFC NFC 태그에서 읽은 특정 형식의 NFC 데이터 교환 형식(NDEF) 메시지 내용을 표시합니다. NDEF 메시지에는 URI 레코드, 선택 사항인 image/* MIME 레코드, 그리고 하나 이상의 지역화된 텍스트 레코드가 포함되어야 합니다.

다음은 예제의 초기 상태입니다:

주석이 달린 URL NFC 메인 화면

태그를 터치하면 해당 NDEF 내용이 표시됩니다. 다음은 텍스트 레코드와 URI 레코드를 포함하는 태그의 UI입니다:

주석이 달린 URL NFC 태그 세부 정보

화면을 탭하면 브라우저에서 해당 URL이 열립니다.

AnnotatedUrl 클래스 정의

AnnotatedUrl 클래스는 NFC 태그 감지 기능을 제공하는 QNearFieldManager 클래스를 래핑합니다. NDEF 메시지는 QNearFieldManager 에 의해 읽혀지며, AnnotatedUrl 클래스에 포함된 핸들러로 전달됩니다. NDEF 메시지를 파싱한 후, 이 클래스는 annotatedUrl() 신호를 발생시킵니다. UI는 이 신호에 반응하여 NDEF 메시지의 내용을 표시합니다.

class AnnotatedUrl : public QObject
{
    Q_OBJECT

public:
    explicit AnnotatedUrl(QObject *parent = 0);
    ~AnnotatedUrl();

    void startDetection();

signals:
    void annotatedUrl(const QUrl &url, const QString &title, const QPixmap &pixmap);
    void nfcStateChanged(bool enabled);
    void tagError(const QString &error);

public slots:
    void targetDetected(QNearFieldTarget *target);
    void targetLost(QNearFieldTarget *target);
    void handleMessage(const QNdefMessage &message, QNearFieldTarget *target);
    void handlePolledNdefMessage(QNdefMessage message);
    void handleAdapterStateChange(QNearFieldManager::AdapterState state);

private:
    QNearFieldManager *manager;
    QNdefFilter messageFilter;
};

참고: ` startDetection() ` 메서드는 UI와 NFC 관련 로직 간의 모든 연결이 설정될 때까지 실제 태그 감지를 연기하는 데 사용됩니다. 이는 NFC 태그를 터치하면 애플리케이션이 자동으로 시작되는 경우 중요합니다. 이러한 사용 사례는 현재 Android에서 지원됩니다.

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    MainWindow mainWindow;
    AnnotatedUrl annotatedUrl;

    QObject::connect(&annotatedUrl, &AnnotatedUrl::annotatedUrl,
                     &mainWindow, &MainWindow::displayAnnotatedUrl);
    QObject::connect(&annotatedUrl, &AnnotatedUrl::nfcStateChanged,
                     &mainWindow, &MainWindow::nfcStateChanged);
    QObject::connect(&annotatedUrl, &AnnotatedUrl::tagError,
                     &mainWindow, &MainWindow::showTagError);

    annotatedUrl.startDetection();
    mainWindow.show();

    return a.exec();
}

메시지 필터링

앞서 언급한 바와 같이, 이 애플리케이션은 특정 형식의 NDEF 메시지를 지원합니다. 올바른 메시지에는 다음 필드가 포함되어야 합니다.

  • 헤더로 사용될 NDEF 텍스트 레코드최소 하나.
  • 정확히 하나의 NDEF URI 레코드.
  • 아이콘이 포함된선택적 MIME 레코드.

레코드의 순서는 엄격하게 지정되어 있지 않습니다.

QNdefFilter 의 인스턴스를 사용하여 NDEF 메시지의 유효성을 확인합니다. 필터는 다음과 같이 설정됩니다:

    messageFilter.setOrderMatch(false);
    messageFilter.appendRecord<QNdefNfcTextRecord>(1, 100);
    messageFilter.appendRecord<QNdefNfcUriRecord>(1, 1);
    messageFilter.appendRecord(QNdefRecord::Mime, "", 0, 1);

수신된 메시지가 필터와 일치하지 않으면 오류 메시지가 표시됩니다:

주석이 달린 URL NFC 태그 데이터 보기

참고: NDEF Editor 예제애플리케이션을 사용하여 메시지 구조가 올바른 태그나 잘못된 태그를 생성할 수 있습니다.

AnnotatedUrl 핸들러 구현

QNearFieldManager 가 읽은 NFC 메시지는 AnnotatedUrl::handleMessage 로 전달됩니다.

void AnnotatedUrl::handleMessage(const QNdefMessage &message, QNearFieldTarget *target)
{

먼저 QNdefFilter::match() 메서드를 사용하여 메시지의 유효성을 검사합니다:

    if (!messageFilter.match(message)) {
        emit tagError("Invalid message format");
        return;
    }

메시지의 형식이 올바른 경우, 구문 분석이 계속 진행됩니다.

NFC 메시지는 여러 NDEF 레코드로 구성되어 있으므로, 모든 레코드를 순회함으로써 UI에 표시할 3가지 매개변수(Uri, Title, Pixmap)를 추출할 수 있습니다:

    for (const QNdefRecord &record : message) {
        if (record.isRecordType<QNdefNfcTextRecord>()) {
            QNdefNfcTextRecord textRecord(record);

            title = textRecord.text();
            QLocale locale(textRecord.locale());
        } else if (record.isRecordType<QNdefNfcUriRecord>()) {
            QNdefNfcUriRecord uriRecord(record);

            url = uriRecord.uri();
        } else if (record.typeNameFormat() == QNdefRecord::Mime &&
                   record.type().startsWith("image/")) {
            pixmap = QPixmap::fromImage(QImage::fromData(record.payload()));
        }

마지막으로 NFC 메시지의 매개변수를 추출한 후, UI에서 이를 처리할 수 있도록 해당 신호를 전송합니다.

    }

    emit annotatedUrl(url, title, pixmap);
}

어댑터 상태 처리

Android에서는 ` QNearFieldManager::adapterStateChanged()` 신호에 연결하여 어댑터 상태 변화를 감지할 수 있습니다. 이를 통해 NFC 어댑터가 비활성화되면 감지를 중지하고, 어댑터가 다시 활성화되면 감지를 재개할 수 있습니다. 이 방식은 ` AnnotatedUrl::handleAdapterStateChange ` 슬롯에 구현되어 있습니다.

void AnnotatedUrl::handleAdapterStateChange(QNearFieldManager::AdapterState state)
{
    if (state == QNearFieldManager::AdapterState::Online) {
        startDetection();
    } else if (state == QNearFieldManager::AdapterState::Offline) {
        manager->stopTargetDetection();
        emit nfcStateChanged(false);
    }
}

애플리케이션 자동 실행

Android는 NDEF 태그를 터치할 때 애플리케이션이 자동으로 시작되도록 지원합니다. Android 매니페스트 파일에 필요한 변경 사항에 대해서는 Android의Qt NFC 문서를 참조하십시오.

사용자 정의 AndroidManifest.xml을 도입하려면 빌드 시스템 측면에서 특별한 단계가 필요합니다.

qmake를 사용한 빌드

qmake를 사용할 경우, .pro 파일에 다음 내용을 추가해야 합니다:

android {
    ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android

    DISTFILES += \
        android/AndroidManifest.xml
}
CMake를 사용한 빌드

CMake를 사용할 경우, CMakeLists.txt 파일에 다음 내용을 추가해야 합니다:

if(ANDROID)
    set_property(TARGET annotatedurl
        APPEND PROPERTY QT_ANDROID_PACKAGE_SOURCE_DIR
        ${CMAKE_CURRENT_SOURCE_DIR}/android
    )
endif()

예제 실행

다음 경로에서 예제를 실행할 수 있습니다:

code.qt.io의 예제 프로젝트

참조 Qt NFC.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.