Back to Qt.io
Contact Us Blog Download Qt

주석이 달린 URL

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

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

이것이 예제의 초기 상태입니다:

태그를 터치하면 해당 NDEF 콘텐츠가 표시됩니다. 다음은 텍스트 레코드와 URI 레코드가 포함된 태그의 UI입니다:

화면을 탭하면 브라우저에서 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 태그가 터치되면 애플리케이션이 자동으로 시작될 때 중요합니다. 이러한 사용 사례는 현재 안드로이드에서 지원됩니다.

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);

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

참고: NDEF 편집기 예제 애플리케이션을 사용하여 메시지 구조가 올바르거나 잘못된 태그를 만들 수 있습니다.

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()

예제 실행하기

에서 예제를 실행하려면 Qt Creator에서 예제를 실행하려면 Welcome 모드를 열고 Examples 에서 예제를 선택합니다. 자세한 내용은 예제 빌드 및 실행하기를 참조하세요.

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

또한 Qt NFC.

© 2025 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.