장소(C++)

개요

장소 API를 사용하면 사용자가 장소/관심 장소를 검색하고 주소 및 연락처 정보와 같은 세부 정보를 볼 수 있으며, 일부 장소에는 이미지 및 리뷰와 같은 풍부한 콘텐츠가 포함될 수도 있습니다. 또한 장소 API는 장소와 카테고리를 쉽게 관리하여 사용자가 저장하고 삭제할 수 있도록 해줍니다.

장소 정의

장소는 관심 지점이며, 즐겨 찾는 레스토랑, 공원 또는 누군가의 집이 될 수 있습니다. QPlace 객체는 해당 장소에 대한 다양한 정보를 담는 컨테이너 역할을 함으로써 장소를 나타냅니다.

이 정보는 크게 두 가지 분류로 나눌 수 있습니다.

  • 세부 정보
  • 풍부한 콘텐츠

장소 세부정보는 이름, 위치, 연락처 정보 등 장소의 속성으로 구성됩니다. 검색 중에 장소가 반환되면 이러한 세부 정보가 채워집니다. 대역폭을 절약하기 위해 사용자가 관심이 있는 경우 장소별로 장소에 대한 추가 세부 정보를 검색할 수 있는 경우도 있습니다. QPlace::detailsFetched () 함수를 쿼리하여 사용 가능한 모든 세부 정보를 가져왔는지 확인할 수 있으며, 그렇지 않은 경우 QPlaceManager::getPlaceDetails()을 사용하여 검색할 수 있습니다. 검색 중에 정확히 어떤 세부 정보가 채워지고 어떤 세부 정보를 개별적으로 가져와야 하는지는 제공업체마다 다를 수 있습니다. 자세한 내용은 플러그인 설명서를 참조하세요.

장소의 리치 콘텐츠는 이미지, 리뷰, 사설 등의 항목으로 구성됩니다. 리치 콘텐츠 항목이 많을 수 있으므로 장소 세부정보와는 별도로 취급됩니다. QPlaceManager::getPlaceContent ()를 통해 페이징 방식으로 검색할 수 있습니다. 필요한 경우 콘텐츠가 편리한 컨테이너 역할을 할 수 있도록 플레이스에 할당될 수 있습니다.

공통 작업

관리자 초기화하기

모든 장소 기능은 QPlaceManager 인스턴스에 의해 촉진됩니다. QGeoServiceProvider 인스턴스를 만들려면 다음을 지정해야 합니다. QPlaceManager

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

검색 작업을 수행하려면 QPlaceSearchRequest 을 생성하고 검색어 및 검색 센터 등 원하는 검색 매개변수를 설정하기만 하면 됩니다.

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

이 요청은 비동기 작업이므로 요청 완료를 처리할 슬롯이 필요합니다. 핸들러에서 오류가 없는지, 검색 결과 유형이 장소인지 확인합니다. 그렇다면 장소의 핵심 세부 정보를 검색할 수 있습니다. 슬롯이 끝나면 응답은 일회용으로만 사용되므로 삭제합니다.

void handleSearchReply() { if (searchReply->error()==. QPlaceReply::NoError) { for(const QPlaceSearchResult &result:  searchReply->results()) { if (result.type()==. QPlaceSearchResult::PlaceResult) { QPlaceResult placeResult = 결과;                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(); //댓글 삭제searchReply = nullptr; }

참고: 선택한 플러그인 백엔드에 따라 검색 결과에 장소 단위로 가져올 수 있는 추가 세부정보가 있는 장소가 포함될 수 있습니다. 이러한 다른 세부 정보를 가져오려면 장소 세부 정보 가져오기를 참조하세요.

추천

추천은 QPlaceSearchRequest::setRecommendationId()를 통해 장소 ID를 입력하여 검색할 수 있습니다. 지정된 장소와 유사한 장소가 모두 검색됩니다.

페이징

플러그인이 페이징을 지원하는 경우 검색 요청에 제한 매개변수를 제공할 수 있습니다.

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

장소 세부 정보 가져오기

검색 요청에서 반환된 장소에는 가져올 수 있는 추가 세부 정보가 있을 수 있습니다. 다음은 추가 세부 정보가 있는지 확인하는 방법과 추가 정보가 있는 경우 요청하는 방법을 설명합니다.

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

리치 콘텐츠 가져오기

이미지 및 리뷰와 같은 리치 콘텐츠는 관리자를 통해 검색된 다음 필요한 경우 해당 장소에 할당됩니다.

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

아래와 같이 콘텐츠 요청을 처리할 수 있습니다.

void handleImagesReply() { if (contentReply->error()==. QPlaceReply::NoError) { const auto content =  contentReply->content(); for(auto iter = content.cbegin(), end = content.cend(); iter != end; ++iter) {            qDebug() << "Index: " << iter.key();
           QPlaceImage 이미지 = iter.value();            qDebug() << image.url();
            qDebug() << image.mimeType();
        } //또는 인덱스가  관련이 없는 경우(const QPlaceImage &image:  contentReply->content()) {            qDebug() << image.url();
            qDebug() << image.mimeType();
        장소 객체는  이미 가져온 //콘텐츠를  가져올 수 있는 컨테이너 역할을 합니다. place.insertContent(contentReply->request().contentType(),  contentReply->content()); place.setTotalContentCount(contentReply->request().contentType(),  contentReply->totalCount()); }  contentReply->deleteLater(); contentReply = nullptr; }

QPlaceContentReply 의 결과는 QPlaceContent::Collection 이며, 이는 본질적으로 QMap<int, QPlaceContent>라는 점에 유의하는 것이 중요합니다. 이 경우 int 키는 콘텐츠의 인덱스이고 값은 콘텐츠 자체입니다. 콘텐츠가 구현되는 방식에 따라 콘텐츠 유형을 다음과 같이 변환할 수 있습니다.

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

QPlaceContent::Collection 의 사용과 콘텐츠와 하위 유형 간의 변환은 페이징 리뷰, 이미지 및 사설의 메커니즘을 처리하기 위한 코드를 쉽게 공유할 수 있음을 의미합니다.

검색 추천

검색어 추천 검색은 장소 검색을 수행하는 것과 매우 유사합니다. QPlaceSearchRequest 은 장소 검색과 마찬가지로 사용되지만, 검색어가 부분적으로 완성된 문자열로 설정된다는 점만 다를 뿐입니다.

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

그리고 요청이 완료되면 응답을 사용하여 추천어를 표시할 수 있습니다.

void handleSuggestionReply() { if (suggestionReply->error()==. QPlaceReply::NoError) { for(const QString &suggestion:  suggestionReply->suggestions())            qDebug() << suggestion;
    }  suggestionReply->deleteLater(); //댓글 삭제suggestionReply = nullptr; }

장소 저장하기

새 장소의 저장은 다음과 같이 수행되며 QPlace 인스턴스를 생성하고 이름, 주소, 좌표 등의 정보로 채웁니다. 완료되면 QPlaceManager::savePlace()를 호출하여 저장 작업을 시작할 수 있습니다.

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

장소가 저장되면 회신에 해당 장소의 새 식별자가 포함됩니다.

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

    savePlaceReply->deleteLater(); //댓글 삭제savePlaceReply = nullptr; }

이미 존재하는 장소를 저장하려면 QPlace::placeId()에 올바른 식별자를 입력해야 합니다. 그렇지 않으면 비어 있는 경우 새 장소가 생성되거나 식별자가 잘못된 경우 잘못된 장소를 덮어쓰게 됩니다.

장소가 저장되면 QPlaceManager 에서 QPlaceManager::placedAdded() 또는 QPlaceManager::placeUpdated() 시그널을 보낼 수 있습니다. 그러나 관리자가 그렇게 하는지 여부는 제공자에 따라 다르며, 웹 서비스에서 장소에 액세스하는 관리자는 일반적으로 이러한 신호를 보내지 않는 반면 로컬에 저장된 장소에 액세스하는 관리자는 일반적으로 신호를 보냅니다.

주의

장소 API는 현재 core 세부 정보만 저장하도록 설계되었습니다. 이미지나 리뷰와 같은 리치 콘텐츠나 공급업체 및 평점과 같은 세부 정보를 저장하는 것은 지원되지 않는 사용 사례입니다. 일반적으로 관리자는 저장 시 이러한 필드를 무시하고 해당 필드를 채우면 경고 메시지를 표시할 수 있습니다.

장소 API는 다음과 같은 핵심 세부 정보 저장만 지원합니다:

  • 이름
  • 장소 ID
  • 위치
  • 연락처 세부정보
  • 아이콘
  • 카테고리(장소를 설명하는 태그와 같은 이름)
  • 공개 범위

제공업체가 이 중 일부만 지원할 수도 있습니다. 자세한 내용은 플러그인 설명서를 참조하세요.

평점, 확장 속성, 이미지, 리뷰, 사설 및 공급업체와 같은 속성의 저장은 Places API에서 명시적으로 지원되지 않습니다.

관리자 간 저장

관리자 간에 장소를 저장할 때는 몇 가지 주의해야 할 사항이 있습니다. 아이디, 카테고리, 아이콘과 같은 장소의 일부 필드는 관리자별 개체로, 예를 들어 한 관리자의 카테고리가 다른 관리자에서는 인식되지 않을 수 있습니다. 따라서 한 관리자에서 다른 관리자로 장소를 직접 저장하는 것은 불가능합니다.

일반적인 방법은 QPlaceManager::compatiblePlace() 함수를 사용하는 것인데, 이 함수는 장소의 사본을 만들지만 관리자가 지원하는 데이터만 복사합니다. 장소 식별자와 같은 관리자별 데이터는 복사되지 않습니다. 이제 새 사본은 매니저에 저장하기에 적합합니다. 관리자가 대체 식별자를 통한 매칭을 지원하는 경우 대체 식별자 속성이 사본에 할당됩니다( 관리자 간에 장소 매칭하기 참조).

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

장소 제거하기

장소 제거는 다음과 같이 수행됩니다:

/* 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()<< "성공했습니다";  removePlaceReply->deleteLater(); //댓글 삭제removePlaceReply = nullptr; }

장소가 제거되면 QPlaceManager 에서 QPlaceManager::placeRemoved() 신호를 보낼 수 있습니다. 관리자가 그렇게 하는지 여부는 제공업체에 따라 다릅니다. 웹 서비스에서 장소에 액세스하는 관리자는 일반적으로 이러한 신호를 보내지 않지만 로컬에 저장된 장소에 액세스하는 관리자는 일반적으로 신호를 보냅니다.

카테고리 사용

카테고리는 장소를 설명할 수 있는 키워드입니다. 예를 들어 '공원', '극장', '레스토랑' 등이 있습니다. 공원, 공연장, 페리 또는 버스 정류장 등 다양한 카테고리로 장소를 설명할 수 있습니다.

카테고리를 사용하려면 먼저 카테고리를 초기화해야 합니다.

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

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

카테고리가 초기화되면 다음 카테고리 함수를 사용할 수 있습니다.

최상위 카테고리를 검색하려면 QPlaceManager::childCategories() 함수를 사용하지만 카테고리 식별자는 제공하지 않습니다.

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

식별자를 제공하면 카테고리의 하위 카테고리를 검색할 수 있습니다.

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

카테고리 저장하기

다음은 카테고리를 저장하는 방법입니다.

QPlaceCategory fastFood;QPlaceCategory category; category.setName("pizza");/*QPlaceIdReply */ saveCategoryReply =  manager->saveCategory(category); connect(saveCategoryReply, &.QPlaceIdReply::finished, this, &RequestHandler::handleSaveCategoryReply);//부모 식별자를 제공하여 카테고리를 자식으로 저장할 수 있었습니다.saveCategoryReply =  manager->saveCategory(category, fastFood.categoryId()); ... ...void handleSaveCategoryReply() { if (saveCategoryReply->error()== QPlaceReply::NoError) {        qDebug() << "Saved category id =" << saveCategoryReply->id();
    }  saveCategoryReply->deleteLater(); saveCategoryReply = nullptr; }

카테고리가 저장되면 QPlaceManager 에서 QPlaceManager::categoryAdded() 또는 QPlaceManager::categoryUpdated() 신호를 보낼 수 있습니다. 그러나 관리자가 그렇게 하는지 여부는 제공업체에 따라 다르며, 웹 서비스에서 카테고리에 액세스하는 관리자는 일반적으로 이러한 신호를 보내지 않는 반면 로컬에 저장된 카테고리에 액세스하는 관리자는 일반적으로 신호를 보냅니다.

카테고리 제거하기

카테고리 제거는 장소 제거와 매우 유사합니다.

/* 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(); //댓글 삭제removeCategoryReply = nullptr; }

카테고리가 제거되면 QPlaceManager 에서 QPlaceManager::categoryRemoved() 신호를 보낼 수 있습니다. 관리자가 그렇게 하는지 여부는 제공업체에 따라 다릅니다. 웹 서비스에서 장소에 액세스하는 관리자는 일반적으로 이러한 신호를 보내지 않지만 로컬에 저장된 장소에 액세스하는 관리자는 일반적으로 신호를 보냅니다.

관리자 간 장소 매칭

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

매칭 메커니즘은 관리자마다 다를 수 있지만 일반적으로 대체 식별자를 통해 이루어집니다. 저장 프로세스의 일부로, 출처 관리자의 장소 식별자는 대상 관리자의 대체 식별자 속성으로 저장됩니다(자체적인 장소 식별자 체계를 가질 수 있음). 다음 예제에서 출발지 관리자는 'here' QGeoServiceProider이므로 저장 프로세스의 일부로 대상 관리자에 저장된 장소에 대해 대체 식별자 속성인 x_id_here가 설정됩니다( QPlaceManager::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

매칭을 수행하기 위해 QPlaceMatchRequest 을 생성하고 출발지 관리자의 검색 결과를 할당합니다. QPlaceMatchRequest 은 목적지 관리자에서 해당 장소를 반환하는 데 사용됩니다. 또한 키 값 쌍인 매칭 매개변수도 지정합니다. 앞서 언급했듯이 관리자에 따라 다를 수 있지만 일반적으로 키는 대체 ID로 매칭하고 있음을 나타내는 QPlaceMatchRequest::AlternativeId 이며, 이 경우 값은 매칭을 수행하는 데 사용할 대체 식별자 속성을 지정하는 x_id_here가 됩니다.

QPlaceMatchRequest 요청; 요청.setResults(results);QVariantMap 매개변수; 매개변수.삽입(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();
           else                qDebug() << "Place is not a favorite";
        } }  matchReply->deleteLater(); matchReply = nullptr; }

장소의 클래스

데이터 클래스

QGeoAddress

QGeoLocation의 주소를 나타냅니다.

QGeoLocation

위치에 대한 기본 정보를 나타냅니다.

QPlace

장소에 대한 데이터 집합을 나타냅니다.

QPlaceAttribute

장소에 대한 일반 속성 정보를 나타냅니다.

QPlaceCategory

QPlace가 연관될 수 있는 카테고리를 나타냅니다.

QPlaceContactDetail

전화 번호 또는 웹사이트 URL과 같은 연락처 세부 정보를 나타냅니다.

QPlaceContent

장소에 대한 콘텐츠를 보유합니다.

QPlaceIcon

아이콘을 나타냅니다.

QPlaceProposedSearchResult

제안된 검색이 포함된 검색 결과를 나타냅니다.

QPlaceRatings

장소에 대한 평점 정보 보유

QPlaceResult

장소가 포함된 검색 결과를 나타냅니다.

QPlaceSearchResult

검색 결과의 기본 클래스

QPlaceSupplier

장소 또는 장소와 관련된 콘텐츠의 공급자를 나타냅니다.

QPlaceUser

개별 사용자를 나타냅니다.

요청 클래스

QPlaceContentRequest

콘텐츠 요청의 매개변수를 나타냅니다.

QPlaceMatchRequest

한 관리자의 장소가 다른 관리자의 장소와 일치하는 것을 찾는 데 사용됩니다. 요청 매개변수 집합을 나타냅니다.

QPlaceSearchRequest

검색 요청의 매개변수 집합을 나타냅니다.

답장 클래스

QPlaceContentReply

QPlaceManager 인스턴스에 의해 시작된 콘텐츠 검색 작업을 관리합니다.

QPlaceDetailsReply

QPlaceManager 인스턴스에 의해 시작된 장소 세부 정보 가져오기 작업을 관리합니다.

QPlaceIdReply

장소 및 카테고리의 저장 및 제거 작업과 같은 식별자를 반환하는 작업을 관리합니다.

QPlaceMatchReply

QPlaceManager의 인스턴스에 의해 시작된 장소 일치 작업을 관리합니다.

QPlaceReply

QPlaceManager의 인스턴스에 의해 시작된 작업을 관리하고 보다 전문화된 회신을 위한 베이스 클래스의 역할을 합니다.

QPlaceSearchReply

QPlaceManager의 인스턴스에 의해 시작된 장소 검색 작업을 관리합니다.

QPlaceSearchSuggestionReply

QPlaceManager의 인스턴스에 의해 시작된 검색 제안 작업을 관리합니다.

관리자 클래스

QPlaceManager

클라이언트가 특정 백엔드에 저장된 장소에 액세스할 수 있도록 하는 인터페이스입니다.

QPlaceManagerEngine

장소 기능에 대한 액세스를 제공하려는 QGeoServiceProvider 플러그인 구현자를 위한 인터페이스입니다.

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