En esta página

Servicio de fondo de «Lugares»

Descripción general

La interfaz ` QPlaceManager `, que se proporciona a los clientes para permitir el acceso a la información de los lugares, depende directamente de una implementación de ` QPlaceManagerEngine`. El motor proporciona las implementaciones de las funciones del backend que son llamadas por el gestor.

Quien implemente un backend de lugares debe derivar de ` QPlaceManagerEngine ` y proporcionar implementaciones para las funciones virtuales relevantes para su backend. La mayoría de estas funciones son asíncronas, por lo que los implementadores también deberán derivar las clases de respuesta adecuadas. Los objetos de respuesta se encargan de gestionar una solicitud asíncrona; se utilizan para notificar cuándo se ha completado una solicitud y para almacenar los resultados de dicha solicitud. QPlaceManagerEngine proporciona una implementación por defecto para todas las funciones virtuales. Las implementaciones por defecto de las funciones asíncronas devuelven una respuesta que emitirá las señales errorOccurred() y finished() en la siguiente iteración del bucle de eventos.

Implementación y herencia de objetos de respuesta

Un objeto de respuesta se heredaría de la siguiente manera:

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

La implementación de un ` QPlaceManagerEngine ` debe garantizar que cualquier señal emitida por los objetos de respuesta se retrase hasta que las funciones de solicitud hayan devuelto un resultado y el código de la aplicación haya tenido la oportunidad de conectar dichas señales a las ranuras. El enfoque habitual consiste en utilizar ` QMetaObject::invokeMethod()` junto con un ` Qt::QueuedConnection ` para emitir las señales.

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

Tenga en cuenta que las señales de ` finished ` siempre deben emitirse cuando se completa una respuesta, incluso si se ha producido un error; es decir, si hay un error, deben emitirse tanto la señal ` error ` como la ` finished `, mientras que, si no hay error, solo se emite la señal ` finished `.

Las funciones protegidas QPlaceSearchReply::setResults() y QPlaceSearchReply::setRequest() se hacen de acceso público para que el complemento pueda asignar resultados y solicitudes. Dado que estas funciones no se exportan públicamente, el acceso no supone un gran problema. Una alternativa habría sido declarar una clase amiga en SearchReply.

Normalmente, la instancia del motor se convertiría en el ` parent ` de la respuesta. Si el desarrollador no descarta las respuestas al finalizar, el motor puede limpiarlas al destruirse. Normalmente, la respuesta también tiene una referencia de puntero al motor, que puede utilizarse para emitir las señales QPlaceManagerEngine::finished() y QPlaceManagerEngine::error(). Esta es solo una de las muchas formas en que se podría implementar la respuesta.

URL de iconos

Las URL de los iconos se proporcionan a través de la función QPlaceManagerEngine::constructIconUrl(). El comportamiento esperado es que el motor utilice QPlaceIcon::parameters() para construir una URL adecuada. Cuando el gestor devuelve un objeto QPlace, ya sea a raíz de una búsqueda o de una consulta para obtener detalles de un lugar, se espera que el motor rellene correctamente los parámetros según sea necesario.

El backend es libre de elegir cuáles son la clave y los valores de los parámetros; sin embargo, si un backend solo tiene una URL por icono, se recomienda utilizar QPlaceIcon::SingleUrl como clave.

Categorías

Las categorías de un motor de gestión son entidades relativamente estáticas; para los motores que acceden a almacenes de datos de lugares remotos, puede ser conveniente almacenar en caché la estructura de categorías en lugar de consultar un servidor cada vez que se llama a ` QPlaceManagerEngine::initializeCategories()`. Dependiendo de lo dinámicas que sean las categorías, puede resultar más adecuado descargar siempre el conjunto de categorías más actualizado.

Guardar lugares en el gestor

Por lo general, un lugar no se puede guardar directamente entre gestores tal cual, ya que contiene datos específicos del gestor, como iconos y categorías. Para facilitar el almacenamiento en el propio gestor, los implementadores del motor deben implementar la función QPlaceManagerEngine::compatiblePlace(). Esta función devuelve una copia del lugar de entrada con las propiedades eliminadas o modificadas según sea necesario, de modo que la copia se pueda guardar en el gestor.

La creación de un lugar compatible puede implicar ignorar ciertas propiedades del lugar original; por ejemplo, si no se admiten los datos de contacto, estos se omiten en el lugar compatible. En otras ocasiones, puede implicar modificar ciertas propiedades, como por ejemplo ajustar los parámetros del icono para facilitar la copia o descarga del icono del lugar original a una ubicación a la que el backend pueda acceder.

Referencias cruzadas entre gestores

En ocasiones puede darse una situación en la que deseemos establecer referencias cruzadas y hacer coincidir lugares entre gestores. Tal situación puede darse cuando un gestor proporciona acceso de solo lectura a los lugares (gestor de origen), mientras que se utiliza un segundo gestor de lectura/escritura (gestor de destino) para guardar los favoritos seleccionados del primero. Durante una búsqueda en el gestor de origen, es posible que queramos saber cuáles se han marcado como «favoritos» en el gestor de destino y, tal vez, mostrar el nombre personalizado del favorito en lugar del nombre original.

Referencias cruzadas mediante identificadores alternativos

Para llevar a cabo la referencia cruzada, debe existir un vínculo entre el lugar original y el lugar marcado como favorito, lo que normalmente se gestiona mediante un atributo de identificador alternativo. El lugar marcado como favorito contiene un atributo de identificador alternativo que incluye el identificador del lugar original.

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

Existen tres requisitos previos para implementar las referencias cruzadas mediante un identificador alternativo. El primero es que el gestor de origen debe proporcionar el atributo x_provider con el valor correspondiente al nombre del gestor ( QGeoServiceProvider). La etiqueta del atributo debe dejarse vacía, lo que indica que el atributo no debe mostrarse a los usuarios.

Nota: Por lo general,se espera que todos los gestores establezcan el atributo x_provider.

La segunda es que el gestor de destino QPlaceManager::compatiblePlace() utilice el atributo x_provider del lugar inicial y establezca un atributo de identificador alternativo del lugar que se va a guardar. La clave del atributo de identificador alternativo es x_id_<provider name> y el valor de texto es el identificador del lugar inicial. El atributo x_provider no debe pasarse al lugar compatible. Al guardarse, se considera que el x_provider del lugar guardado es el gestor de destino.

La tercera es que QPlaceManager::matchingPlaces() del gestor de destino acepte QPlaceMatchRequest::AlternativeId como clave de parámetro y la clave del atributo de identificador alternativo como valor; en este caso, x_id_<provider nombre> sería el valor esperado. Esto indica que los identificadores de los lugares en QPlaceMatchRequest deben cotejarse con los atributos de identificador alternativo x_id_<provider nombre>.

Tenga en cuenta que, si el gestor de destino debe facilitar el almacenamiento y las referencias cruzadas desde cualquier gestor arbitrario, debe admitir internamente el almacenamiento de pares clave-valor arbitrarios, ya que no podemos conocer de antemano los nombres de los proveedores, ni podemos saber qué estructura tendrán los identificadores.

Otros métodos de vinculación

Si un gestor de origen no proporciona un identificador de lugar, puede ser necesario ofrecer algún otro medio de referencia cruzada o coincidencia. Un enfoque podría consistir en hacerlo a través de las coordenadas del lugar: si las coordenadas de un lugar en el gestor de origen son idénticas o similares a las de un lugar en el gestor de destino, existe una alta probabilidad de que se trate del mismo lugar. En este caso, el gestor podría implementar QPlaceManager::matchingPlaces() para aceptar un QPlaceMatchRequest con una clave de parámetro «proximity» y un valor de parámetro que indique la distancia que deben tener dos lugares para que se detecte una coincidencia. Por ejemplo, si un lugar de origen y un lugar de destino se encuentran a menos de 50 m uno del otro, pueden considerarse el mismo lugar.

Sin embargo, en general se recomienda que las referencias cruzadas se implementen mediante identificadores alternativos, tal y como se ha mencionado anteriormente.

Atributos extendidos legibles para el usuario frente a los no legibles para el usuario

Si no se pretende que un atributo sea legible para los usuarios finales, el campo de etiqueta debe dejarse en blanco como indicador de este hecho.

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