Lieux (C++)

Vue d'ensemble

L'API Lieux permet aux utilisateurs de découvrir des lieux/points d'intérêt et d'en afficher les détails, tels que l'adresse et les coordonnées ; certains lieux peuvent même avoir un contenu riche, tel que des images et des commentaires. L'API Lieux facilite également la gestion des lieux et des catégories, permettant aux utilisateurs de les enregistrer et de les supprimer.

Définition d'un lieu

Un lieu est un point d'intérêt, qu'il s'agisse d'un restaurant préféré, d'un parc ou du domicile d'une personne. Un objet QPlace représente un lieu en servant de conteneur pour diverses informations sur ce lieu.

Ces informations peuvent être classées en deux grandes catégories

• Les détails
• Contenu riche

Les détails d'un lieu se composent des propriétés du lieu, telles que le nom, la localisation, les informations de contact, etc. Lorsqu'un lieu est renvoyé lors d'une recherche, ces détails sont renseignés. Parfois, afin d'économiser de la bande passante, il existe d'autres détails sur le lieu qui peuvent être récupérés individuellement, lieu par lieu, si l'utilisateur est intéressé. La fonction QPlace::detailsFetched() peut être interrogée pour savoir si tous les détails disponibles ont été récupérés, et si ce n'est pas le cas, QPlaceManager::getPlaceDetails() peut être utilisé pour les récupérer. Les détails qui sont renseignés lors d'une recherche et ceux qui doivent être récupérés individuellement peuvent varier d'un fournisseur à l'autre. Voir la documentation du plugin pour plus de détails.

Le contenu riche d'un lieu se compose d'éléments tels que des images, des critiques et des éditoriaux. Il est possible qu'il y ait de nombreux éléments de contenu riche, c'est pourquoi ils sont traités séparément des détails du lieu. Ils peuvent être récupérés de manière paginée via QPlaceManager::getPlaceContent(). Si nécessaire, le contenu peut être assigné à un lieu afin qu'il puisse servir de conteneur pratique.

Opérations courantes

Initialisation d'un gestionnaire

Toutes les fonctionnalités des lieux sont facilitées par une instance QPlaceManager. Il faut spécifier une adresse QGeoServiceProvider pour créer l'instance QPlaceManager

//The "provider name" is used to select a particular provider
QGeoServiceProvider *provider = new QGeoServiceProvider("provider name");
QPlaceManager *manager = provider->placeManager();

Découverte/Recherche

Pour effectuer une opération de recherche, il suffit de créer un site QPlaceSearchRequest et de définir les paramètres de recherche souhaités, tels qu'un terme et un centre de recherche.

//instantiate request and set parameters
QPlaceSearchRequest searchRequest;
searchRequest.setSearchTerm("ice cream");
searchRequest.setSearchArea(QGeoCircle(QGeoCoordinate(12.34, 56.78)));

//send off a search request
/*QPlaceSearchReply * */ searchReply = manager->search(searchRequest);

//connect a slot to handle the reply
connect(searchReply, &QPlaceSearchReply::finished, this, &RequestHandler::handleSearchReply);

La demande étant une opération asynchrone, nous avons besoin d'un slot pour gérer l'achèvement de la demande. Dans le gestionnaire, nous vérifions qu'il n'y a pas d'erreur et que notre type de résultat de recherche est un lieu. Si c'est le cas, nous pouvons alors récupérer certains détails essentiels du lieu. À la fin du slot, nous supprimons la réponse puisqu'elle n'est destinée qu'à un usage unique.

void handleSearchReply() { if (searchReply->error() == QPlaceReply::NoError) { for(const QPlaceSearchResult &result:  searchReply->results()) { if (result.type() == QPlaceSearchResult::PlaceResult) { QPlaceResult placeResult = result ;                qDebug() << "Name: " << placeResult.place().name();
                qDebug() << "Coordinate " << placeResult.place().location().coordinate().toString();
                qDebug() << "Street: " << placeResult.place().location().address().street();
                qDebug() << "Distance: " << placeResult.distance();
            } }  searchReply->deleteLater() ; //débarrasser de la réponsesearchReply = nullptr ; }

Note : En fonction du plugin backend choisi, les résultats de la recherche peuvent contenir des lieux qui ont d'autres détails qui peuvent être récupérés sur une base de lieu par lieu. Pour récupérer ces autres détails, voir Récupérer les détails d'un lieu.

Recommandations

Les recommandations peuvent être récupérées en fournissant un identifiant de lieu via QPlaceSearchRequest::setRecommendationId(). Tous les lieux similaires au lieu donné sont récupérés.

Pagination

Si le plugin prend en charge la pagination, le paramètre limit peut être fourni à la requête de recherche.

QPlaceSearchRequest searchRequest;
searchRequest.setLimit(15); //specify how many results are to be retrieved.

Récupérer les détails d'un lieu

Un lieu renvoyé par une requête de recherche peut avoir plus de détails qui peuvent être récupérés. La section suivante montre comment vérifier s'il y a d'autres détails et, le cas échéant, comment les demander.

if (!place.detailsFetched()) {
    /*QPlaceDetailsReply * */ detailsReply = manager->getPlaceDetails(place.placeId());
    connect(detailsReply, &QPlaceDetailsReply::finished, this, &RequestHandler::handleDetailsReply);
}
    ...
    ...
void handleDetailsReply() {
    QPlace place;
    if (detailsReply->error() == QPlaceReply::NoError)
        place = detailsReply->place();

    detailsReply->deleteLater(); //discard reply
    detailsReply = nullptr;
}

Récupération d'un contenu riche

Le contenu riche, tel que les images et les commentaires, est récupéré par le gestionnaire puis, si nécessaire, assigné à un lieu.

QPlaceContentRequest request;
request.setContentType(QPlaceContent::ImageType);
request.setPlaceId(place.placeId());
request.setLimit(5);
/*QPlaceContentReply * */ contentReply = manager->getPlaceContent(request);
connect(contentReply, &QPlaceContentReply::finished, this, &RequestHandler::handleImagesReply);

Nous pouvons traiter la demande de contenu comme indiqué ci-dessous.

void handleImagesReply() { if (contentReply->error() ==::NoError) { const auto content = contentReply->control() ==::NoError) QPlaceReply::NoError) { const auto content =  contentReply->content() ; for(auto iter = content.cbegin(), end = content.cend() ; iter != end ; ++iter) {            qDebug() << "Index: " << iter.key();
           QPlaceImage image = iter.value() ;            qDebug() << image.url();
            qDebug() << image.mimeType();
        } //alternativement si les index ne sont pas pertinents for(const QPlaceImage &image:  contentReply->content()) {            qDebug() << image.url();
            qDebug() << image.mimeType();
        L'objet place sert de conteneur où nous pouvons récupérer //contenu qui a déjà été récupéréplace.insertContent(contentReply->request().contentType(),  contentReply->content()) ; place.setTotalContentCount(contentReply->request().contentType(),  contentReply->totalCount()) ; }  contentReply->deleteLater() ; contentReply = nullptr ; }

Il est important de noter que les résultats dans QPlaceContentReply, est un QPlaceContent::Collection qui est essentiellement un QMap<int, QPlaceContent>. La clé int dans ce cas est l'index du contenu, et la valeur est le contenu lui-même. En raison de la manière dont le contenu est implémenté, il est possible de convertir un type de contenu comme suit

QPlaceImage image = content; //provided that 'content' has a type QPlace::ImageType

L'utilisation de QPlaceContent::Collection et la conversion entre le contenu et ses sous-types signifient que le code pour gérer la mécanique de la pagination des revues, des images et des éditoriaux peut être facilement partagé.

Suggestions de recherche

La récupération des suggestions de termes de recherche est très similaire à la recherche d'un lieu. Une adresse QPlaceSearchRequest est utilisée de la même manière qu'une recherche de lieu, à la seule différence que le terme de recherche est défini comme une chaîne de caractères partiellement complétée.

QPlaceSearchRequest request;
request.setSearchTerm("piz");
request.setSearchArea(QGeoCircle(QGeoCoordinate(12.34, 56.78)));
/* QPlaceSearchSuggestion * */suggestionReply = manager->searchSuggestions(request);
connect(suggestionReply, &QPlaceSearchSuggestion::finished, this, &RequestHandler::handleSuggestionReply);

Lorsque la requête est terminée, nous pouvons utiliser la réponse pour afficher les suggestions.

void handleSuggestionReply() { if (suggestionReply->error() == QPlaceReply::NoError) { for(const QString &suggestion:  suggestionReply->suggestions())            qDebug() << suggestion;
    }  suggestionReply->deleteLater() ; //débarrasser de la réponsesuggestionReply = nullptr ; }

Sauvegarde d'un lieu

L'enregistrement d'un nouveau lieu s'effectue de la manière suivante : nous créons une instance QPlace et la remplissons avec des informations telles que le nom, l'adresse et les coordonnées. Une fois cela fait, nous pouvons invoquer QPlaceManager::savePlace() pour commencer une opération d'enregistrement.

QPlace  place;
place.setName( "Fred's Ice Cream Parlor" );

QGeoLocation location;
location.setCoordinate(QGeoCoordinate(12.34, 56.78));

QGeoAddress address;
address.setStreet("111 Nother Street");
    ...
location.setAddress(address);
place.setLocation(location);

/* QPlaceIdReply * */savePlaceReply = manager->savePlace(place);
connect(savePlaceReply, &QPlaceIdReply::finished, this, &RequestHandler::handleSavePlaceReply);

Lorsqu'un lieu est enregistré, la réponse contient le nouvel identifiant de ce lieu.

void handleSavePlaceReply() { if (savePlaceReply->error() == QPlaceReply::NoError)        qDebug() << savePlaceReply->id();

    savePlaceReply->deleteLater() ; //débarrasser de la réponsesavePlaceReply = nullptr ; }

Notez que pour sauvegarder un lieu déjà existant, l'adresse QPlace::placeId() doit être remplie avec l'identifiant correct. Sinon, un nouveau lieu sera créé s'il est vide ou le mauvais lieu sera écrasé si l'identifiant est incorrect.

Lorsqu'un lieu est sauvegardé, QPlaceManager peut émettre les signaux QPlaceManager::placedAdded() ou QPlaceManager::placeUpdated(). Cependant, le fait qu'un gestionnaire le fasse ou non est spécifique au fournisseur, les gestionnaires accédant à des lieux à partir d'un service web n'émettront généralement pas ces signaux alors que les gestionnaires accédant à des lieux stockés localement le feront.

Mise en garde

L'API Lieux est actuellement conçue pour enregistrer uniquement les détails de core. L'enregistrement d'un contenu riche tel que des images et des avis ou de détails tels que le fournisseur et l'évaluation n'est pas un cas d'utilisation pris en charge. En règle générale, un gestionnaire ignore ces champs lors de l'enregistrement et peut produire un message d'avertissement s'ils sont renseignés.

L'API Lieux ne prend en charge que l'enregistrement des détails de base suivants :

• nom
• identifiant du lieu
• lieu
• coordonnées
• icône
• catégories (noms semblables à des tags pour décrire un lieu)
• champ de visibilité

Il est possible que les fournisseurs ne prennent en charge qu'un sous-ensemble de ces éléments. Voir la documentation du plugin pour plus de détails.

L'enregistrement de propriétés telles que l'évaluation, les attributs étendus, les images, les critiques, les éditoriaux et les fournisseurs n'est explicitement pas pris en charge par l'API Lieux.

Sauvegarde entre gestionnaires

Lors de la sauvegarde de lieux entre gestionnaires, il y a quelques points à prendre en compte. Certains champs d'un lieu, tels que l'identifiant, les catégories et les icônes, sont des entités spécifiques à un gestionnaire ; par exemple, les catégories d'un gestionnaire peuvent ne pas être reconnues dans un autre. Il n'est donc pas possible de sauvegarder un lieu directement d'un gestionnaire à l'autre.

L'approche classique consiste à utiliser la fonction QPlaceManager::compatiblePlace(), qui crée une copie d'un lieu, mais ne copie que les données prises en charge par le gestionnaire. Les données spécifiques au gestionnaire, telles que l'identifiant du lieu, ne sont pas copiées. La nouvelle copie peut maintenant être enregistrée dans le gestionnaire. Si le gestionnaire prend en charge la correspondance par des identifiants alternatifs, un attribut d'identifiant alternatif est attribué à la copie (voir Correspondance des lieux entre gestionnaires).

//result retrieved from a different manager)
QPlace place = manager->compatiblePlace(result.place());
saveReply = manager->savePlace(place);

Suppression d'un lieu

La suppression d'un lieu s'effectue comme suit :

/* QPlaceIdReply * */removePlaceReply =  manager->removePlace(place.placeId()) ; connect(removePlaceReply, &QPlaceIdReply::finished, this, &RequestHandler::handleRemovePlaceReply) ; ... ...void handleRemovePlaceReply() { if (removePlaceReply->error() == QPlaceReply::NoError)        qDebug() << "Removal of place identified by"
                <<  removePlaceReply->id()<< "was successful";  removePlaceReply->deleteLater() ; //débarrasser de la réponseremovePlaceReply = nullptr ; }

Lorsqu'un lieu est supprimé, le QPlaceManager peut émettre le signal QPlaceManager::placeRemoved(). La question de savoir si un gestionnaire le fait est spécifique au fournisseur. Les gestionnaires qui accèdent à des lieux à partir d'un service web n'émettent généralement pas ces signaux, alors que les gestionnaires qui accèdent à des lieux stockés localement le font.

Utilisation des catégories

Les catégories sont des mots-clés qui peuvent décrire un lieu. Par exemple, "parc", "théâtre", "restaurant". Un lieu peut être décrit par plusieurs catégories : il peut s'agir d'un parc, d'une salle de concert, d'un ferry ou d'un arrêt de bus.

Pour utiliser les catégories, il faut d'abord les initialiser.

/* QPlaceReply * */initCatReply =  manager->initializeCategories() ; connect(initCatReply, &QPlaceReply::finished, this, &RequestHandler::handleInitCatReply) ; ... ...void handleInitCatReply() { if (initCatReply->error() == QPlaceReply::NoError)        qDebug() << "Categories initialized";
   autre        qDebug() << "Failed to initialize categories";

    initCatReply->deleteLater() ; initCatReply = nullptr ; }

Une fois que les catégories ont été initialisées, nous pouvons utiliser ces fonctions de catégorie.

• QPlaceManager::childCategories()
• QPlaceManager::category()
• QPlaceManager::parentCategoryId()
• QPlaceManager::childCategoryIds() ;

Pour récupérer les catégories de premier niveau, nous utilisons la fonction QPlaceManager::childCategories() mais nous ne fournissons pas d'identifiant de catégorie.

const QList<QPlaceCategory> topLevelCategories =  manager->childCategories() ;for(const QPlaceCategory &category: topLevelCategories)    qDebug() << category.name();

Si nous fournissions un identifiant, nous pourrions récupérer les enfants d'une catégorie.

QList<QPlaceCategory> childCategories = manager->childCategories(pizza.categoryId());

Sauvegarde d'une catégorie

La procédure suivante montre comment sauvegarder une catégorie

QPlaceCategory fastFood ;QPlaceCategory category ; category.setName("pizza") ;/*QPlaceIdReply */ saveCategoryReply =  manager->saveCategory(category) ; connect(saveCategoryReply, &QPlaceIdReply::finished, this, &RequestHandler::handleSaveCategoryReply) ;//nous aurions pu enregistrer une catégorie en tant qu'enfant en fournissant un identifiant de parent.saveCategoryReply =  manager->saveCategory(category, fastFood.categoryId()) ; ... ...void handleSaveCategoryReply() { if (saveCategoryReply->error() == QPlaceReply::NoError) {        qDebug() << "Saved category id =" << saveCategoryReply->id();
    }  saveCategoryReply->deleteLater() ; saveCategoryReply = nullptr ; }

Lorsqu'une catégorie est sauvegardée, le site QPlaceManager peut émettre les signaux QPlaceManager::categoryAdded() ou QPlaceManager::categoryUpdated(). Cependant, le fait qu'un gestionnaire le fasse ou non est spécifique au fournisseur, les gestionnaires accédant à des lieux à partir d'un service web n'émettront généralement pas ces signaux alors que les gestionnaires accédant à des lieux stockés localement les émettront.

Suppression d'une catégorie

La suppression d'une catégorie est très similaire à la suppression d'un lieu

/* QPlaceIdReply * */removeCategoryReply =  manager->removeCategory(place.placeId()) ; connect(removeCategoryReply, &QPlaceIdReply::finished, this, &RequestHandler::handleRemoveCategoryReply) ; ... ...void handleRemoveCategoryReply() { if (removeCategoryReply->error() == QPlaceReply::NoError)        qDebug() << "Removal of category identified by"
                <<  removeCategoryReply->id()<< "was successful";  removeCategoryReply->deleteLater() ; //discount replyremoveCategoryReply = nullptr ; }

Lorsqu'une catégorie est supprimée, le QPlaceManager peut émettre le signal QPlaceManager::categoryRemoved(). La question de savoir si un gestionnaire le fait est spécifique au fournisseur. Les gestionnaires qui accèdent à des lieux à partir d'un service web n'émettent généralement pas ces signaux, alors que les gestionnaires qui accèdent à des lieux stockés localement le font.

Correspondance des lieux entre gestionnaires

Il peut arriver que vous souhaitiez vérifier si les lieux d'un gestionnaire correspondent à ceux d'un autre gestionnaire. Une telle situation peut se présenter lorsqu'un gestionnaire fournit un accès en lecture seule aux lieux (gestionnaire d'origine) tandis qu'un autre gestionnaire en lecture seule (gestionnaire de destination) est utilisé pour sauvegarder les favoris sélectionnés dans le premier. Lors d'une recherche dans le gestionnaire d'origine, on peut vouloir savoir quels lieux ont été "favorisés" dans le gestionnaire de destination et éventuellement afficher un nom de favori personnalisé plutôt que le nom d'origine.

Le mécanisme de correspondance peut varier d'un gestionnaire à l'autre, mais il est généralement réalisé au moyen d'un identifiant alternatif. Dans le cadre du processus d'enregistrement, l'identifiant de lieu du gestionnaire d'origine est enregistré en tant qu'attribut d'identifiant alternatif dans le gestionnaire de destination (qui peut avoir son propre schéma d'identifiant de lieu). Dans l'exemple suivant, le gestionnaire d'origine est le QGeoServiceProider 'here', donc dans le cadre du processus de sauvegarde, un attribut d'identifiant alternatif, x_id_here, est défini pour le lieu sauvegardé dans le gestionnaire de destination (lorsque QPlaceManager::compatiblePlace() est appelé).

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

Pour effectuer la mise en correspondance, nous créons un site QPlaceMatchRequest et lui attribuons les résultats de la recherche du gestionnaire d'origine. Le QPlaceMatchRequest sera utilisé dans le gestionnaire de destination pour renvoyer les lieux correspondants. Nous spécifions également des paramètres de correspondance qui sont des paires clé-valeur. Comme indiqué précédemment, cela peut varier en fonction du gestionnaire, mais la clé est généralement QPlaceMatchRequest::AlternativeId pour indiquer que nous effectuons la correspondance par identifiant alternatif, la valeur dans ce cas serait x_id_here qui spécifie l'attribut d'identifiant alternatif que nous utilisons pour effectuer la correspondance.

QPlaceMatchRequest request ; request.setResults(results) ;QVariantMap parameters ; parameters.insert(QPlaceMatchRequest::AlternativeId, "x_id_here") ; request.setParameters(parameters) ; matchReply =  manager->matchingPlaces(request) ; ... ...void matchHandler() { if (matchReply->error() == QPlaceReply::NoError) { const auto places =  matchReply->places() ; for(const QPlace &place: places) { if (place ! = QPlace())                qDebug() << "Place is a favorite with name" << place.name();
           autre                qDebug() << "Place is not a favorite";
        } }  matchReply->deleteLater() ; matchReply = nullptr ; }

Classes dans les lieux

Classes de données

Classes de demandes

Classes de réponses

Classes de gestionnaires