플레이스 백엔드

개요

장소 정보에 액세스할 수 있도록 클라이언트에 제공되는 QPlaceManager 인터페이스는 QPlaceManagerEngine 의 구현에 직접적으로 의존합니다. 엔진은 관리자가 호출하는 백엔드 함수 구현을 제공합니다.

장소 백엔드 구현자는 QPlaceManagerEngine 에서 파생하여 해당 백엔드와 관련된 가상 함수에 대한 구현을 제공해야 합니다. 이러한 함수의 대부분은 비동기식이기 때문에 구현자는 적절한 응답 클래스도 파생해야 합니다. 응답 객체는 비동기 요청 관리를 담당하며 요청이 완료되면 이를 알리고 해당 요청의 결과를 보관하는 데 사용됩니다. QPlaceManagerEngine 은 모든 가상 함수에 대한 기본 구현을 제공합니다. 비동기 함수에 대한 기본 구현은 이벤트 루프를 통한 다음 반복에서 errorOccurred() 및 finished() 시그널을 방출하는 응답을 반환합니다.

응답 객체 구현/상속하기

응답 객체는 다음과 같이 상속됩니다:

class SearchReply : public QPlaceSearchReply
{
public:
    explicit SearchReply(ManagerEngine *engine)
        : QPlaceSearchReply(engine), m_engine(engine){}

    ~SearchReply();
    void setResults(const QList<QPlaceSearchResult> &results);
    void setRequest(const QPlaceSearchRequest &request);
    ...
    void triggerDone(QPlaceReply::Error error = QPlaceReply::NoError,
                     const QString &errorString = QString());

    ManagerEngine *m_engine;
};

QPlaceManagerEngine 구현은 요청 함수가 반환되고 애플리케이션 코드가 해당 신호를 슬롯에 연결할 기회를 가질 때까지 응답 객체에서 방출되는 모든 신호가 지연되도록 해야 합니다. 일반적인 접근 방식은 QMetaObject::invokeMethod()와 Qt::QueuedConnection 을 사용하여 신호를 방출하는 것입니다.

void SearchSuggestionReply::triggerDone(QPlaceReply::Error error,
                         const QString &errorString)
{
    if (error != QPlaceReply::NoError) {
        this->setError(error,errorString);
        QMetaObject::invokeMethod(m_engine, "errorOccurred", Qt::QueuedConnection,
                                  Q_ARG(QPlaceReply *,this),
                                  Q_ARG(QPlaceReply::Error, error),
                                  Q_ARG(QString, errorString));
        QMetaObject::invokeMethod(this, "errorOccurred", Qt::QueuedConnection,
                                  Q_ARG(QPlaceReply::Error, error),
                                  Q_ARG(QString, errorString));
    }

    this->setFinished(true);
    QMetaObject::invokeMethod(m_engine, "finished", Qt::QueuedConnection,
                              Q_ARG(QPlaceReply *,this));
    QMetaObject::invokeMethod(this, "finished", Qt::QueuedConnection);
}

오류가 발생하더라도 응답이 완료되면 항상 finished 신호가 전송되어야 하며, 즉 오류가 있으면 error 및 finished 신호가 모두 전송되고 오류가 없으면 finished 신호만 전송되어야 합니다.

QPlaceSearchReply::setResults() 및 QPlaceSearchReply::setRequest()의 보호된 함수는 플러그인이 결과와 요청을 할당할 수 있도록 공개적으로 액세스할 수 있도록 설정되어 있습니다. 이러한 함수는 공개적으로 내보내지 않기 때문에 접근성은 그다지 문제가 되지 않습니다. 다른 대안은 SearchReply에서 친구 클래스를 선언하는 것이었을 것입니다.

일반적으로 엔진 인스턴스는 응답의 parent 로 만들어집니다. 개발자가 완료 시 답글을 삭제하지 않으면 엔진이 삭제 시 답글을 정리할 수 있습니다. 일반적으로 답장에는 엔진에 대한 포인터 참조가 있으며, 이 포인터는 QPlaceManagerEngine::finished() 및 QPlaceManagerEngine::error() 신호를 보내는 데 사용될 수 있습니다. 이는 응답을 구현할 수 있는 여러 가지 방법 중 하나일 뿐입니다.

아이콘 URL

아이콘 URL은 QPlaceManagerEngine::constructIconUrl() 함수를 통해 제공됩니다. 예상되는 동작은 엔진이 QPlaceIcon::parameters()를 사용하여 적절한 URL을 구성하는 것입니다. 검색 또는 장소 세부 정보를 얻기 위한 쿼리를 통해 관리자로부터 QPlace 객체가 반환되면 엔진이 필요에 따라 매개 변수를 올바르게 채울 것으로 예상됩니다.

백엔드에서 매개변수 키와 값을 자유롭게 선택할 수 있지만, 아이콘당 하나의 URL만 있는 경우 QPlaceIcon::SingleUrl 을 키로 사용하는 것이 좋습니다.

카테고리

매니저 엔진의 카테고리는 비교적 정적인 엔티티이므로 원격지 데이터스토어에 액세스하는 엔진의 경우 QPlaceManagerEngine::initializeCategories()가 호출될 때마다 서버를 쿼리하는 대신 카테고리 구조를 캐시하는 것이 바람직할 수 있습니다. 카테고리가 얼마나 동적인지에 따라 항상 가장 최신의 카테고리 집합을 다운로드하는 것이 더 적절할 수도 있습니다.

매니저에 장소 저장하기

장소에는 아이콘 및 카테고리와 같은 관리자별 데이터가 포함되어 있기 때문에 일반적으로 관리자 간에 직접 저장할 수 없습니다. 자신의 매니저에게 쉽게 저장하기 위해 엔진 구현자는 QPlaceManagerEngine::compatiblePlace() 함수를 구현해야 합니다. 이 함수는 매니저에 저장할 수 있도록 필요에 따라 속성을 잘라내거나 수정한 입력 장소의 복사본을 반환합니다.

호환 가능한 장소를 만들려면 원래 장소의 특정 속성을 무시해야 할 수도 있습니다(예: 연락처 정보가 지원되지 않는 경우 호환 가능한 장소에서 제외됨). 백엔드에서 액세스할 수 있는 위치로 원래 장소의 아이콘을 쉽게 복사하거나 다운로드할 수 있도록 아이콘 매개변수를 수정하는 등 특정 속성을 수정하는 경우도 있습니다.

관리자 간 장소 상호 참조

관리자 간에 장소를 상호 참조하고 일치시키고자 하는 상황이 발생할 수 있습니다. 이러한 상황은 한 관리자가 장소에 대한 읽기 전용 액세스 권한을 제공하는 반면(원본 관리자), 다른 두 번째 관리자(대상 관리자)는 첫 번째 관리자에서 선택한 즐겨찾기를 저장하는 데 사용되는 경우 발생할 수 있습니다. 원점 관리자를 검색하는 동안 어떤 것이 목적지 관리자로 '즐겨찾기'되었는지 알고 싶을 수 있으며, 원래 이름 대신 사용자 지정한 즐겨찾기 이름을 표시할 수도 있습니다.

대체 식별자 상호 참조

상호 참조를 수행하려면 원래 장소와 즐겨찾는 장소 사이에 링크가 있어야 하며, 이는 일반적으로 대체 식별자 속성을 통해 처리됩니다. 즐겨찾는 장소에는 원래 장소의 식별자가 있는 대체 식별자 속성이 포함되어 있습니다.

origin R/O manager(here)       destination R/W manager (places_jsondb)
                        Save
Place id: ae246         --->    Place id: 0001
Attribute type: x_provider      Attribute type: x_id_here
Attribute value: here           Attribute text value: ae246

대체 식별자를 통한 상호 참조를 구현하기 위한 3가지 전제 조건이 있습니다. 첫 번째는 원본 관리자가 x_provider 속성을 제공해야 하며, 그 값은 관리자의 이름 QGeoServiceProvider 이어야 한다는 것입니다. 속성 레이블은 사용자에게 속성이 표시되지 않아야 함을 나타내는 비워 두어야 합니다.

두 번째는 대상 관리자의 QPlaceManager::compatiblePlace()가 초기 장소의 x_provider 속성을 사용하고 저장할 장소의 대체 식별자 속성을 설정하는 것입니다. 대체 식별자 속성의 키는 x_id_<provider 이름>이며 텍스트 값은 초기 장소의 식별자입니다. x_provider 속성은 호환되는 장소로 전달해서는 안 됩니다. 저장되면 저장된 장소의 x_provider가 대상 관리자로 간주됩니다.

세 번째는 대상 관리자의 QPlaceManager::matchingPlaces()가 QPlaceMatchRequest::AlternativeId 을 매개변수 키로 받아들이고 대체 식별자 속성 키를 값으로 받아들이는 경우입니다(이 경우 x_id_<provider 이름>이 예상되는 값입니다). 이는 QPlaceMatchRequest 에 있는 장소의 식별자가 x_id_<provider name> 대체 식별자 속성과 일치해야 함을 나타냅니다.

대상 관리자가 임의의 관리자에서 저장 및 상호 참조를 용이하게 하려면 공급자 이름을 미리 알 수 없고 ID가 어떤 구조가 될지 알 수 없으므로 내부적으로 임의의 키 값 쌍의 저장을 수용해야 한다는 점에 유의하세요.

다른 연결 방법

출처 관리자가 장소 ID를 제공하지 않는 경우, 다른 상호 참조/매칭 수단을 제공해야 할 수도 있습니다. 한 가지 방법은 장소 좌표를 사용하는 것인데, 출발지 관리자에 있는 장소의 좌표가 목적지 관리자에 있는 장소와 동일하거나 가까운 경우 같은 장소일 가능성이 높습니다. 이 경우 관리자는 QPlaceManager::matchingPlaces()를 구현하여 매개변수 키가 '근접'인 QPlaceMatchRequest 과 일치 여부를 감지하기 위해 두 장소가 있어야 하는 거리를 매개변수 값으로 설정할 수 있습니다. 예를 들어 출발지와 목적지가 서로 50m 이내인 경우 같은 장소로 간주할 수 있습니다.

그러나 일반적으로 위에서 언급한 대로 대체 식별자를 통해 상호 참조를 구현하는 것이 좋습니다.

사용자 읽기 가능 속성과 비사용자 읽기 가능 확장 속성 비교

최종 사용자가 읽을 수 없는 속성이라면 이 사실을 나타내는 표시로 라벨 필드를 비워 두어야 합니다.