バックエンド

概要

クライアントがプレイス情報にアクセスできるようにするために提供される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 の実装は、リクエスト関数が戻り、アプリケーションコードがそれらのシグナルをスロットに接続する機会が得られるまで、リプライオブジェクトが発するシグナルが遅延されることを保証しなければならない。典型的なアプローチは、Qt::QueuedConnection でQMetaObject::invokeMethod() を使ってシグナルを出すことである。

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()シグナルを発するために使用されるかもしれません。これは、リプライを実装できる多くの方法の1つに過ぎません。

アイコンURL

アイコンURLは、QPlaceManagerEngine::constructIconUrl()関数を通して提供されます。期待される動作は、エンジンがQPlaceIcon::parameters() を使用して適切な URL を作成することです。検索や場所の詳細を取得するクエリからQPlace オブジェクトがマネージャーから返されると、エンジンは必要に応じてパラメータを正しく入力することが期待されます。

パラメータのキーと値はバックエンドが自由に選択できますが、バックエンドがアイコンごとに1つのURLしか持たない場合は、QPlaceIcon::SingleUrl をキーとして使用することをお勧めします。

カテゴリ

マネージャー・エンジンのカテゴリーは比較的静的なエンティティです。リモート・プレース・データストアにアクセスするエンジンでは、QPlaceManagerEngine::initializeCategories() が呼び出されるたびにサーバーに問い合わせるのではなく、カテゴリー構造をキャッシュすることが望ましいかもしれません。カテゴリがどの程度動的かにもよりますが、常に最も新しいカテゴリセットをダウンロードすることがより適切かもしれません。

マネージャーへの場所の保存

プレイスは一般的に、アイコンやカテゴリーといったマネージャー固有のデータを含んでいるため、そのままマネージャー間で直接保存することはできません。自分のマネージャーへの保存を容易にするために、エンジン実装者はQPlaceManagerEngine::compatiblePlace() 関数を実装する必要があります。この関数は、マネージャに保存できるように、必要に応じてプロパティを刈り込んだり変更したりした入力プレイスのコピーを返します。

例えば、連絡先の詳細がサポートされていない場合、互換プレースからは除外されます。また、特定のプロパティを変更することもあります。たとえば、元の場所のアイコンをバックエンドがアクセスできる場所にコピーまたはダウンロードしやすくするために、アイコンのパラメータを変更するなどです。

管理者間でのプレースメントの相互参照

時々、マネージャー間で場所を相互参照し、マッチさせたい場合があります。このような状況では、あるマネージャー（オリジンマネージャー）が場所への読み取り専用アクセスを提供し、別の2つ目のR/Wマネージャー（デスティネーションマネージャー）が最初のマネージャーから選択されたお気に入りを保存するために使用される場合があります。このような場合、オリジン・マネージャの検索中に、どのお気に入りがデスティネーション・マネージャに「お気に入り登録」されたかを知り、オリジナルのお気に入り名ではなく、カスタマイズされたお気に入り名を表示したいと思うかもしれません。

代替識別子の相互参照

相互参照を行うためには、元の場所とお気に入りされた場所の間にリンクが必要で、これは通常代替識別子属性によって処理されます。お気に入りの場所は、元の場所の識別子を持つ代替識別子属性を含んでいます。

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つの前提条件があります。1つ目は、オリジン・マネージャーはx_provider属性を提供し、その値はマネージャーのQGeoServiceProvider 。属性ラベルは空にしておくべきです。これは、属性がユーザーに表示されるべきではないことを示します。

もう一つは、保存先マネージャーのQPlaceManager::compatiblePlace() が、初期場所のx_provider 属性を使用し、保存する場所の代替識別子属性を設定することです。代替識別子属性のキーはx_id_<provider name> で、テキスト値は初期場所の識別子です。x_provider 属性は、互換性のある場所に渡してはならない。保存されるとき、保存された場所のx_providerは、保存先マネージャーとみなされます。

x_id_<provider 3つ目は、保存先マネージャのQPlaceManager::matchingPlaces() が、パラメータキーとしてQPlaceMatchRequest::AlternativeId を受け取り、値として代替識別子属性キーを受け取ることである。これは、QPlaceMatchRequest の場所の識別子が、x_id_<provider name> の代替識別子属性と照合されるべきであることを示している。

宛先マネージャが任意のマネージャからの保存と相互参照を容易にするのであれば、内部的に任意のキーと値のペアの保存に対応しなければならないことに注意してください。

その他のリンク方法

もしオリジン・マネージャーがプレースIDを提供しない場合、他の相互参照/マッチング手段を提供する必要があるかもしれません。一つの方法として、場所の座標を介して行うことが考えられます。もし、出発地マネージャの場所の座標が目的地マネージャの場所と同じか近い場合、それらは同じ場所である可能性が高くなります。この場合、マネージャーはQPlaceManager::matchingPlaces() を実装して、QPlaceMatchRequest で、パラメータキーに「proximity」、パラメータ値に2つの場所の一致を検出するために必要な距離を指定します。例えば、出発地の場所と目的地の場所が互いに50m以内であれば、同じ場所とみなすことができます。

しかし一般的には、上記のような代替識別子を使用して相互参照することが推奨される。

ユーザー可読拡張属性と非ユーザー可読拡張属性

ある属性がエンドユーザーによる読み取りを意図していない場合、その事実を示すラベルフィールドは空にしておくべきである。